rustdoc: Allow multiple references to a single footnote

[a4lg]

Multiple references to a single footnote is not prohibited by rustdoc but causes multiple sup elements with the same id attribute, which is invalid per the HTML specification.

However, such references are helpful on certain cases and actually tested in tests/rustdoc/footnote-reference-in-footnote-def.rs.

This commit keeps track of the number of references per footnote and gives unique ID per reference to a footnote.
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.

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.

[rustbot]

r? @notriddle

rustbot has assigned @notriddle.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

[notriddle]

I'm satisfied with the known limitation on nested, hidden footnotes.

Since this is a UI-visible change, I'll cc the frontend team about it.

@rfcbot poll appearance

[rfcbot]

Team member @notriddle has asked teams: T-rustdoc-frontend, for consensus on:

appearance

• @GuillaumeGomez
• @camelid
• @jsha
• @notriddle

[GuillaumeGomez]

It's really cool, nicely done!

[a4lg]

With all due respect, if time constraints allow, I would greatly appreciate it if this PR could be merged within the version 1.88 cycle (before beta branching occurs). That would allow re-applying platform-specific guide documentation (RISC-V) on stdarch in the version 1.89 cycle.
Thank you for your consideration.