Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Footnotes are squished together by rustdoc when there's no empty line between them #100638

Closed
CJKay opened this issue Aug 16, 2022 · 7 comments · Fixed by #120443
Closed

Footnotes are squished together by rustdoc when there's no empty line between them #100638

CJKay opened this issue Aug 16, 2022 · 7 comments · Fixed by #120443
Labels
A-rustdoc-ui Area: Rustdoc UI (generated HTML) C-bug Category: This is a bug. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.

Comments

@CJKay
Copy link

CJKay commented Aug 16, 2022

Problem

Footnote lines, when written on adjacent lines, squish into a single footnote:

//! [^1]: Footnote A.
//! [^2]: Footnote B.
//! [^3]: Footnote C.

Screenshot 2022-08-16 at 18 39 09

Steps

  1. Copy-paste the following snippet at the top of a new module:

    //! Reference to footnotes A[^1], B[^2] and C[^3].
    //!
    //! [^1]: Footnote A.
    //! [^2]: Footnote B.
    //! [^3]: Footnote C.
  2. Run cargo doc.

  3. Observe that the footnotes have been incorrectly rendered as a single footnote.

Possible Solution(s)

No response

Notes

One workaround is to separate the footnotes with empty lines:

//! [^1]: Footnote A.
//! 
//! [^2]: Footnote B.
//! 
//! [^3]: Footnote C.

It's not pretty, though.

Version

cargo 1.64.0-nightly (b1dd22e66 2022-07-09)
release: 1.64.0-nightly
commit-hash: b1dd22e668af5279e13a071ad4b17435bd6bfa4c
commit-date: 2022-07-09
host: x86_64-apple-darwin
libgit2: 1.4.2 (sys:0.14.2 vendored)
libcurl: 7.79.1 (sys:0.4.55+curl-7.83.1 system ssl:(SecureTransport) LibreSSL/3.3.6)
os: Mac OS 12.5.0 [64-bit]
@CJKay CJKay added the C-bug Category: This is a bug. label Aug 16, 2022
@Eh2406
Copy link
Contributor

Eh2406 commented Aug 16, 2022

Transferring to Rust as it is an issue with doc generation.

@Eh2406 Eh2406 transferred this issue from rust-lang/cargo Aug 16, 2022
@ehuss
Copy link
Contributor

ehuss commented Aug 16, 2022

I think this is somewhat working as intended. Footnote definitions need to be separated by blank lines.

That is not ideal, and I think pulldown-cmark/pulldown-cmark#20 is the closest thing tracking this issue.

@GuillaumeGomez
Copy link
Member

This is the expected behaviour from commonmark as you can see here.

Closing then.

@CJKay
Copy link
Author

CJKay commented Aug 23, 2022

This is the expected behaviour from commonmark as you can see here.

Closing then.

Hi @GuillaumeGomez, CommonMark does not support footnotes at all. RustDoc is very explicit that it does, so the behaviour of RustDoc's footnotes should probably be based on whatever library it uses for Markdown parsing rather than actual CommonMark.

You can see from this simple example that CommonMark does not support footnotes:

Reference to footnote A[^1].

[^1]: Footnote A.
<p>Reference to footnote A[^1].</p>
<p>[^1]: Footnote A.</p>

But CommonMark with "extensions" does:

<p>Hello, World<a href="#fn1" class="footnote-ref" id="fnref1"
role="doc-noteref"><sup>1</sup></a>!</p>
<section id="footnotes" class="footnotes footnotes-end-of-document"
role="doc-endnotes">
<hr />
<ol>
<li id="fn1"><p>The world is big!<a href="#fnref1" class="footnote-back"
role="doc-backlink">↩︎</a></p></li>
</ol>
</section>

@GuillaumeGomez
Copy link
Member

Oh I see, my apologies. Reopening the issue then.

@ChrisDenton ChrisDenton added the needs-triage-legacy Old issue that were never triaged. Remove this label once the issue has been sufficiently triaged. label Jul 16, 2023
@fmease fmease added T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. A-rustdoc-ui Area: Rustdoc UI (generated HTML) and removed needs-triage-legacy Old issue that were never triaged. Remove this label once the issue has been sufficiently triaged. labels Jan 25, 2024
@fmease fmease changed the title Footnotes are squished together by cargo doc when there's no empty line between them Footnotes are squished together by rustdoc when there's no empty line between them Jan 25, 2024
@fmease
Copy link
Member

fmease commented Jan 25, 2024

Triage: Still an issue.

@GuillaumeGomez
Copy link
Member

Taking a look.

GuillaumeGomez added a commit to GuillaumeGomez/rust that referenced this issue Jan 28, 2024
GuillaumeGomez added a commit to GuillaumeGomez/rust that referenced this issue Jan 28, 2024
matthiaskrgr added a commit to matthiaskrgr/rust that referenced this issue Jan 28, 2024
…ement, r=fmease

Fixes footnote handling in rustdoc

Fixes rust-lang#100638.

You can now declare footnotes like this:

```rust
//! Reference to footnotes A[^1], B[^2] and C[^3].
//!
//! [^1]: Footnote A.
//! [^2]: Footnote B.
//! [^3]: Footnote C.
```

r? `@notriddle`
fmease added a commit to fmease/rust that referenced this issue Jan 29, 2024
…ement, r=fmease

Fixes footnote handling in rustdoc

Fixes rust-lang#100638.

You can now declare footnotes like this:

```rust
//! Reference to footnotes A[^1], B[^2] and C[^3].
//!
//! [^1]: Footnote A.
//! [^2]: Footnote B.
//! [^3]: Footnote C.
```

r? ``@notriddle``
GuillaumeGomez added a commit to GuillaumeGomez/rust that referenced this issue Jan 29, 2024
@bors bors closed this as completed in f35504d Jan 30, 2024
rust-timer added a commit to rust-lang-ci/rust that referenced this issue Jan 30, 2024
Rollup merge of rust-lang#120443 - GuillaumeGomez:footnote-def-improvement, r=fmease

Fixes footnote handling in rustdoc

Fixes rust-lang#100638.

You can now declare footnotes like this:

```rust
//! Reference to footnotes A[^1], B[^2] and C[^3].
//!
//! [^1]: Footnote A.
//! [^2]: Footnote B.
//! [^3]: Footnote C.
```

r? `@notriddle`
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-rustdoc-ui Area: Rustdoc UI (generated HTML) C-bug Category: This is a bug. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.
Projects
None yet
Development

Successfully merging a pull request may close this issue.

6 participants