#450 0.18: New HTML markup for footnotes is difficult to stylise

[Pradyun Gedam]

Docutils 0.18 changed the HTML markup for footnotes/citations generated for rst documents. This changed markup is significantly more difficult to stylise with CSS, in ways that was possible with Docutils 0.17. This has negatively affected HTML themes for Sphinx, since the Sphinx 5 release allows using docutils 0.18, which is preferentially installed by pip.

The reasons for this boils down to an inconsistent number of elements inside each aside.

1. It's not possible use CSS grid layouts sanely, with this setup.
2. Even if you added multiple rules based on number of elements in the section, it's not possible to know what the 2nd element might be -- which balloons the complexity+size of the stylesheet, if it tries to accomodate for this.

It is theoretically possible to stylise this but it would be on the order of 100s of lines of CSS to get this right, compared to ~20 with 0.17.

Would it be possible to change this markup, to wrap the label & backrefs in a div and to wrap the content paragraphs in a separate div as well? This would make it possible to stylise this content in ways that were feasible with 0.17, with significantly less complexity in the stylesheets.

---

Sources:

[some content that references these footnotes]

.. [1] A footnote contains body elements, consistently indented by at
   least 3 spaces.

   This is the footnote's second paragraph.

.. [#label] Footnotes may be numbered, either manually (as in [1]_) or
   automatically using a "#"-prefixed label.  This footnote has a
   label so it can be referred to from multiple places, both as a
   footnote reference ([#label]_) and as a hyperlink reference
   (label_).

0.17 output HTML:

<dl class="footnote brackets">
  <dt class="label" id="id6"><span class="brackets">1</span><span class="fn-backref">(<a href="#id1">1</a>,<a
        href="#id7">2</a>)</span></dt>
  <dd>
    <p>A footnote contains body elements, consistently indented by at
      least 3 spaces.</p>
    <p>This is the footnote’s second paragraph.</p>
  </dd>
  <dt class="label" id="label"><span class="brackets">2</span><span class="fn-backref">(<a href="#id3">1</a>,<a
        href="#id8">2</a>)</span></dt>
  <dd>
    <p>Footnotes may be numbered, either manually (as in <a class="footnote-reference brackets" href="#id6"
        id="id7">1</a>) or
      automatically using a “#”-prefixed label. This footnote has a
      label so it can be referred to from multiple places, both as a
      footnote reference (<a class="footnote-reference brackets" href="#label" id="id8">2</a>) and as a hyperlink
      reference
      (<a class="reference internal" href="#label">label</a>).</p>
  </dd>
</dl>

0.18 output HTML:

<aside class="footnote brackets" id="id6" role="note">
  <span class="label"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></span>
  <span class="backrefs">(<a href="#id1" role="doc-backlink">1</a>,<a href="#id7" role="doc-backlink">2</a>)</span>
  <p>A footnote contains body elements, consistently indented by at
    least 3 spaces.</p>
  <p>This is the footnote’s second paragraph.</p>
</aside>
<aside class="footnote brackets" id="label" role="note">
  <span class="label"><span class="fn-bracket">[</span>2<span class="fn-bracket">]</span></span>
  <span class="backrefs">(<a href="#id3" role="doc-backlink">1</a>,<a href="#id8" role="doc-backlink">2</a>)</span>
  <p>Footnotes may be numbered, either manually (as in <a class="footnote-reference brackets" href="#id6" id="id7"
      role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a>) or
    automatically using a “#”-prefixed label. This footnote has a
    label so it can be referred to from multiple places, both as a
    footnote reference (<a class="footnote-reference brackets" href="#label" id="id8" role="doc-noteref"><span
        class="fn-bracket">[</span>2<span class="fn-bracket">]</span></a>) and as a hyperlink reference
    (<a class="reference internal" href="#label">label</a>).</p>
</aside>

The suggested change to the markup is to generate something like (using only the first aside for this demo):

<aside class="footnote brackets" id="id6" role="note">
  <div class="footnote-label">
    <span class="label"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></span>
    <span class="backrefs">(<a href="#id1" role="doc-backlink">1</a>,<a href="#id7" role="doc-backlink">2</a>)</span>
  </div>
  <div class="footnote-content">
    <p>A footnote contains body elements, consistently indented by at
      least 3 spaces.</p>
    <p>This is the footnote’s second paragraph.</p>
  </div>
</aside>

[Günter Milde]

Specifying the "footnote-reference" value on the wrapper
element would also allow to get rid of some redundancy in the HTML source
by not replicating the "brackets" or "superscript" class value on every
individual footnote element in future (after preparing the style-sheets and
an advance warning).

[Adam Turner]

@pradyun -- please may you test this patch & see if it allows you parity styling in furo with 0.17 Docutils?

A

[Alan]

Should the roles become doc-footnote and doc-noteref?
See https://www.w3.org/TR/dpub-aria-1.1/
Alan Isaac

[Günter Milde]

"The footnote element is used for labeled notes that provide additional context to a passage of text (footnotes or endnotes)." The Docutils Document Tree.
Due to this ambiguity, the note role was chosen over "doc-footnote" or "doc-endnotes".

The doc-noteref is used for the marker "appearing as a superscripted number or symbol in the main body of text." In Docutils this is the footnote_reference element.

[Alan]

Must the role be part of the element definition? It would be nice to stay close to the digital-publishing standard. (Aside: in principle, multiple roles are possible.)

[Günter Milde]

The role attribute value must match the actual role of the element in the document.

The doc-footnote role is only for representing individual notes that occur within the body of a work. For collections of notes that occur at the end of a section, see doc-endnotes."
-- doc-footnote

The HTML writer can only guess whether a Docutils <footnote> element is a footnote or part of a "collection of notes at the end of a work or a section within it"
doc-endnodes.
"Authors MUST NOT declare elements with the role doc-footnote within the endnotes" [ibid].

[Alan]

Hmm, yes. Then it seems like this should be communicated by an option (e.g., --use-endnotes).

Staying close to the digital-publishing standards is a high payoff.

[Günter Milde]

by an option (e.g., --use-endnotes).

Rather by the discussed new directive to collect footnotes.

Staying close to the digital-publishing standards is a high payoff.

Can you elaborate on the adantages of "Digital Publishing WAI-ARIA" roles over the generic WAI-ARIA?

[Alan]

Well ... I guess I would throw this back at you. How much support for technical reports and ebooks do the docutils developers wish to provide? I consider those outputs natural for docutils. And I'd love to be able to turn on an epub option and get <aside epub:type="footnote" role="doc-footnote"> (assuming such pairing is still allowed). Anyway, I find the doc roles particularly appropriate for the output of docutils.

[Günter Milde]

Must the role be part of the element definition?

Current praxis is to use the <footnote> element for both:
a) individual notes that occur within the body of a work,
b) collections of notes that occur at the end of a section.
The Digital Publishing WAI-ARIA Module 1.0 explicitely says that doc-footnote
is only for usage case a).

Despite this, I announced the change to "doc-footnote", assuming that
1. this is the more frequent use and a better match to the element's name,
2. a possible future "select footnotes" directive (see TODO.txt) may serve for use case b).

[Günter Milde]

Fixed in [r9081].

[Günter Milde]

Fixed in Docutils 0.19.
Thank you for reporting.