Documenter.jl: Multiple identical footnotes
Right now, Documenter errors when multiple bodies for a footnote is encountered. This is problematic, when, for instance, rendering docstrings, where each docstring may contain identical references to the same article with identically labelled footnotes. Manually relabelling these for Documenter to work "fixes" it, but it would be better if the footnotes were either collected at the bottom, or the anchor tag to each footnote was given a unique reference based on its section/function name.
This came up in: https://github.com/JuliaLang/julia/pull/23679
dalum
All 2 comments
I would lean towards making the footnotes in each docstring be a separate group, as opposed to collecting them into a single catalogue as is done now. It would mean that you couldn't refer to footnotes defined in other docstrings, nor refer to a non-docstring footnote within a docstring anymore. As you say, the anchor would have to be updated to have a docstring-specific prefix.
Alternatively, we could also do some more sophisticated scoping with the footnotes, but I am not sure whether the complexity would be worth it.
mortenpi
on 27 Sep 2017
Referring to a footnote in another docstring is probably not good practice, unless they would automatically be pulled into the docstring. help?> would just show a reference to a footnote that the user would have no idea what was. Even then, Documenter would also fail if the referenced footnote did not appear on the same page in the rendered documentation, as far as I can tell.
dalum
on 27 Sep 2017
Related issues
halirutan
路
4Comments
SimonEnsemble
路
3Comments
nalimilan
路
4Comments
dkarrasch
路
5Comments
carlobaldassi
路
5Comments
Most helpful comment
Referring to a footnote in another docstring is probably not good practice, unless they would automatically be pulled into the docstring.
help?>would just show a reference to a footnote that the user would have no idea what was. Even then, Documenter would also fail if the referenced footnote did not appear on the same page in the rendered documentation, as far as I can tell.