Thread: [Docutils-develop] [docutils:bugs] Re: #450 0.18: New HTML markup for footnotes is difficult to sty (Page 2)

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 422-6466

Immediate response on the CSS styling issue -- patch version 5 wraps all adjacent footnotes into one `aside` so that CSS grid can be used (because of the wrapping, you need to use `aside.footnote > div {display: contents;}` to be able to assign grid column positions to the `fn-label` and `fn-text` classes -- ideally we'd use subgrids but there's no support beyond FireFox. @pradyun would you be able to test if this works for Furo? (I haven't updated tests or HISTORY)

On the issue of semantics -- I think grouping adjacent footnotes into a single container makes sense, as it allows for multiple blocks of footnotes in one document (say one per major section). For the HTML writer, I think we should aim to allow the end user to style as he prefers -- with sensible defaults in `minimal`, `plain`, and `responsive`. 

We would ideally be able to lay this out as we saw fit, but the CSS specification, and the implementation of the CSS specification by browser engines are limiting factors that mean we have to make unfortunate compromises.

An alternate patch is also attached, which only changes the outer wrapper and doesn't use the `.fn-(label|text)` elements. This allows using the CSS grid by e.g.:
```css
aside.footnote * {
    grid-column: 2;
}
aside.footnote .label,
aside.footnote .backrefs {
    grid-column: 1;
}
```

I think these two approaches are the most pragmatic that balance functionality in CSS against semantics of the HTML -- I would welcome thoughts on either implementation. Once (if) we have a winner, I will do the final polishing steps to prepare it as a proper patch.

A

Attachments:

- [0001-Alternate-patch-for-CSS-footnote-styling.patch](https://sourceforge.net/p/docutils/bugs/_discuss/thread/af593fcd69/937a/460a/81bc/attachment/0001-Alternate-patch-for-CSS-footnote-styling.patch) (6.0 kB; application/octet-stream)
- [0001-Wrap-footnote-labels-and-text-for-easier-CSS-styling.patch](https://sourceforge.net/p/docutils/bugs/_discuss/thread/af593fcd69/937a/460a/81bc/attachment/0001-Wrap-footnote-labels-and-text-for-easier-CSS-styling.patch) (36.0 kB; application/octet-stream)

---

** [bugs:#450] 0.18: New HTML markup for footnotes is difficult to stylise**

**Status:** open
**Labels:** footnotes 
**Created:** Sun Jun 05, 2022 08:28 PM UTC by Pradyun Gedam
**Last Updated:** Wed Jun 08, 2022 02:27 PM UTC
**Owner:** nobody

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>
```

---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

Thread: [Docutils-develop] [docutils:bugs] Re: #450 0.18: New HTML markup for footnotes is difficult to sty (Page 2)

docutils-develop