docutils-develop — For developer discussions of the implementation.

Re: [Docutils-develop] Docutils 0.19 Release

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

Dear Engelbert,

[Günter]
> The default "html" writer change is still open/undecided
> (no problem in 0.19 if envisaged for 2.0).

> This means we should be clear for release 0.19b.

Are you in favour of making a 0.19.0b1 release? The only potential unresolved items are:

* announcing a date for the switch to HTML5-by-default (Günter has abstained, I am in favour of announcing the date as 2.0)
* bugs#450 [1]_

On the latter, Günter and I have converged towards a single similar patch, so that will hopefully be resolved soon. On the former, I think you would be the casting vote!

Please let me know your thoughts,
Thanks,
Adam

_[1]: https://sourceforge.net/p/docutils/bugs/450/

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

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

@milde your approach makes a lot more sense! The attached builds on your patch -- I renamed `footnotes` to `footnote-list` for consistency with `citation-list` and as I think the risk for single-character typos would be high.

I also added a CHANGES entry.

A


Attachments:

- [0001-CSS-footnote-styling-footnote-list-version.patch](https://sourceforge.net/p/docutils/bugs/_discuss/thread/af593fcd69/937a/460a/81bc/e203/ecc3/attachment/0001-CSS-footnote-styling-footnote-list-version.patch) (4.3 kB; application/octet-stream)


---

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

**Status:** open
**Created:** Sun Jun 05, 2022 08:28 PM UTC by Pradyun Gedam
**Last Updated:** Fri Jun 10, 2022 03: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.

Re: [Docutils-develop] I/O uses default encoding argument

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

> However, in cases of user-supplied input, this is an API change.
> We can fix the cases in the tests now but need due process for cases where
> changes may lead to different behaviur for users.

> Suggestion:

> * backport Python 3.11 behaviour to docutils.io:
>   “use locale encoding when encoding="locale" is passed”.

> * announce change of default encoding to UTF-8

> * keep encoding attribute unspecified for now when reading input
>   specified by users or 3rd-party code.

This seems a sensible way forwards. The updated patch set does (1) and (2) and warns on unspecified encoding input in the ``docutils.io.(Input|Output)`` classes.

> Consistent naming in Docutils code (not only latex2e.py) and
> documentation is good.

The updated patch set renames everything to my reccomendation below. (It is a larger change than originally envisaged, so it is 8 patches -- alternativley formatted on the web [1]_.

> What is the motivation for 'utf-8'?

The name of the encoding is UTF-8 [2]_ [3]_. I propose using UTF-8 (uppercase) in documentation and prose text and utf-8 (lowercase) in code (If you'd prefer consistency in case I would pick lowercase everywhere). 

A

_[1]: https://github.com/AA-Turner/docutils/pull/15 and https://github.com/AA-Turner/docutils/pull/15.patch
_[2]: https://www.ietf.org/rfc/rfc3629.html
_[3]: https://encoding.spec.whatwg.org/#names-and-labels

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

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

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

Rather by the discussed new directive to [collect footnotes](https://docutils.sourceforge.io/docs/dev/todo.html#footnote-citation-gathering).

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

Can you elaborate on the adantages of "Digital Publishing WAI-ARIA" roles over the generic [WAI-ARIA](https://www.w3.org/TR/wai-aria-1.1)?



---

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

**Status:** open
**Created:** Sun Jun 05, 2022 08:28 PM UTC by Pradyun Gedam
**Last Updated:** Fri Jun 10, 2022 02:00 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

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

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

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


---

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

**Status:** open
**Created:** Sun Jun 05, 2022 08:28 PM UTC by Pradyun Gedam
**Last Updated:** Fri Jun 10, 2022 01:40 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...>]

I don't believe that the "backrefs" should be grouped as part of the footnote label: 
it complicates the structure and handicaps styles similar to the  [Wikipedia references](https://en.wikipedia.org/wiki/Odessa#References). Therefore I prefer the simpler, "alternate-patch".

The "ids" and the ARIA role must be kept on the individual footnotes. (Did you test the footnote links?)
When also keeping the "footnote" and "brackets"/"superscript" class values on the individual notes, minimal.css keeps working. Only tuftig.css needs adaption.
The attached patch is a proof of concept.


Attachments:

- [html5-footnotes.patch](https://sourceforge.net/p/docutils/bugs/_discuss/thread/af593fcd69/937a/460a/81bc/e203/attachment/html5-footnotes.patch) (2.8 kB; text/x-patch)


---

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

**Status:** open
**Created:** Sun Jun 05, 2022 08:28 PM UTC by Pradyun Gedam
**Last Updated:** Fri Jun 10, 2022 12:13 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...>]

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

> The doc-footnote role is only for representing individual notes that occur within the body of a work. For collections of notes that occur at the end of a section, see doc-endnotes."
-- [doc-footnote](https://www.w3.org/TR/dpub-aria-1.1/#doc-footnote)

The HTML writer can only guess whether a Docutils `<footnote>` element is a footnote or part of a "collection of notes at the end of a work or a section within it" 
[doc-endnodes](https://www.w3.org/TR/dpub-aria-1.1/#doc-endnotes). 
"Authors MUST NOT declare elements with the role doc-footnote within the endnotes" [ibid].


---

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

**Status:** open
**Created:** Sun Jun 05, 2022 08:28 PM UTC by Pradyun Gedam
**Last Updated:** Fri Jun 10, 2022 11:13 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.

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

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

- **labels**: footnotes --> 



---

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

**Status:** open
**Created:** Sun Jun 05, 2022 08:28 PM UTC by Pradyun Gedam
**Last Updated:** Thu Jun 09, 2022 08:07 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] #448 `Element.index()` returns incorrect results for `Text` nodes

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

- **status**: open --> open-fixed
- **Comment**:

Fixed in [r9067]. 
Thank you for report and contributions.



---

** [bugs:#448] `Element.index()` returns incorrect results for `Text` nodes**

**Status:** open-fixed
**Created:** Tue May 24, 2022 11:38 PM UTC by Adam  Turner
**Last Updated:** Tue May 31, 2022 11:36 AM UTC
**Owner:** nobody


This captures the bug behind `branches/index-bug`. I'm not sure the general case of `index` is worth fixing, as `Text` nodes are a special case, but it might have implications for `Node.findall`.


```python
>>> from docutils import nodes
>>> tree = nodes.Element()
>>> blah1 = nodes.Text("blah")
>>> blah2 = nodes.Text("blah")
>>> tree += [nodes.Text("node1"), blah1, blah2]
>>> print(tree.pformat())
<Element>
    node1
    blah
    blah

>>> tree[tree.index(blah2)] is blah2
False
>>> tree[tree.index(blah2)] is blah1
True
```

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.

[Docutils-develop] [docutils:bugs] Re: #451 Deprecate PEP 263 coding slugs support

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

> Python 3 uses utf-8 as the encoding for Python source files, there is
> no longer a compelling use-case for the support, which adds complexity
> to the IO implementation.

I see still a reason to keep (and properly document) a way to specify the
encoding of an rST source in the document itself.

Use cases: 

* A collection of files, where one file for whatever reason must be in a
  different encoding. Compilation with "buildhtml.py".
  
* Documents in an 8-bit or 16-bit encoding intended for compilation 
  anywhere. Avoids shipping a separate configuration file.
  
The "coding slug" might become obsoleted by a more generic "in-document configuration" 
(cf. TODO item [misc.settings directive](https://docutils.sourceforge.io/docs/dev/todo.html#misc-settings)
but this is still a long way off.
  


---

** [bugs:#451] Deprecate PEP 263 coding slugs support**

**Status:** open
**Created:** Thu Jun 09, 2022 10:48 PM UTC by Adam  Turner
**Last Updated:** Thu Jun 09, 2022 10:48 PM UTC
**Owner:** nobody
**Attachments:**

- [0001-Deprecate-PEP-263-coding-slugs.patch](https://sourceforge.net/p/docutils/bugs/451/attachment/0001-Deprecate-PEP-263-coding-slugs.patch) (5.5 kB; application/octet-stream)


Python 3 uses utf-8 as the encoding for Python source files, there is no longer a compelling use-case for the support, which adds complexity to the IO implementation.

I propose deprecating support for removal in 1.0, but 2.0 might be a better option.

Support was added in [r4506].

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.

Re: [Docutils-develop] I/O uses default encoding argument

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

On 2022-06-09, Adam Turner wrote:

>> This means for every instance of open() without explicit encoding, we have
>> to decide whether to use "ascii", "utf-8", or `io.locale_encoding`
>> (the latter is equivalent to the value "locale" introduced in Py 3.10).

> My strong suggestion would be that Docutils moves towards defaulting to
> UTF-8 for all encodings (of course keeping the option to supply
> explicit other encodings) -- it is compatible with US-ASCII and is the
> safest sane default. (PEP 686's motivation section [1]_ has some colour
> on this).

However, in cases of user-supplied input, this is an API change.
We can fix the cases in the tests now but need due process for cases where
changes may lead to different behaviur for users.

Suggestion:

* backport Python 3.11 behaviour to docutils.io:
  “use locale encoding when encoding="locale" is passed”.

* announce change of default encoding to UTF-8

* keep encoding attribute unspecified for now when reading input
  specified by users or 3rd-party code.


>>Unfortunately, the patch mixes added "encoding" arguments with the>change of "utf8" to "utf-8" in many cases.

> An updated patch attached (The only 'utf8' -> 'utf-8' were in the
> LaTex2e writer, but you're right it is better to keep the changes
> distinct.)

Consistent naming in Docutils code (not only latex2e.py) and
documentation is good.

What is the motivation for 'utf-8'?

* Python's codecs module uses "utf_8"
  (with aliases U8, UTF, utf8, cp65001 and normalizing case and "-/_").

* In LaTeX, it's named "utf8",

* `locale` reports "UTF-8"

* PEP 8 uses uppercase:
  "Code in the core Python distribution should always use UTF-8".

* The `codecs  documentation`__ uses ``encoding='utf-8'`` when documenting
  default arguments for encode() and decode().

__ https://docs.python.org/3/library/codecs.html

Thanks,

Günter

Re: [Docutils-develop] I/O uses default encoding argument

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

> This means for every instance of open() without explicit encoding, we have
> to decide whether to use "ascii", "utf-8", or `io.locale_encoding`
> (the latter is equivalent to the value "locale" introduced in Py 3.10).

My strong suggestion would be that Docutils moves towards defaulting to UTF-8 for all encodings (of course keeping the option to supply explicit other encodings) -- it is compatible with US-ASCII and is the safest sane default. (PEP 686's motivation section [1]_ has some colour on this).

>Unfortunately, the patch mixes added "encoding" arguments with the>change of "utf8" to "utf-8" in many cases.

An updated patch attached (The only 'utf8' -> 'utf-8' were in the LaTex2e writer, but you're right it is better to keep the changes distinct.)

A

_[1]: https://peps.python.org/pep-0686/#motivation

[Docutils-develop] [docutils:bugs] #451 Deprecate PEP 263 coding slugs support

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

---

** [bugs:#451] Deprecate PEP 263 coding slugs support**

**Status:** open
**Created:** Thu Jun 09, 2022 10:48 PM UTC by Adam  Turner
**Last Updated:** Thu Jun 09, 2022 10:48 PM UTC
**Owner:** nobody
**Attachments:**

- [0001-Deprecate-PEP-263-coding-slugs.patch](https://sourceforge.net/p/docutils/bugs/451/attachment/0001-Deprecate-PEP-263-coding-slugs.patch) (5.5 kB; application/octet-stream)


Python 3 uses utf-8 as the encoding for Python source files, there is no longer a compelling use-case for the support, which adds complexity to the IO implementation.

I propose deprecating support for removal in 1.0, but 2.0 might be a better option.

Support was added in [r4506].

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.

Re: [Docutils-develop] I/O uses default encoding argument

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

On 2022-06-09, Adam Turner wrote:

> Using Python 3.10's ``-X warn_default_encoding`` argument to Python, we
> can see a large number of places where the default encoding is used. On
> posix systems this is now UTF-8 following PEP 538 [1], but on Windows a
> non-unicode codepage can be used.

> The attached patch fixes the majority of these instances.

Thank you for the patch. After reading PEP 597, I agree that we should
specify the intended encoding where appropriate.

This means for every instance of open() without explicit encoding, we have
to decide whether to use "ascii", "utf-8", or `io.locale_encoding`
(the latter is equivalent to the value "locale" introduced in Py 3.10).

Unfortunately, the patch mixes added "encoding" arguments with the
change of "utf8" to "utf-8" in many cases.

* Is there a reason to prefer 'utf-8'?

  We have currently 36 instances of 'utf8' vs. 19 instances of 'utf-8'
  in the library code and tests.
  
  The "codecs" documentation names "utf8" and "utf-8" as aliases for "utf_8".
  
* Separating the encoding name normalization from new arguments would
  make it easier to check whether the new-specified encoding is correct.
  
Günter  

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

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

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

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

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

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

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

A


Attachments:

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


---

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

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


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

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

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

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

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

---

Sources:

```
[some content that references these footnotes]

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

   This is the footnote's second paragraph.

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

```

0.17 output HTML:

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

0.18 output HTML:

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

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

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


---

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

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

[Docutils-develop] Python 3.7 test failure -- ``test_CLI``

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

(Re-sending to the correct list)

test_CLI fails on Python 3.7 as "utf-8" is capitalised in the actual output. 
Attached is a patch to fix the failure.

I noticed it the test also fails on Windows, so I've included new a patch for that too (the regular expression should match a forward or a backwards stroke character).

A

[Docutils-develop] I/O uses default encoding argument

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

(Re-sending to the correct list)

Using Python 3.10's ``-X warn_default_encoding`` argument to Python, we can see a large number of places where the default encoding is used. On posix systems this is now UTF-8 following PEP 538 [1], but on Windows a non-unicode codepage can be used.

The attached patch fixes the majority of these instances.

A

[1]: https://peps.python.org/pep-0538/

Re: [Docutils-develop] missing symlinks (was: #450 0.18: New HTML markup for footnotes is difficult to stylise)

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

> OTOH, the "math.css" is present, although it is a symlink as well!
> Maybe the "public checkout" does not create new files (or new symlinks)
> without maintainer interaction?

> Does anyone know how the "public checkout" under
> https://docutils.sourceforge.io/test/
> https://docutils.sourceforge.io/docutils/
> works, where it is set up and how we can fix it?

I read various pages in the SourceForge documentation -- there are some that document the project website [1]_ and the remote shell access [2]_ but I couldn't find anything on the auto-updating. I expect there is a script somewhere that runs ``svn checkout​`` and uploads the results -- it doesn't overwrite, as there is obsolete content in the ``docutils/`` directory [3]_.

I looked into the subversion metadata but the only SVN hook that is setup is the auto-mailer to ``docutils-checkins``, so the script may be in the admin web area?

Sorry I can't be of much further help -- I think the quick fix would be to use the shell service to recreate the link, but as we don't know what keeps the website up-to-date, it is hard to know if or when it'll break again.

[1]: https://sourceforge.net/p/forge/documentation/Project%20Web%20Services/
[2]: https://sourceforge.net/p/forge/documentation/Shell%20Service/
[3]: https://docutils.sourceforge.io/docutils/?C=M;O=A

A

[Docutils-develop] missing symlinks (was: #450 0.18: New HTML markup for footnotes is difficult to stylise)

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

On 2022-06-07, Adam Turner wrote:

>>>> 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:
...
> The files exist on disk, but are not valid links in Windows.
...
> So perhaps this is just a Windows issue.

At least, it works with a POSIX-compatible file system and also in our
repository.

> if the web server has disabled symlinks, 
> then it would also report errors. 

The repository web-view has the files and reports them as symlinks, e.g.

https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/test/functional/input/data/math.css
https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/test/functional/input/data/minimal.css

However, "minimal.css" is missing in the "public checkout"

https://docutils.sourceforge.io/test/functional/input/data/

OTOH, the "math.css" is present, although it is a symlink as well!
Maybe the "public checkout" does not create new files (or new symlinks)
without maintainer interaction?

Does anyone know how the "public checkout" under
https://docutils.sourceforge.io/test/
https://docutils.sourceforge.io/docutils/
works, where it is set up and how we can fix it?

Günter

[Docutils-develop] [docutils:feature-requests] Re: #58 Migration Docutils from SourceForge to Github

[Stephen F. <ste...@us...>]

On this point

> (2) what the concerns for doing a migration.
> 
> For me, the main concern is a monopoly in the hand of a commercial
> corporation.

While I am personally not a fan of GitHub and its pull request workflow
(OpenStack uses their own Gerrit and Gitea instance), it's worth noting that the
distributed nature of Git means lock in is not a huge issue as far as the code
itself is concerned. As long as someone has an up-to-date clone of the repo, you
could always move to a new home in no time. Of course you could lock yourself in
in other ways, such as through use of the issue tracker, CI (GitHub Actions),
etc. but all of these are secondary to the code and migration tooling exists for
many of these features already.

GitLab, Sourcehut, etc. all exist also if you really wanted to avoid GitHub,
however, the open core model of GitLab is problematic for some folks while the
long-term funding for things like Sourcehut is always going to be an issue (we
don't want our new "home" to disappear with minimal/no notice).

Just my 2c.

Cheers,
Stephen


On Wed, 2022-06-01 at 14:16 +0000, "Günter Milde" via Docutils-develop wrote:
> > (1) the maintainers want to migrate.
> 
> There is consensus to migrate to git.
> There is no consensus to migrate to Github.
> > (2) what the concerns for doing a migration.
> 
> For me, the main concern is a monopoly in the hand of a commercial
> corporation.
> > (3) whether my helping hand would be welcome. 
> 
> Thank you for the offer. Sorry for the long silence. 
>  [feature-requests:#58] Migration Docutils from SourceForge to Github
> Status: pending
> Group: Default
> Created: Fri Feb 16, 2018 03:23 PM UTC by Yves Chevallier
> Last Updated: Wed Jun 01, 2022 01:25 PM UTC
> Owner: nobody
> Sourceforge is not really user friendly to report issues, propose pull-request
> and contribute to the project. I would like to know if it is possible to
> migrate Docutils to 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 mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-develop
> 
> Please use "Reply All" to reply to the list.



---

** [feature-requests:#58] Migration Docutils from SourceForge to Github**

**Status:** pending
**Group:** Default
**Created:** Fri Feb 16, 2018 03:23 PM UTC by Yves Chevallier
**Last Updated:** Wed Jun 01, 2022 06:26 PM UTC
**Owner:** nobody


Sourceforge is not really user friendly to report issues, propose pull-request and contribute to the project. I would like to know if it is possible to migrate Docutils to 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.

Re: [Docutils-develop] [docutils:feature-requests] Re: #58 Migration Docutils from SourceForge to Github

[Stephen F. <st...@th...>]

On this point

> (2) what the concerns for doing a migration.
> 
> For me, the main concern is a monopoly in the hand of a commercial
> corporation.

While I am personally not a fan of GitHub and its pull request workflow
(OpenStack uses their own Gerrit and Gitea instance), it's worth noting that the
distributed nature of Git means lock in is not a huge issue as far as the code
itself is concerned. As long as someone has an up-to-date clone of the repo, you
could always move to a new home in no time. Of course you could lock yourself in
in other ways, such as through use of the issue tracker, CI (GitHub Actions),
etc. but all of these are secondary to the code and migration tooling exists for
many of these features already.

GitLab, Sourcehut, etc. all exist also if you really wanted to avoid GitHub,
however, the open core model of GitLab is problematic for some folks while the
long-term funding for things like Sourcehut is always going to be an issue (we
don't want our new "home" to disappear with minimal/no notice).

Just my 2c.

Cheers,
Stephen


On Wed, 2022-06-01 at 14:16 +0000, "Günter Milde" via Docutils-develop wrote:
> > (1) the maintainers want to migrate.
> 
> There is consensus to migrate to git.
> There is no consensus to migrate to Github.
> > (2) what the concerns for doing a migration.
> 
> For me, the main concern is a monopoly in the hand of a commercial
> corporation.
> > (3) whether my helping hand would be welcome. 
> 
> Thank you for the offer. Sorry for the long silence. 
>  [feature-requests:#58] Migration Docutils from SourceForge to Github
> Status: pending
> Group: Default
> Created: Fri Feb 16, 2018 03:23 PM UTC by Yves Chevallier
> Last Updated: Wed Jun 01, 2022 01:25 PM UTC
> Owner: nobody
> Sourceforge is not really user friendly to report issues, propose pull-request
> and contribute to the project. I would like to know if it is possible to
> migrate Docutils to 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 mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-develop
> 
> Please use "Reply All" to reply to the list.

Re: [Docutils-develop] Please state preferred email address for Git repository

[Stephen F. <st...@th...>]

On Wed, 2022-06-01 at 16:50 +0000, Guenter Milde via Docutils-develop wrote:
> Dear Docutils developers,
> 
> we plan to move the Docutils version repository from SVN to Git.
> 
> As Git uses "Name <mail-name@host>" instead of the Sourceforge user name
> to identify the Authors/Sponsors of a commit, we need to provide this info
> to the conversion script.
> 
> The default will be the one provided by Sourceforge: "<sfname>@users.sf.net".
> 
> If you have included an email address in the "author" info of a contributed
> file, this will be used instead.
> 
> This is your chance to announce a preferred/up to date email address under
> which you will be known in the Git repo.
> 
> 
> Thank you,
> 
> Günter

I would suggest using the default email but encouraging people to submit a patch
to add entries to the '.mailmap' file. There are docs on the internet about this
but tl;dr: the format is:

  <preferred e-mail 1> <other e-mail 1>
  <preferred e-mail 2> <other e-mail 2>
  <preferred e-mail 3> <other e-mail 3>
  ...

If you want to do this now, please use ste...@th...ru for my
contributions.

Cheers,
Stephen 

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

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

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


---

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

**Status:** open
**Labels:** footnotes 
**Created:** Sun Jun 05, 2022 08:28 PM UTC by Pradyun Gedam
**Last Updated:** Wed Jun 08, 2022 02:24 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...>]

> There was an incompatible API change in the 0.18 release -- why can't the same be done in 0.19?

There is no outright ban on such a change in the Docutils policies or in semantic versioning (as 0.19 < 1.0).
OTOH, HTML structure is part of the API and incompatible changes should be avoided if there is another way to solve the problem.

To ask it the other way: How can we be sure an incompatible change in 0.19 is a net benefit, when an incompatible change in 0.18 introduced a problem?


---

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

**Status:** open
**Labels:** footnotes 
**Created:** Sun Jun 05, 2022 08:28 PM UTC by Pradyun Gedam
**Last Updated:** Wed Jun 08, 2022 10:58 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.

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

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

"The footnote element is used for labeled notes that provide additional context to a passage of text (footnotes or endnotes)." [The Docutils Document Tree](https://docutils.sourceforge.io/docs/ref/doctree.html#footnote).
Due to this ambiguity, the [note](https://www.w3.org/TR/wai-aria-1.1/#note) role was chosen over "doc-footnote" or "doc-endnotes".

The [doc-noteref](https://www.w3.org/TR/dpub-aria-1.1/#doc-noteref) is used for the marker "appearing as a superscripted number or symbol in the main body of text." In Docutils this is the *footnote_reference* element.


---

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

**Status:** open
**Labels:** footnotes 
**Created:** Sun Jun 05, 2022 08:28 PM UTC by Pradyun Gedam
**Last Updated:** Wed Jun 08, 2022 10:47 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.