rustdoc: Allow multiple references to a single footnote by a4lg · Pull Request #140434 · rust-lang/rust (original) (raw)

Multiple references to a single footnote is a part of GitHub Flavored Markdown syntax (although not explicitly documented as well as regular footnotes, it is implemented in GitHub's fork of CommonMark) and not prohibited by rustdoc.

cf. https://github.com/github/cmark-gfm/blob/587a12bb54d95ac37241377e6ddc93ea0e45439b/test/extensions.txt#L762-L780

However, using it makes multiple sup elements with the same id attribute, which is invalid per the HTML specification.

Still, not only this is a valid GitHub Flavored Markdown syntax, this is helpful on certain cases and actually tested (accidentally) in tests/rustdoc/footnote-reference-in-footnote-def.rs.

This commit keeps track of the number of references per footnote and gives unique ID to each reference.
It also emits all back links from a footnote to its references as "↩" (return symbol) plus a numeric list in superscript.

As a known limitation, it assumes that all references to a footnote are rendered (this is not always true if a dangling footnote has one or more references but considered a reasonable compromise).

Also note that, this commit is designed so that no HTML changes will occur unless multiple references to a single footnote is actually used.

Background

A failure is detected on the CI process of #140389, which adopted stdarch submodule with PR rust-lang/stdarch#1779.

As you see in the screenshot of that stdarch PR, it uses multiple references to a single footnote to simplify showing various platform/version-specific notes (this is far more important than x86 because there are no architectural, fine-grained feature detection methods on RISC-V and hence feature detection is highly platform/version-specific).

And I thought this kind of references are allowed because:

  1. rustdoc does not reject such links and
  2. One of the tests tests/rustdoc/footnote-reference-in-footnote-def.rs contains multiple references to a single footnote [^a].

...until I encounter a linkchecker failure (ran on CI).

Proposal

Of course, rejecting such references might be an option but this PR attempts to resolve the issue by explicitly allowing multiple references to a single footnote by:

  1. Generating unique id attribute per a reference to a footnote and
  2. Emitting all back links from a footnote as a return symbol plus a numeric list in superscript.

Note that, this PR is designed so that no HTML changes will occur unless multiple references to a single footnote is actually used.

Known Limitation

To simplify the implementation, it just keeps track of the number of references per footnote and assumes that all references to footnotes are rendered. This is usually true but may not be always true if a reference is inside a footnote and that footnote is dangling (in this case, broken links (that won't cause any action when clicked/touched) will be generated but otherwise fine).

I also didn't use atomics but was it necessary?

Screenshot

This is a screenshot of this PR plus rust-lang/stdarch#1779, showing how back links are rendered.
You can see the differences in the footnotes 1, 2 and 5.

Screenshot of stdarch PR 1779 with this PR (footnote part)

Design Considerations / Options

I just used 1-origin numbers for back links from a footnote but if this is confusing, using alphabet-based list "a", "b"..."z", "aa", "ab"... might be an option like in Wikipedia. The reason I didn't do this (in the first proposal) is because back links are visually distinct than Wikipedia and seems easy to make distinction between regular references to footnotes due to the return symbol "↩" (Wikipedia: caret "^" is used).

History

Version 1 (2025-04-29)

The initial proposal.

Version 2 and 3 (2025-04-30)

Excluding the rebase, they only change the commit message (mainly grammar fixes)
and the code is unchanged from the version 1.

Version 4 (2025-05-06)

No changes in the source code.

Version 5 (2025-08-14)