docutils-develop — For developer discussions of the implementation.

[Docutils-develop] [docutils:bugs] #450 0.18: New HTML markup for footnotes is difficult to stylise

[Alan <ai...@us...>]

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


---

** [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:** Tue Jun 07, 2022 11:48 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.

[Docutils-develop] [docutils:bugs] Re: #450 0.18: New HTML markup for footnotes is difficult to stylise

[Pradyun G. <pr...@us...>]

You're right. I'm not sure why, but looks like it came in ~4 hours after I sent it. :)

https://sourceforge.net/p/docutils/bugs/450/#6bdd/ddc7


---

** [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:** Tue Jun 07, 2022 05:26 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.

[Docutils-develop] [docutils:bugs] Re: #450 0.18: New HTML markup for footnotes is difficult to stylise

[Pradyun G. <pr...@us...>]

On Tue, Jun 7, 2022 at 7:21 PM "Günter Milde" <mi...@us...>
wrote:

> can this go into 0.19
>
> I am hesitant to introduce an incompatible API change unannounced and in
> the last minute .
> It has the potential to break custom style sheets.
>
> Could you elaborate on this? There was an incompatible API change in the
0.18 release -- why can't the same be done in 0.19?



---

** [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:** Tue Jun 07, 2022 05:26 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.

[Docutils-develop] [docutils:bugs] Re: #450 0.18: New HTML markup for footnotes is difficult to stylise

[Günter M. <mi...@us...>]

> Fun, SourceForge does not allow users to reply via email.

It does. This is an email reply.

I don't know what kind of pre-conditions and spam-checks apply, though.


---

** [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:** Tue Jun 07, 2022 05:26 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.

[Docutils-develop] [docutils:bugs] #450 0.18: New HTML markup for footnotes is difficult to stylise

[Pradyun G. <pr...@us...>]

@aa-turner -- the patch would be an improvement over status quo. See image for what can be achieved with the new markup, which is an improvement over 0.18 but not at parity with 0.17.

In other words, for preserving the style in Furo, more is needed.

As @milde pointed out, Furo uses a grid layout on `dl`, which means it is able to keep all the footnotes aligned even when there's different width among various labels+references. This would require moving away from each footnote living in its own `aside` to having a single aside containing multiple footnotes (which is what 0.17 had).


Attachments:

- [Screenshot 2022-06-07 at 22.47.06.png](https://sourceforge.net/p/docutils/bugs/_discuss/thread/af593fcd69/937a/attachment/Screenshot%202022-06-07%20at%2022.47.06.png) (348.7 kB; image/png)


---

** [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:** Tue Jun 07, 2022 02:22 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.

Re: [Docutils-develop] [docutils:bugs] Re: #450 0.18: New HTML markup for footnotes is difficult to stylise

[Adam T. <aat...@ou...>]

>>> due to a broken link to minimal.css.

>> This is one of the problems I had during the reposurgeon conversion --
>> these four CSS files in `input/` seem to have broken symlinks in the
>> SVN index or some other oddity going on.

> It should work in a repository checkout, though.
> Please tell whether this is the case.

Using a fresh checkout:

```ps1con
PS S:\Development\docutils_svn_test> svn checkout https://svn.code.sf.net/p/docutils/code/trunk .
Checked out revision 9063.
PS S:\Development\docutils_svn_test> cd .\docutils\test\functional\input\data
PS S:\Development\docutils_svn_test\docutils\test\functional\input\data> dir | findstr /i css
-a---          07/06/2022    13:49             57 html4css1.css
-a---          07/06/2022    13:49             57 math.css
-a---          07/06/2022    13:49             60 minimal.css
-a---          07/06/2022    13:49             58 plain.css
-a---          07/06/2022    13:49             63 responsive.css
PS S:\Development\docutils_svn_test\docutils\test\functional\input\data> Get-ChildItem "*.css" | ?{$_.Attributes} | select FullName,ReparsePoint

FullName                                                                            ReparsePoint
--------                                                                            ------------
S:\Development\docutils_svn_test\docutils\test\functional\input\data\html4css1.css
S:\Development\docutils_svn_test\docutils\test\functional\input\data\math.css
S:\Development\docutils_svn_test\docutils\test\functional\input\data\minimal.css
S:\Development\docutils_svn_test\docutils\test\functional\input\data\plain.css
S:\Development\docutils_svn_test\docutils\test\functional\input\data\responsive.css
```

The files exist on disk, but are not valid links in Windows.

Trying again on WSL:

```shell
/mnt/s/Development/docutils_svn_wsl$ svn checkout https://svn.code.sf.net/p/docutils/code/trunk .
Checked out revision 9063.
/mnt/s/Development/docutils_svn_wsl$ cd ./docutils/test/functional/input/data
/mnt/s/Development/docutils_svn_wsl/docutils/test/functional/input/data$ find . -name "*.css"
./html4css1.css
./math.css
./minimal.css
./plain.css
./responsive.css
/mnt/s/Development/docutils_svn_wsl/docutils/test/functional/input/data$ [ -L minimal.css ] && [ -e minimal.css ] || exit 1
(base) adam@Gimbals:/mnt/s/Development/docutils_svn_wsl/docutils/test/functional/input/data$
```

So perhaps this is just a Windows issue -- but if the web server has disabled symlinks, then it would also report errors. Perhaps we should make it a carbon copy rather than a symlink, and add a test that the two files are identical?

A

[Docutils-develop] [docutils:bugs] Re: #450 0.18: New HTML markup for footnotes is difficult to stylise

[Adam T. <aa-...@us...>]

@pradyun -- sorry, for clarity does my patch no. 4 allow you to solve the issue in Furo or is more needed?

@milde -- from a CSS styling perspective, I will say I found it challenging working with the footnotes structure in v0.18, and I believe the patch makes it easier for end users. (Note many end users haven't yet updated their themes and CSS styles to v0.18 as we just released Sphinx 5 with support -- this is probably why the issue was raised now rather than earlier).

A


---

** [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:** Tue Jun 07, 2022 02:19 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.

[Docutils-develop] [docutils:bugs] Re: #450 0.18: New HTML markup for footnotes is difficult to stylise

[Adam T. <aa-...@us...>]

> Does docutils announce upcoming releases and their changes somewhere before the release is made? 

We try to: https://docutils.sourceforge.io/RELEASE-NOTES.html#future-changes and https://docutils.sourceforge.io/HISTORY.html#changes-since-0-18-1

A


---

** [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:** Tue Jun 07, 2022 02:14 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.

[Docutils-develop] [docutils:bugs] #450 0.18: New HTML markup for footnotes is difficult to stylise

[Pradyun G. <pr...@us...>]

Fun, SourceForge does not allow users to reply via email.

> We don't know whether the patch solves the OP's problem. The rendering in https://pradyunsg.me/furo/kitchen-sink/generic/#footnotes cannot be reproduced easily even with the patch, as every footnote has its own grid (as opposed to one grid for the list of footnotes in the example).

That's correct. It does not.

In my example, `<div class="footnote-label">` functionally replaces the `dt` and the content div replaces the `dd` from 0.17. It changes the `footnote` to being a wrapper around the divs, which come in pairs. In effect, mirroring the structure from before (with an `aside` rather than `dl`, and divs rather than `dt` and `dd`).

> I am hesitant to introduce an incompatible API change unannounced and in the last minute .
It has the potential to break custom style sheets.

"incompatible API change" seems like a weak reason for hesitancy for accepting a patch, since an incompatible API change in 0.18 (compared to 0.17) is literally what caused this issue.

Does docutils announce upcoming releases and their changes somewhere *before* the release is made? If not, I can tell you that end users will not care if the change was made 1 hour, 1 week, 18 weeks before the release. :)



---

** [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:** Tue Jun 07, 2022 01:51 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.

[Docutils-develop] [docutils:bugs] #450 0.18: New HTML markup for footnotes is difficult to stylise

[Günter M. <mi...@us...>]

> can this go into 0.19

I am hesitant to introduce an incompatible API change unannounced and in the last minute . 
It has the potential to break custom style sheets.

We don't know whether the patch solves the OP's problem. The rendering in https://pradyunsg.me/furo/kitchen-sink/generic/#footnotes cannot be reproduced easily even with the patch, as every footnote has its own grid (as opposed to one grid for the list of footnotes in the example).

The varying number of elements in every footnote `<aside>` element can easily be rendered on a 3-column grid if you assign them to grid columns. See attachment. (Tested with `rst2html5 --stylesheet-path=minimal.css,gridfoot.css footnotes.txt`.)

OTOH, a layout with one column for footnote label and backlinks and a second for the footnote text becomes problematic if there are many backlinks
(as, e.g. in https://docutils.sourceforge.io/docs/user/config.html#override). 
This may be the reason, why html4css1 puts the backlinks in the column with the footnote text.


Attachments:

- [gridfoot.css](https://sourceforge.net/p/docutils/bugs/_discuss/thread/af593fcd69/6bdd/attachment/gridfoot.css) (334 Bytes; text/css)


---

** [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:** Mon Jun 06, 2022 10:03 AM 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.

Re: [Docutils-develop] [docutils:bugs] Re: #450 0.18: New HTML markup for footnotes is difficult to stylise

[Guenter M. <mi...@us...>]

>> due to a broken link to minimal.css.

> This is one of the problems I had during the reposurgeon conversion --
> these four CSS files in `input/` seem to have broken symlinks in the
> SVN index or some other oddity going on.

It should work in a repository checkout, though. 
Please tell whether this is the case.

[Docutils-develop] [docutils:bugs] #450 0.18: New HTML markup for footnotes is difficult to stylise

[Pradyun G. <pr...@us...>]

The markup rendering for Sourceforge seems to have eaten an `_`.


~~~
https://github.com/pradyunsg/furo/blob/d955850a89310a932ecab4e84cba0c20371a6a33/src/furo/assets/styles/content/_footnotes.sass#L12
~~~


---

** [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:** Sun Jun 05, 2022 11:49 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.

[Docutils-develop] [docutils:bugs] Re: #450 0.18: New HTML markup for footnotes is difficult to stylise

[Adam T. <aa-...@us...>]

Attached is a fourth patch that fixes two remaining inconsistencies I noticed. Günter -- sorry, the third patch I uploaded is not visually identical, but this one should be.

Pradyun -- your `footnotes.sass` link doesn't seem to work.

> due to a broken link to minimal.css.

This is one of the problems I had during the reposurgeon conversion -- these four CSS files in `input/` seem to have broken symlinks in the SVN index or some other oddity going on.

A


Attachments:

- [0001-Wrap-footnote-labels-and-text-for-easier-CSS-styling.patch](https://sourceforge.net/p/docutils/bugs/_discuss/thread/af593fcd69/1602/baa0/attachment/0001-Wrap-footnote-labels-and-text-for-easier-CSS-styling.patch) (33.8 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:** Sun Jun 05, 2022 11:09 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.

[Docutils-develop] [docutils:bugs] #450 0.18: New HTML markup for footnotes is difficult to stylise

[Pradyun G. <pr...@us...>]

https://pradyunsg.me/furo/kitchen-sink/generic/#footnotes has the 0.17 rendering.

https://github.com/pradyunsg/furo/blob/d955850a89310a932ecab4e84cba0c20371a6a33/src/furo/assets/styles/content/footnotes.sass#L12 has the CSS, basically using the CSS Grid model to stylise the content to be aligned correctly (written in Sass for an indentation based syntax).

FYI: https://docutils.sourceforge.io/test/functional/expected/standalone_rst_html5.html#footnotes seems to be unstylised, due to a broken link to minimal.css.


---

** [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:** Sun Jun 05, 2022 09:51 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.

[Docutils-develop] [docutils:bugs] Re: #450 0.18: New HTML markup for footnotes is difficult to stylise

[Adam T. <aa-...@us...>]

@milde -- checking my patch in FireFox 101, I see no visual difference between `standalone_rst_html5.html#footnotes` before and after applying the patch.

I believe I was fairly thorough in updating the CSS, although I might've gotten something wrong -- I would appreciate if you had a quick look / check please?

A


---

** [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:** Sun Jun 05, 2022 09:42 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.

[Docutils-develop] [docutils:bugs] Re: #450 0.18: New HTML markup for footnotes is difficult to stylise

[Günter M. <mi...@us...>]

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

Unfortunately, this would break the default footnote styling ("minimal.css")
as well as the styles building on it ("plain.css" and "responsive.css").
Try the "standalone_rst_html5.html" test sample
to see the intended footnote rendering.

If you gave more details of what you want to achieve and/or examples of
the CSS we may find a solution.


---

** [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:** Sun Jun 05, 2022 09:42 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.

[Docutils-develop] [docutils:bugs] #450 0.18: New HTML markup for footnotes is difficult to stylise

[Adam T. <aa-...@us...>]

A third update, I've now updated tests and CSS to follow the new structure.

A


Attachments:

- [0001-Wrap-footnote-labels-and-text-for-easier-CSS-styling.patch](https://sourceforge.net/p/docutils/bugs/_discuss/thread/af593fcd69/32b4/attachment/0001-Wrap-footnote-labels-and-text-for-easier-CSS-styling.patch) (33.4 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:** Sun Jun 05, 2022 08:52 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.

[Docutils-develop] [docutils:bugs] #450 0.18: New HTML markup for footnotes is difficult to stylise

[Adam T. <aa-...@us...>]

Updated patch, I fixed missing line breaks.

A


Attachments:

- [0001-Wrap-footnote-labels-and-text-for-easier-CSS-styling.patch](https://sourceforge.net/p/docutils/bugs/_discuss/thread/af593fcd69/3922/attachment/0001-Wrap-footnote-labels-and-text-for-easier-CSS-styling.patch) (1.7 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:** Sun Jun 05, 2022 08:49 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.

[Docutils-develop] [docutils:bugs] #450 0.18: New HTML markup for footnotes is difficult to stylise

[Adam T. <aa-...@us...>]

This is actually pretty easy to fix -- I agree it is currently not ideal.

Patch and diff attached. @milde -- can this go into 0.19 please? I don't know if you heard back fron Engelbert on when he's going to make the release.

```diff
diff --git a/docutils/docutils/writers/_html_base.py b/docutils/docutils/writers/_html_base.py
index 19e394657..d0d2d58e8 100644
--- a/docutils/docutils/writers/_html_base.py
+++ b/docutils/docutils/writers/_html_base.py
@@ -951,7 +951,6 @@ class HTMLTranslator(nodes.NodeVisitor):
                                        role="note"))

     def depart_footnote(self, node):
@@ -1104,8 +1102,6 @@ class HTMLTranslator(nodes.NodeVisitor):
                          for (i, ref) in enumerate(backrefs, 1)]
             self.body.append('<span class="backrefs">(%s)</span>\n'
                              % ','.join(backlinks))
+        self.body.append('</div>\n')  # closer for <div class="fn-text">
         self.body.append('</aside>\n')

     def visit_footnote_reference(self, node):
@@ -1081,6 +1082,7 @@ class HTMLTranslator(nodes.NodeVisitor):

     # footnote and citation labels:
     def visit_label(self, node):
+        self.body.append('<div class="fn-label">')
         self.body.append('<span class="label">')
         self.body.append('<span class="fn-bracket">[</span>')
         # footnote/citation backrefs:
@@ -1102,6 +1104,8 @@ class HTMLTranslator(nodes.NodeVisitor):
                          for (i, ref) in enumerate(backrefs, 1)]
             self.body.append('<span class="backrefs">(%s)</span>\n'
                              % ','.join(backlinks))
+        self.body.append('</div>')
+        self.body.append('<div class="fn-text">')

     def visit_legend(self, node):
         self.body.append(self.starttag(node, 'div', CLASS='legend'))
```

A


Attachments:

- [0001-Wrap-footnote-labels-and-text-for-easier-CSS-styling.patch](https://sourceforge.net/p/docutils/bugs/_discuss/thread/af593fcd69/82d6/attachment/0001-Wrap-footnote-labels-and-text-for-easier-CSS-styling.patch) (1.7 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:** Sun Jun 05, 2022 08:28 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.

[Docutils-develop] [docutils:bugs] #450 0.18: New HTML markup for footnotes is difficult to stylise

[Pradyun G. <pr...@us...>]

---

** [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:** Sun Jun 05, 2022 08:28 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.

[Docutils-develop] [docutils:patches] Re: #186 Modernise packaging

[Adam T. <aa-...@us...>]

I would suggest `rst2s5.py`, `rstpep2html`, `rst2odt_prepstyles`,  `rst2odt`, and `rst2pseudoxml` for removal (leaving html/4/5, latex/xetex, man, xml).

I think we could announce the deprecation in RELEASE-NOTES & docs/usr/tools and change usage examples in the documentation now, for inclusion in 0.19, as long as we don't affect runtime behaviour?

A


---

** [patches:#186] Modernise packaging**

**Status:** open
**Group:** None
**Created:** Fri Dec 31, 2021 03:16 AM UTC by Adam  Turner
**Last Updated:** Mon May 30, 2022 05:15 PM UTC
**Owner:** nobody
**Attachments:**

- [0001-Use-flit-and-pyproject.toml.patch](https://sourceforge.net/p/docutils/patches/186/attachment/0001-Use-flit-and-pyproject.toml.patch) (12.2 kB; application/octet-stream)
- [0002-Use-entry-points.patch](https://sourceforge.net/p/docutils/patches/186/attachment/0002-Use-entry-points.patch) (20.7 kB; application/octet-stream)
- [0003-update-docs-etc-after-packaging-changes.patch](https://sourceforge.net/p/docutils/patches/186/attachment/0003-update-docs-etc-after-packaging-changes.patch) (49.3 kB; application/octet-stream)


Hi,

I had a go at modernising the packaging stack. `setup.py` based invocations have been deprecated (https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html), and setuptools may remove them in the future. 

This takes the opportunity to move to a PEP 621 based declarative config, and also fixes a longstanding TODO item about providing script wappers for the frontend tools on windows, by migrating them to entry points.

I've updated install and development docs with the new guidance, and updated references to the frontend tools to remove `.py`, given they are now installed as proper scripts.

Hope this is appreciated -- happy to make revisions etc to help getting this merged.

A


---

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

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

[Docutils-develop] [docutils:feature-requests] #83 Support SVG images in LaTeX

[Günter M. <mi...@us...>]

- **summary**: Support SVT images in LaTeX --> Support SVG images in LaTeX



---

** [feature-requests:#83] Support SVG images in LaTeX**

**Status:** open
**Group:** Default
**Created:** Sat Oct 09, 2021 12:05 AM UTC by Local State
**Last Updated:** Wed Jun 01, 2022 09:25 PM UTC
**Owner:** nobody


Hi there, this is Local State.

## Motivation
The current `Image` directive is not enough for svg files. Using `img` tag loses interactivities, and the width, and height can't be applied for svg files directly. It's better to use `style="width:50%"` instead. 

## 2 New Options
I'm hoping there could be 2 new options for `Image` directive.
    
   1. `tag`
        This would determine the html tag used to render the image. The default value would be `img`, and we could also use `object`, `iframe` and `embed` as alternatives. Currently, all images are rendered with `img` tag, which loses some interactivities (e.g., the text in svg file). We could avoid this by using `object` tag. I see there are some similar work in `html4css1` about `object_image_types`.  
        
        Example:
        ```
        <img src="a.png" width="50%" alt="alt msg">`
        <object data="a.png" style="width:50%">alt msg</object>
        <iframe src="a.png" width="50%" title="alt msg"></iframe>
        <embed src="a.png" width="50%">`
        ```
        
   2. `embed`
        If enabled, this option would embed the image into the html file using base64 encoding.  
        While I see there is already the if sentence in the `visit_image` function.
        ```
        if self.settings.embed_images or ('embed' in node):
        ```
        The `embed_images` could be set from command-line or setting, but I can't find how to satisfy the latter condition, since any node doesn't seem to have `embed` attribute. Could anyone tell me how to enable it? If we can't, then it's necessary to add the `embed` option, so that we could choose to embed one particular image or not. 
        Especially, I notice there exist a `todo` item for svg embedding. I'd like to implement it if possible. But the first option is still in demand, because most times we don't want our html files to be so large and need separate svg files.

##  Potential bugs
 
 svg files under `<img>` tag can't correctly render height and width if svg viewbox information is not contained in the file. It might be better to set the height and width in `style` indirectly.

##  Contribution
 I would like to fix and implement all these things if possible. But I'm not quite familiar with SourceForge and don't know how to submit a PR like what we do in github.


---

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

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

[Docutils-develop] [docutils:feature-requests] Re: #41 Not all Node instances have the source and line attributes set

[Günter M. <mi...@us...>]

>Also potentially [bugs:#145] 

No, "#145 error report with paragraph start line instead of error-line" can/must be solved independently.


---

** [feature-requests:#41] Not all Node instances have the source and line attributes set**

**Status:** open
**Group:** sandbox
**Created:** Sun Jan 12, 2014 07:21 PM UTC by Brecht Machiels
**Last Updated:** Wed Jun 01, 2022 09:50 PM UTC
**Owner:** nobody


The source and line attributes of Node elements are not set for all types of elements. For example, these attributes never get set on bulleted or enumerated list nodes. Other elements (such as literal block) don't have source set depending on the context.


---

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

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

[Docutils-develop] [docutils:feature-requests] Re: #41 Not all Node instances have the source and line attributes set

[Adam T. <aa-...@us...>]

Also potentially [bugs:#145]


---

** [feature-requests:#41] Not all Node instances have the source and line attributes set**

**Status:** open
**Group:** sandbox
**Created:** Sun Jan 12, 2014 07:21 PM UTC by Brecht Machiels
**Last Updated:** Wed Jun 01, 2022 09:48 PM UTC
**Owner:** nobody


The source and line attributes of Node elements are not set for all types of elements. For example, these attributes never get set on bulleted or enumerated list nodes. Other elements (such as literal block) don't have source set depending on the context.


---

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

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

[Docutils-develop] [docutils:bugs] #449 Image has no line number with an `:alt:` attribute

[Günter M. <mi...@us...>]

- **status**: open --> closed-duplicate



---

** [bugs:#449] Image has no line number with an `:alt:` attribute**

**Status:** closed-duplicate
**Created:** Tue May 31, 2022 05:20 PM UTC by Adam  Turner
**Last Updated:** Wed Jun 01, 2022 09:41 PM UTC
**Owner:** nobody


Reproducer:

```pycon
>>> print(core.publish_doctree(".. image:: placeholder_image.jpg")[0].line)
1
>>> print(core.publish_doctree(".. image:: placeholder_image.jpg\n   :alt: blah")[0].line)
None
```

This is rather odd! Originally found whilst debugging a Sphinx issue.

A


---

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.