Menu
▾
▴
docutils-develop
|
From: Pradyun G. <pr...@us...> - 2022-06-05 20:28:33
|
---
** [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. |
|
From: Adam T. <aa-...@us...> - 2022-06-05 20:49:51
|
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. |
|
From: Adam T. <aa-...@us...> - 2022-06-05 20:52:09
|
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. |
|
From: Adam T. <aa-...@us...> - 2022-06-05 21:42:29
|
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. |
|
From: Günter M. <mi...@us...> - 2022-06-05 21:44:27
|
> 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. |
|
From: Adam T. <aa-...@us...> - 2022-06-05 21:51:23
|
@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. |
|
From: Pradyun G. <pr...@us...> - 2022-06-05 23:09:13
|
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. |
|
From: Adam T. <aa-...@us...> - 2022-06-05 23:49:16
|
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. |
|
From: Pradyun G. <pr...@us...> - 2022-06-06 10:03:08
|
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. |
|
From: Guenter M. <mi...@us...> - 2022-06-06 20:36:01
|
>> 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. |
|
From: Adam T. <aat...@ou...> - 2022-06-07 17:24:22
|
>>> 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 |
|
From: Günter M. <mi...@us...> - 2022-06-07 13:51:05
|
> 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. |
|
From: Pradyun G. <pr...@us...> - 2022-06-07 14:14:37
|
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. |
|
From: Adam T. <aa-...@us...> - 2022-06-07 14:19:13
|
> 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. |
|
From: Adam T. <aa-...@us...> - 2022-06-07 14:22:08
|
@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. |
|
From: Pradyun G. <pr...@us...> - 2022-06-07 17:26:35
|
@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. |
){kind=link}
|
From: Günter M. <mi...@us...> - 2022-06-07 17:53:41
|
> 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. |
|
From: Pradyun G. <pr...@us...> - 2022-06-07 23:48:31
|
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. |
|
From: Pradyun G. <pr...@us...> - 2022-06-07 18:02:15
|
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. |
|
From: Günter M. <mi...@us...> - 2022-06-08 14:24:37
|
> 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. |
|
From: Günter M. <mi...@us...> - 2022-06-08 10:47:10
|
The result shown in the image can easily be achieved with the current "html5" footnote markup and a 3-column grid layout (see [gridfoot.css](https://sourceforge.net/p/docutils/bugs/_discuss/thread/af593fcd69/6bdd/attachment/gridfoot.css) for a prove of concept). How can we improve? "html5_polyglot" aims for clear, semantic HTML markup that is easily stylable and ["degrades gracefully"](https://en.wikipedia.org/wiki/Fault_tolerance) (e.g. with missing CSS). Traditionally, groups of footnotes are rendered either as *sequence of paragraphs* (with standard paragraph separation, hanging indent or no separation) preceded by the reference mark or as a *list* with the reference mark as list label. The *list* style is common for endnotes. rST and the Docutils document model don't differentiate footnotes from endnotes - it is up to the placement in the source. (Endnote support is an old TODO item, cf. below.) There is no equivalent for the optional *footnote backrefs* element in printed documents. [Wikipedia references](https://en.wikipedia.org/wiki/Odessa#References) and the "html4css writer" use only the reference mark as list label and place backrefs in front of the footnote text. Reference mark, optional backlinks and actual footnote content should be wrapped in a "footnote" element for accessibility and clear semantics. I don't know whether this constitutes a major obstacle for styling as a list by way of a CSS "grid". The HTML standard allows *div* wrappers around *dt* –*dd* groups in [dl elements](https://html.spec.whatwg.org/multipage/grouping-content.html#the-dl-element). Hence, there might be a precedence for styling such an element hierarchy as grid. If the additional level constitutes a major obstacle for styling by way of a CSS "grid", we may compromise for the case of HTML5 output treating all footnotes as endnotes: wrapping groups of footnotes in an element with role [doc-endnotes](https://www.w3.org/TR/dpub-aria-1.1/#doc-endnotes) containing a list with the actual notes. This would match nicely the use case of rST footnotes placed "at the end of a work or a section within it" at the cost of a mis-match for footnotes placed within a section, near their reference point in the text. I'd prefer to spare this for a possible "endnotes" directive to [collect footnotes](https://docutils.sourceforge.io/docs/dev/todo.html#footnote-citation-gathering). --- ** [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:54 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. |
|
From: Günter M. <mi...@us...> - 2022-06-08 10:58:20
|
"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. |
|
From: Alan <ai...@us...> - 2022-06-08 14:27:19
|
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. |
|
From: Guenter M. <mi...@us...> - 2022-06-08 18:54:47
|
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 |
|
From: Adam T. <aat...@ou...> - 2022-06-09 00:24:49
|
> 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 |
×
Want the latest updates on software, tech news, and AI?
Get latest updates about software, tech news, and AI from SourceForge directly in your inbox once a month.
Thanks for helping keep SourceForge clean.
X