docutils-develop — For developer discussions of the implementation.

[Docutils-develop] [docutils:feature-requests] #112 The the include directive does not allow configuring a parser

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

Generally, the parser(s) can be configured via Docutils [configuration files](https://docutils.sourceforge.io/docs/user/config.html#configuration-files).¹
This also holds for the 3rd-party MyST parser. (See the output of, e.g., `myst-docutils-html5 --help` or https://myst-parser.readthedocs.io/en/latest/configuration.html#sphinx-config-options for available options.)

¹ Sphinx reads a `docutils.conf` configuration file, if it is present in the [configuration](https://www.sphinx-doc.org/en/master/usage/configuration.html) directory.



---

**[feature-requests:#112] The the include directive does not allow configuring a parser**

**Status:** pending-works-for-me
**Group:** Default
**Created:** Sat Apr 05, 2025 03:14 PM UTC by Gabriel P
**Last Updated:** Mon Apr 14, 2025 10:04 AM UTC
**Owner:** nobody


See this bug report: https://github.com/executablebooks/MyST-NB/issues/471

Is there a way to configure the parser when using include? I checked here but could not see anything that might help: https://docutils.sourceforge.io/docs/ref/rst/directives.html#include


---

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

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

[Docutils-develop] [docutils:feature-requests] #108 title/tooltip option for the "image" directive

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

- **status**: pending --> pending-moreinfo
- **Comment**:

This feature requestd needs more thought and discussion -- may be a topic for an enhancement proposal.



---

**[feature-requests:#108] title/tooltip option for the "image" directive**

**Status:** pending-moreinfo
**Group:** Default
**Created:** Sun Sep 29, 2024 08:41 AM UTC by toastal
**Last Updated:** Sat Feb 15, 2025 01:35 PM UTC
**Owner:** nobody


Like `image`’s `:alt:` directive, allow `:title:` for creating titles on pointer hover. The use case here is different from alt as alt is for assistive technologies & titles are more to give a labels for images for those with pointer cursors.

Expected input

~~~
.. image:: /house.jxl
	:alt: Home
	:title: Navigate home
	:target: /

.. image:: /cat.jxl
	:alt: A Siamese cat on a chair
	:title: Chula says, “meow”
~~~

Expected HTML output

~~~
<a href="/"><img src="/house.jxl" alt="Home" title="Navigate home"></a>
<img src="/cat.jxl" alt="A Siamese cat on a chair" title="Chula says, “meow”">
~~~

~~~






---

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

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

[Docutils-develop] [docutils:feature-requests] #110 Move from "optparse" to "argparse".

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

- **status**: open --> pending



---

**[feature-requests:#110] Move from "optparse" to "argparse".**

**Status:** pending
**Group:** Default
**Created:** Thu Jan 06, 2022 03:02 PM UTC by Günter Milde
**Last Updated:** Fri Apr 25, 2025 03:24 PM UTC
**Owner:** nobody


The optparse documentation says:
> Deprecated since version 3.2: The optparse module is deprecated and will not be developed further; development will continue with the argparse module.

We are currently suppressing related deprecation warnings in the test suite.
After raising the Python dependency to >=3.7, now may be the right time to make the move.


---

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

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

[Docutils-develop] [docutils:bugs] Re: #497 manpage writer renders links incorrectly

[G. B. R. <br...@us...>]

> One thing that I would possibly change about alacritty variant is: don't put fancy brackets around aa...@bb... and dd...@gm... (they seem out of place because these are emails not links, and they are not clickable).

I didn't test _alacritty_ myself, but if I understand you correctly...

...I agree.  In my opinion, the terminal device should not perform any transformations on the grapheme content of character cells to reflect semantic content, and especially should not perform transformations that change how many character cells a character sequence occupies on the terminal.  (We have to make an exception for cases where the terminal must format U+FFFD to represent an unavailable or invalid UTF-8 character.)

I find myself wondering if alacritty's automatic angle bracketing corrupts the display when _curses_ is used.


---

**[bugs:#497] manpage writer renders links incorrectly**

**Status:** open-fixed
**Labels:** manpage writer 
**Created:** Tue Feb 11, 2025 11:03 PM UTC by Ulya Trofimovich
**Last Updated:** Sat Apr 26, 2025 07:20 AM UTC
**Owner:** engelbert gruber


Hi! Here's an example bug.rst file (trimmed from a real-world manpage AUTHORS section and changed to hide real names):
~~~
$ cat bug.rst
Aaaaa (aa...@bb...),
`Bbb <https://github.com/cc>`_ (dd...@gm...),
`mm <https://github.com/m>`_
`nn <https://github.com/nn>`_
and `OooOoooo <https://github.com/OooOoooo>`_.
~~~
With rst2man (Docutils 0.21.2, Python 3.12.8, on linux) it is rendered as follows (I cut first and last output lines in the output as they obscure the view and are irrelevant):
~~~
$ rst2man bug.rst > bug.1 && man ./bug.1
NAME
        - Aaaaa ( <aa...@bb...> ), Bbb <https://github.com/cc>
        ( <dd...@gm...> ), mm <https://github.com/m>

        <nn> and  <OooOoooo> .
~~~
What I think is wrong:

1. In <nn> and <OooOoooo> URI had been removed completely (note that they are different from other addresses in that the substitution text is the same as the last URI path component)
2. spaces surrounding email in parentheses look weird
3. newlines seem to be inserted at random

I would like it to be rendered like this:
~~~
NAME
        - Aaaaa (aa...@bb...), Bbb <https://github.com/cc> (dd...@gm...), mm <https://github.com/m> nn <https://github.com/nn> and OooOoooo <https://github.com/OooOoooo>.
~~~
    
I suspect this is the change in https://docutils.sourceforge.io/RELEASE-NOTES.html#release-0-21-2024-04-09, as I saw other changes listed in this release in the same diff with the breaking changes described above.


---

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

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

[Docutils-develop] [docutils:bugs] Re: #497 manpage writer renders links incorrectly

[G. B. R. <br...@us...>]

This generated output looks really good to me.  I formatted the files as follows.

~~~
nroff -rCHECKSTYLE=4 -man ./authors.man
nroff -rCHECKSTYLE=4 -man ./authors-urue.man
nroff -rCHECKSTYLE=4 -rU0 -man ./authors-urue.man
nroff -rCHECKSTYLE=4 -man ./ref-2025.man
nroff -rCHECKSTYLE=4 -man ./ref-2025-urue.man
nroff -rCHECKSTYLE=4 -man -rU0 ./ref-2025-urue.man
~~~

I got a few warnings from the style checker, but they are solely due to the degenerate input affecting parts of the document that have nothing to do with formatting links, and which are unlikely to occur in practical, real-world _docutils_ input.

~~~
$ nroff -z -rCHECKSTYLE=4 -man ./authors.man 
an.tmac:./authors.man:31: style: .TH missing third argument; consider document modification date in ISO 8601 format (YYYY-MM-DD)
an.tmac:./authors.man:31: style: .TH missing fourth argument; consider package/project name and version (e.g., "groff 1.23.0")
an.tmac:./authors.man:31: style: .TH missing fifth argument and second argument '' not a recognized manual section; specify its title
an.tmac:./authors.man:33: style: 1 leading space(s) on input line
~~~

None of these alarm me or affect the correctness of your generated output with respect to the formatting of hyperlinks.

I checked output in two terminal emulators.

~~~
$ gnome-terminal --version
# GNOME Terminal 3.38.3 using VTE 0.66.1 +BIDI +GNUTLS +ICU +SYSTEMD
$ xterm -version
XTerm(395)
~~~

...and everything looks good to me.  _xterm_ of course does not honor OSC 8.  _gnome-terminal_ does, and the highlighting of the OSC 8-bracketed sequences are where I expect them to be, and the pop-up tooltips over them show correctly-formed URLs.

Even better, when I specify the additional `nroff` option `-T ascii`, your "text references" feature's output so closely resembles what _groff man_ does when OSC 8 support is disabled (`-r U0`) that neither my eyeballs nor _diff_ can detect a difference!  (There is a difference when using _groff_'s `utf8` device because the U+2010 hyphen and U+27E8 and U+27E9 angle brackets are available. )

This feature looks ready to ship to me!  Please advise if I can be of any further assistance.


---

**[bugs:#497] manpage writer renders links incorrectly**

**Status:** open-fixed
**Labels:** manpage writer 
**Created:** Tue Feb 11, 2025 11:03 PM UTC by Ulya Trofimovich
**Last Updated:** Sat Apr 26, 2025 05:29 AM UTC
**Owner:** engelbert gruber


Hi! Here's an example bug.rst file (trimmed from a real-world manpage AUTHORS section and changed to hide real names):
~~~
$ cat bug.rst
Aaaaa (aa...@bb...),
`Bbb <https://github.com/cc>`_ (dd...@gm...),
`mm <https://github.com/m>`_
`nn <https://github.com/nn>`_
and `OooOoooo <https://github.com/OooOoooo>`_.
~~~
With rst2man (Docutils 0.21.2, Python 3.12.8, on linux) it is rendered as follows (I cut first and last output lines in the output as they obscure the view and are irrelevant):
~~~
$ rst2man bug.rst > bug.1 && man ./bug.1
NAME
        - Aaaaa ( <aa...@bb...> ), Bbb <https://github.com/cc>
        ( <dd...@gm...> ), mm <https://github.com/m>

        <nn> and  <OooOoooo> .
~~~
What I think is wrong:

1. In <nn> and <OooOoooo> URI had been removed completely (note that they are different from other addresses in that the substitution text is the same as the last URI path component)
2. spaces surrounding email in parentheses look weird
3. newlines seem to be inserted at random

I would like it to be rendered like this:
~~~
NAME
        - Aaaaa (aa...@bb...), Bbb <https://github.com/cc> (dd...@gm...), mm <https://github.com/m> nn <https://github.com/nn> and OooOoooo <https://github.com/OooOoooo>.
~~~
    
I suspect this is the change in https://docutils.sourceforge.io/RELEASE-NOTES.html#release-0-21-2024-04-09, as I saw other changes listed in this release in the same diff with the breaking changes described above.


---

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

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

[Docutils-develop] [docutils:bugs] #497 manpage writer renders links incorrectly

[engelbert g. <gr...@us...>]

RFC the generated man-pages with and without macros



Attachments:

- [ref-2025-urue.man](https://sourceforge.net/p/docutils/bugs/_discuss/thread/48dad27f08/fa9d/attachment/ref-2025-urue.man) (1.1 kB; application/x-troff-man)
- [ref-2025.man](https://sourceforge.net/p/docutils/bugs/_discuss/thread/48dad27f08/fa9d/attachment/ref-2025.man) (1.0 kB; application/x-troff-man)
- [authors-urue.man](https://sourceforge.net/p/docutils/bugs/_discuss/thread/48dad27f08/fa9d/attachment/authors-urue.man) (1.7 kB; application/x-troff-man)
- [authors.man](https://sourceforge.net/p/docutils/bugs/_discuss/thread/48dad27f08/fa9d/attachment/authors.man) (1.6 kB; application/x-troff-man)


---

**[bugs:#497] manpage writer renders links incorrectly**

**Status:** open-fixed
**Labels:** manpage writer 
**Created:** Tue Feb 11, 2025 11:03 PM UTC by Ulya Trofimovich
**Last Updated:** Tue Apr 15, 2025 10:41 AM UTC
**Owner:** engelbert gruber


Hi! Here's an example bug.rst file (trimmed from a real-world manpage AUTHORS section and changed to hide real names):
~~~
$ cat bug.rst
Aaaaa (aa...@bb...),
`Bbb <https://github.com/cc>`_ (dd...@gm...),
`mm <https://github.com/m>`_
`nn <https://github.com/nn>`_
and `OooOoooo <https://github.com/OooOoooo>`_.
~~~
With rst2man (Docutils 0.21.2, Python 3.12.8, on linux) it is rendered as follows (I cut first and last output lines in the output as they obscure the view and are irrelevant):
~~~
$ rst2man bug.rst > bug.1 && man ./bug.1
NAME
        - Aaaaa ( <aa...@bb...> ), Bbb <https://github.com/cc>
        ( <dd...@gm...> ), mm <https://github.com/m>

        <nn> and  <OooOoooo> .
~~~
What I think is wrong:

1. In <nn> and <OooOoooo> URI had been removed completely (note that they are different from other addresses in that the substitution text is the same as the last URI path component)
2. spaces surrounding email in parentheses look weird
3. newlines seem to be inserted at random

I would like it to be rendered like this:
~~~
NAME
        - Aaaaa (aa...@bb...), Bbb <https://github.com/cc> (dd...@gm...), mm <https://github.com/m> nn <https://github.com/nn> and OooOoooo <https://github.com/OooOoooo>.
~~~
    
I suspect this is the change in https://docutils.sourceforge.io/RELEASE-NOTES.html#release-0-21-2024-04-09, as I saw other changes listed in this release in the same diff with the breaking changes described above.


---

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

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

[Docutils-develop] [docutils:bugs] #488 prepare URIs

[engelbert g. <gr...@us...>]

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



---

**[bugs:#488] prepare URIs **

**Status:** open-fixed
**Labels:** manpage writer 
**Created:** Sun May 12, 2024 03:55 PM UTC by engelbert gruber
**Last Updated:** Tue Apr 15, 2025 06:19 PM UTC
**Owner:** engelbert gruber


groff_man_style on hyperlinks

    The arguments to .MR, .MT, and .UR should be prepared for typesetting
    
1. Use special character escape sequences to encode Unicode  basic  Latin  characters  where  necessary, particularly the hyphen-minus.
2. URIs can be lengthy; ... the  application  of  non-printing break point escape sequences \: after each slash (or series thereof), and before each  dot  (or  series  thereof)  is recommended 
3. Consider  adding  break points  before  or after at signs in email addresses, and question marks, ampersands, and number signs in HTTP(S) URIs.


---

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

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

[Docutils-develop] [docutils:feature-requests] #110 Move from "optparse" to "argparse".

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

In Python 3.13.3, the [optparse](https://docs.python.org/3/library/optparse.html) module is no longer deprecated but rather described as a low-level alternative to *argparse* for apps already using *optparse*  if the migrating costs are too high.

In Docutils migrating will become easier after we drop support for old-format configuration files in Docutils 2.0. I suggest postponing the migration and announce it for "Docutils 2.0 or later".


Attachments:

- [0001-Announce-switch-to-argparse-for-Docutils-2.0-or-late.patch](https://sourceforge.net/p/docutils/feature-requests/_discuss/thread/c76f9a2618/7847/attachment/0001-Announce-switch-to-argparse-for-Docutils-2.0-or-late.patch) (6.4 kB; text/x-patch)


---

**[feature-requests:#110] Move from "optparse" to "argparse".**

**Status:** open
**Group:** Default
**Created:** Thu Jan 06, 2022 03:02 PM UTC by Günter Milde
**Last Updated:** Thu Jan 16, 2025 09:26 AM UTC
**Owner:** nobody


The optparse documentation says:
> Deprecated since version 3.2: The optparse module is deprecated and will not be developed further; development will continue with the argparse module.

We are currently suppressing related deprecation warnings in the test suite.
After raising the Python dependency to >=3.7, now may be the right time to make the move.


---

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

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

[Docutils-develop] [docutils:bugs] #157 Line block parsing doesn't like system message -> traceback

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

Proper fix in [r10104], cf. [bugs:#489].


---

**[bugs:#157] Line block parsing doesn't like system message -> traceback**

**Status:** closed-fixed
**Created:** Mon Jan 03, 2011 10:30 PM UTC by Georg Brandl
**Last Updated:** Tue Mar 03, 2020 09:41 PM UTC
**Owner:** nobody


\(originally from https://bitbucket.org/birkenfeld/sphinx/issue/533/\)

When a system message \(e.g. for a duplicate target\) occurs in a line block, a traceback is caused.  Example reST source:

Publications
============

| Hoyt Koepke. Paper 1.
| \[\`pdf <\_static/paper-1.pdf>\`\_ \]

| Hoyt Koepke. Paper 2.
| \[\`pdf <\_static/paper-2.pdf>\`\_ \]

Traceback \(Sphinx-specific frames cut at the top\):

File "/usr/local2/lib/python2.6/site-packages/docutils-0.6-py2.6.egg/docutils/readers/\_\_init\_\_.py", line 69, in read
self.parse\(\)
File "/usr/local2/lib/python2.6/site-packages/docutils-0.6-py2.6.egg/docutils/readers/\_\_init\_\_.py", line 75, in parse
self.parser.parse\(self.input, document\)
File "/usr/local2/lib/python2.6/site-packages/docutils-0.6-py2.6.egg/docutils/parsers/rst/\_\_init\_\_.py", line 157, in parse
self.statemachine.run\(inputlines, document, inliner=self.inliner\)
File "/usr/local2/lib/python2.6/site-packages/docutils-0.6-py2.6.egg/docutils/parsers/rst/states.py", line 170, in run
input\_source=document\['source'\]\)
File "/usr/local2/lib/python2.6/site-packages/docutils-0.6-py2.6.egg/docutils/statemachine.py", line 233, in run
context, state, transitions\)
File "/usr/local2/lib/python2.6/site-packages/docutils-0.6-py2.6.egg/docutils/statemachine.py", line 421, in check\_line
return method\(match, context, next\_state\)
File "/usr/local2/lib/python2.6/site-packages/docutils-0.6-py2.6.egg/docutils/parsers/rst/states.py", line 2678, in underline
self.section\(title, source, style, lineno - 1, messages\)
File "/usr/local2/lib/python2.6/site-packages/docutils-0.6-py2.6.egg/docutils/parsers/rst/states.py", line 323, in section
self.new\_subsection\(title, lineno, messages\)
File "/usr/local2/lib/python2.6/site-packages/docutils-0.6-py2.6.egg/docutils/parsers/rst/states.py", line 391, in new\_subsection
node=section\_node, match\_titles=1\)
File "/usr/local2/lib/python2.6/site-packages/docutils-0.6-py2.6.egg/docutils/parsers/rst/states.py", line 278, in nested\_parse
node=node, match\_titles=match\_titles\)
File "/usr/local2/lib/python2.6/site-packages/docutils-0.6-py2.6.egg/docutils/parsers/rst/states.py", line 195, in run
results = StateMachineWS.run\(self, input\_lines, input\_offset\)
File "/usr/local2/lib/python2.6/site-packages/docutils-0.6-py2.6.egg/docutils/statemachine.py", line 233, in run
context, state, transitions\)
File "/usr/local2/lib/python2.6/site-packages/docutils-0.6-py2.6.egg/docutils/statemachine.py", line 421, in check\_line
return method\(match, context, next\_state\)
File "/usr/local2/lib/python2.6/site-packages/docutils-0.6-py2.6.egg/docutils/parsers/rst/states.py", line 1539, in line\_block
self.nest\_line\_block\_lines\(block\)
File "/usr/local2/lib/python2.6/site-packages/docutils-0.6-py2.6.egg/docutils/parsers/rst/states.py", line 1556, in nest\_line\_block\_lines
if block\[index\].indent is None:
AttributeError: 'system\_message' object has no attribute 'indent'



---

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

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

[Docutils-develop] [docutils:bugs] #489 Issues with the Docutils Doctree

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

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

Fixed in [r10104].



---

**[bugs:#489] Issues with the Docutils Doctree**

**Status:** open-fixed
**Created:** Tue Jun 11, 2024 12:13 PM UTC by Günter Milde
**Last Updated:** Fri Apr 25, 2025 10:50 AM UTC
**Owner:** nobody
**Attachments:**

- [0001-Doctree-amendment-System-messages-can-appear-in-plac.patch](https://sourceforge.net/p/docutils/bugs/489/attachment/0001-Doctree-amendment-System-messages-can-appear-in-plac.patch) (5.5 kB; text/x-patch)


There are a number of discrepancies between the [Docutils Generic DTD][docutils.dtd]
and the implementation in Docutils code.

footnote
--------

[docutils.dtd][docutils.dtd]: `(label?, (%body.elements;)+)`
→ Label **optional**, content **required**; (not changed since 2002-04-20).

[reStructureText Markup Specification][rST spec]:
> Each footnote consists of an explicit markup start (".. "), a left
> square bracket, **the footnote label**, a right square bracket, and
> whitespace, followed by indented body elements.

The `footnote` class in [docutils.nodes](https://docutils.sourceforge.io/docutils/nodes.py) is a subclass of `Labeled`, 
whose docstring says: "**Contains a label** as its first element."

The rST parser **requires** a label but allows **empty footnotes**
(cf. `test/test_writers/test_latex2e.py`).

citation
--------

[docutils.dtd][docutils.dtd]: `(label, (%body.elements;)+)`
→ Label **required**, content **required**; (not changed since 2002-04-20).

[reStructureText Markup Specification][rST spec]:
> Citations are **identical to footnotes** except that they use only
> non-numeric labels …

The rST parser allows **empty citations** (cf. test_rst/test_citations.py).

figure
------

[docutils.dtd][docutils.dtd]: `(image, ((caption, legend?) | legend))`
→ caption or legend **required**; (not changed since 2002-04-20).

[reStructuredText Directives](https://docutils.sourceforge.io/docs/ref/rst/directives.html#figure)

> A "figure" consists of image data (including image options), an **optional
> caption** (a single paragraph), and an **optional legend** (arbitrary body
> elements). For page-based output media, figures might float to a different
> position if this helps the page layout.

The rST parser allows **figures without caption or legend**.

Docutils HTML and LaTeX writers use a different layout for figures vs.
images. They can handle figures without caption/legend.

Suggestion
----------

* Make *footnote label compulsory`*.
* Let rST report a *warning for empty footnote and citation*.
  Remove tests with empty footnote and citation.
* Allow *figures without caption/legend* in the Docutils Generic DTD.

(Change in Docutils 1.0, announce in 0.22.)

Questions
---------
Are there a use cases for 
* footnotes without label,
* footnotes without content,
* citations without content?

[docutils.dtd]: https://docutils.sourceforge.io/docs/ref/docutils.dtd
[rST spec]: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html



---

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

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

[Docutils-develop] [docutils:bugs] Re: #489 Issues with the Docutils Doctree

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

It turns out to be a rST parser problem affecting all elements supporting the "text model" (i.e accepting text and inline elements but no body elements) like `<field_name>` and `<rubric>`. 
As a consequence, the HTML writers generate invalid HTML for, e.g., a rubric with a :name: option value that is a duplicate of another external reference target.

The test case was added in [r7638] in response to [bugs:#157]. However, the commit fixed the a symptom, not the cause.



---

**[bugs:#489] Issues with the Docutils Doctree**

**Status:** open
**Created:** Tue Jun 11, 2024 12:13 PM UTC by Günter Milde
**Last Updated:** Wed Apr 23, 2025 10:49 AM UTC
**Owner:** nobody
**Attachments:**

- [0001-Doctree-amendment-System-messages-can-appear-in-plac.patch](https://sourceforge.net/p/docutils/bugs/489/attachment/0001-Doctree-amendment-System-messages-can-appear-in-plac.patch) (5.5 kB; text/x-patch)


There are a number of discrepancies between the [Docutils Generic DTD][docutils.dtd]
and the implementation in Docutils code.

footnote
--------

[docutils.dtd][docutils.dtd]: `(label?, (%body.elements;)+)`
→ Label **optional**, content **required**; (not changed since 2002-04-20).

[reStructureText Markup Specification][rST spec]:
> Each footnote consists of an explicit markup start (".. "), a left
> square bracket, **the footnote label**, a right square bracket, and
> whitespace, followed by indented body elements.

The `footnote` class in [docutils.nodes](https://docutils.sourceforge.io/docutils/nodes.py) is a subclass of `Labeled`, 
whose docstring says: "**Contains a label** as its first element."

The rST parser **requires** a label but allows **empty footnotes**
(cf. `test/test_writers/test_latex2e.py`).

citation
--------

[docutils.dtd][docutils.dtd]: `(label, (%body.elements;)+)`
→ Label **required**, content **required**; (not changed since 2002-04-20).

[reStructureText Markup Specification][rST spec]:
> Citations are **identical to footnotes** except that they use only
> non-numeric labels …

The rST parser allows **empty citations** (cf. test_rst/test_citations.py).

figure
------

[docutils.dtd][docutils.dtd]: `(image, ((caption, legend?) | legend))`
→ caption or legend **required**; (not changed since 2002-04-20).

[reStructuredText Directives](https://docutils.sourceforge.io/docs/ref/rst/directives.html#figure)

> A "figure" consists of image data (including image options), an **optional
> caption** (a single paragraph), and an **optional legend** (arbitrary body
> elements). For page-based output media, figures might float to a different
> position if this helps the page layout.

The rST parser allows **figures without caption or legend**.

Docutils HTML and LaTeX writers use a different layout for figures vs.
images. They can handle figures without caption/legend.

Suggestion
----------

* Make *footnote label compulsory`*.
* Let rST report a *warning for empty footnote and citation*.
  Remove tests with empty footnote and citation.
* Allow *figures without caption/legend* in the Docutils Generic DTD.

(Change in Docutils 1.0, announce in 0.22.)

Questions
---------
Are there a use cases for 
* footnotes without label,
* footnotes without content,
* citations without content?

[docutils.dtd]: https://docutils.sourceforge.io/docs/ref/docutils.dtd
[rST spec]: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html



---

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

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

[Docutils-develop] [docutils:patches] #213 Change section handling to not rely on exceptions and reparsing

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

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



---

**[patches:#213] Change section handling to not rely on exceptions and reparsing**

**Status:** open-fixed
**Group:** None
**Created:** Wed Mar 26, 2025 07:57 PM UTC by Arne Skjærholt
**Last Updated:** Thu Apr 17, 2025 09:50 PM UTC
**Owner:** nobody
**Attachments:**

- [section-handling.patch](https://sourceforge.net/p/docutils/patches/213/attachment/section-handling.patch) (13.3 kB; text/x-patch)


While waiting for responses to an email I sent to the -users I decided to dig further into the issue and ended up implementing a fix. To recap my issue, I was having problems with a custom directive's nested parse of its content when section headers were used, because the existing code throws an EOFError up the chain to find the correct place to attach a new section.

The proposed patch changes this by adding an explicit stack of sections to the memo object instead of using the Python call stack, and changing RSTState.section() to unwind this state in-place, instead of using exception throwing to find the right place. In fact, I think this is the kind of implementation suggested as an alternative in a comment in the existing code. This also lets us get rid of memo.section_bubble_up_kludge and Line.eofcheck, which only existed to handle the exceptions.

In addition to the changed code, I've had to make six changes to the test suite.

- Three diagnostics in test/functional/expected/standalone_rst_pseudoxml.txt now have line numbers relative to the beginning of the file rather than some other element. I think because we no longer initiate a nested parse for sections.
- Two diagnostics in test/test_parsers/test_rst/test_targets.py have different line numbers, indicating the second conflicting label, rather than the implicit label generated by the section. I think the reason is that due to the exception throwing approach, the existing code handled the section label later than the other, even if the section is earlier in the text.
- test/test_parsers/test_rst/test_section_headers.py has one diagnostic output less. I think this diagnostic is a duplicate, caused by the rethrowing of the exception for bubbling up the stack.




---

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

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

Re: [Docutils-develop] [docutils:feature-requests] Re: #113 scale option in docutils.conf

[Karl O. P. <ko...@ka...>]

On Wed, 23 Apr 2025 18:57:34 -0000
Günter Milde via Docutils-develop
<doc...@li...> wrote:

> This approach would add a level of complexity that makes it more
> suitable for an extension or a custom HTML writer than for standard
> Docutils.
> 
> Some alternatives come to mind:
> 
> A "simple script" could also be used to pre-process the rST source or
> post-process the generated HTML to add image dimensions instead of
> generating sidecar files.

FWIW, I've used the m4 macro processor
(https://www.gnu.org/software/m4/m4.html) 
for pre-processing rST.  With plain-old macro text substitution it's 
hard to go wrong.  

It is easy to be seduced and utilize more
sophisticated m4 features, conditionals, calling out to shell,
and so forth, which can lead to over-engineering.
That said, utilizing ImageMagic, it should be easy to write a 
m4 macro that takes a path to an image and returns
(one of) the dimensions for substitution into the rsT source.

Regards,

Karl <ko...@ka...>
Free Software:  "You don't pay back, you pay forward."
                 -- Robert A. Heinlein

[Docutils-develop] [docutils:patches] #89 latex2e: Propagate figure align to image

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

- Description has changed:

Diff:

~~~~

--- old
+++ new
@@ -1,7 +1,7 @@
 latex2e: Propagate figure align to image
 
 Previously figure alignment was not taken into account for
-embedding-in-fugure images -- images were always center-aligned.
+embedding-in-figure images -- images were always center-aligned.
 
 Fix it, by propagating figure's alignment to image, centering by
 default.

~~~~

- **Comment**:

 The alignment of the image in a figure can be set passing the special values "align-left", "align-right", or "align-center" to the class option. The LaTeX writer respects these special values.
 
A more consistent support for image-in-figure alignment is proposed in [feature-requests:#114].



---

**[patches:#89] latex2e: Propagate figure align to image**

**Status:** closed-rejected
**Group:** None
**Created:** Tue Nov 08, 2011 10:31 AM UTC by Kirill Smelkov
**Last Updated:** Wed Apr 23, 2025 07:26 PM UTC
**Owner:** nobody


latex2e: Propagate figure align to image

Previously figure alignment was not taken into account for
embedding-in-figure images -- images were always center-aligned.

Fix it, by propagating figure's alignment to image, centering by
default.



---

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

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

[Docutils-develop] [docutils:patches] #89 latex2e: Propagate figure align to image

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

- **status**: pending-remind --> closed-rejected
- **Group**:  --> None
- **Comment**:

 The alignment of the image in a figure can be set passing the special values "align-left", "align-right", or "align-center" to the class option. The LaTeX writer respects these special values.
 
A more consistent support for image-in-figure alignment is proposed in [feature-requests:#114].



---

**[patches:#89] latex2e: Propagate figure align to image**

**Status:** closed-rejected
**Group:** None
**Created:** Tue Nov 08, 2011 10:31 AM UTC by Kirill Smelkov
**Last Updated:** Thu Nov 10, 2011 01:20 PM UTC
**Owner:** nobody


latex2e: Propagate figure align to image

Previously figure alignment was not taken into account for
embedding-in-fugure images -- images were always center-aligned.

Fix it, by propagating figure's alignment to image, centering by
default.



---

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

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

[Docutils-develop] [docutils:feature-requests] #114 Inconsistent handling of "figure" directive option "align".

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

---

**[feature-requests:#114] Inconsistent handling of "figure" directive option "align".**

**Status:** open
**Group:** Default
**Labels:** reStructuredText 
**Created:** Wed Apr 23, 2025 07:22 PM UTC by Günter Milde
**Last Updated:** Wed Apr 23, 2025 07:22 PM UTC
**Owner:** nobody


The [figure](https://docutils.sourceforge.io/docs/ref/rst/directives.html#figure) directive passes all options that are supported by the "image" directive **except `align`** to the included image:
* `width` sets the image width, `figwidth` sets the figure width,
* `class` sets image class values, `figclass` sets figure class values,
* `name` sets a reference name for the image, `figname` sets a reference name for the figure.
but 
* `align` sets the alignment of the figure and there is no option to set the alignment of an image in the figure.¹

¹ As a workaround, the image alignment can be set passing the special  values "align-left", "align-right", or "align-center" to the `class` option.

Suggestion: 
* Use `align` for image alignment and the new option `figalign` for figure alignment.
* Provide a new configuration setting `legacy-figure-align` for the rST parser that switches to the current behaviour  for backwards compatibility. The default value of this setting would be "True" and change at a later stage.



---

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

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

[Docutils-develop] [docutils:feature-requests] Re: #113 scale option in docutils.conf

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

This approach would add a level of complexity that makes it more suitable for an extension or a custom HTML writer than for standard Docutils.

Some alternatives come to mind:

A "simple script" could also be used to pre-process the rST source or post-process the generated HTML to add image dimensions instead of generating sidecar files.

A custom HTML writer may add image dimensions by reading from the image file for all image elements that do not have at least one of the "width", "height" or "scale" options.

An editor macro may insert a template with :width: and :height: either read from the image file or set to a fixed default. (Since [feature-requests:#102] is fixed, Docutils 0.22 will support CSS style-sheet rules to override :widht: and :height: if these use unitless values.) 


---

**[feature-requests:#113] scale option in docutils.conf**

**Status:** open
**Group:** Default
**Created:** Mon Apr 21, 2025 08:39 PM UTC by Aaron Schif
**Last Updated:** Wed Apr 23, 2025 02:50 PM UTC
**Owner:** nobody


I would like all the images in the generated html to have width and height attributes to prevent content flashes. This is especially important with `loading: lazy`. The code to do this already mostly exists, but would be automatic if only I could set a default to `scale: 100%'.


---

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

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

[Docutils-develop] [docutils:feature-requests] #44 Add :figname: option to the figure directive

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

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

Commit [r10102] adds a "figname" option to the figure directive.



---

**[feature-requests:#44] Add :figname: option to the figure directive**

**Status:** open-fixed
**Group:** Default
**Created:** Wed Mar 11, 2015 03:25 PM UTC by Jellby
**Last Updated:** Fri Aug 30, 2024 12:08 PM UTC
**Owner:** nobody


As suggested in https://sourceforge.net/p/docutils/bugs/274/, I fill a feature request for a :figname: option to figure, so I can add a name to a figure and not to the image inside.


---

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

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

[Docutils-develop] [docutils:bugs] #489 Issues with the Docutils Doctree

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

- **status**: closed-fixed --> open
- Attachments has changed:

Diff:

~~~~

--- old
+++ new
@@ -0,0 +1 @@
+0001-Doctree-amendment-System-messages-can-appear-in-plac.patch (5.5 kB; text/x-patch)

~~~~

- **Comment**:

A new problem: System messages  in  `<line_block>`s.

According to the *Docutils Generic DTD*, `<line_block>`s may contain `<line>`s and nested `<line_block>`s, nothing else.

The file ``test/test_parsers/test_rst/test_line_blocks.py`` contains
a test case stating that "System messages can appear in place of lines."
This is also the current behaviour of the rST parser.

To solve this discrepancy, there are two alternatives:

a) Change the DTD and the Document Tree documentation to add this special case. The attached patch implements this approach
+1 simpler to implement
-1 more complex rules for the "Docutils Document Model" (Doctree).

b) Change the rST parser to place system messages *after* `<line_block>` elements.
+1 simpler "Docutils Document Model"
-1 change in rST parser behaviour.






---

**[bugs:#489] Issues with the Docutils Doctree**

**Status:** open
**Created:** Tue Jun 11, 2024 12:13 PM UTC by Günter Milde
**Last Updated:** Mon Nov 18, 2024 12:58 PM UTC
**Owner:** nobody
**Attachments:**

- [0001-Doctree-amendment-System-messages-can-appear-in-plac.patch](https://sourceforge.net/p/docutils/bugs/489/attachment/0001-Doctree-amendment-System-messages-can-appear-in-plac.patch) (5.5 kB; text/x-patch)


There are a number of discrepancies between the [Docutils Generic DTD][docutils.dtd]
and the implementation in Docutils code.

footnote
--------

[docutils.dtd][docutils.dtd]: `(label?, (%body.elements;)+)`
→ Label **optional**, content **required**; (not changed since 2002-04-20).

[reStructureText Markup Specification][rST spec]:
> Each footnote consists of an explicit markup start (".. "), a left
> square bracket, **the footnote label**, a right square bracket, and
> whitespace, followed by indented body elements.

The `footnote` class in [docutils.nodes](https://docutils.sourceforge.io/docutils/nodes.py) is a subclass of `Labeled`, 
whose docstring says: "**Contains a label** as its first element."

The rST parser **requires** a label but allows **empty footnotes**
(cf. `test/test_writers/test_latex2e.py`).

citation
--------

[docutils.dtd][docutils.dtd]: `(label, (%body.elements;)+)`
→ Label **required**, content **required**; (not changed since 2002-04-20).

[reStructureText Markup Specification][rST spec]:
> Citations are **identical to footnotes** except that they use only
> non-numeric labels …

The rST parser allows **empty citations** (cf. test_rst/test_citations.py).

figure
------

[docutils.dtd][docutils.dtd]: `(image, ((caption, legend?) | legend))`
→ caption or legend **required**; (not changed since 2002-04-20).

[reStructuredText Directives](https://docutils.sourceforge.io/docs/ref/rst/directives.html#figure)

> A "figure" consists of image data (including image options), an **optional
> caption** (a single paragraph), and an **optional legend** (arbitrary body
> elements). For page-based output media, figures might float to a different
> position if this helps the page layout.

The rST parser allows **figures without caption or legend**.

Docutils HTML and LaTeX writers use a different layout for figures vs.
images. They can handle figures without caption/legend.

Suggestion
----------

* Make *footnote label compulsory`*.
* Let rST report a *warning for empty footnote and citation*.
  Remove tests with empty footnote and citation.
* Allow *figures without caption/legend* in the Docutils Generic DTD.

(Change in Docutils 1.0, announce in 0.22.)

Questions
---------
Are there a use cases for 
* footnotes without label,
* footnotes without content,
* citations without content?

[docutils.dtd]: https://docutils.sourceforge.io/docs/ref/docutils.dtd
[rST spec]: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html



---

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

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

[Docutils-develop] [docutils:feature-requests] #113 scale option in docutils.conf

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

Mind, that setting "scale" on an image/figure without explicitely set "height" and "width" starts an attempt to get the image size from the image file on the local file system. In addition to slowing down compilation time, this raises a warning for all non-available (e.g. external) image URIs. 
This means, that in addition to a configuration setting we would need a convention how to override this setting so that individual images will *not* be read from the local file system. Something like `:scale: None`, `:scale: orginal`, or `:scale: False` that is currently not a valid argument for the scale option. Alternatively, the "senseless" special value `:scale: 0` may be used.


---

**[feature-requests:#113] scale option in docutils.conf**

**Status:** open
**Group:** Default
**Created:** Mon Apr 21, 2025 08:39 PM UTC by Aaron Schif
**Last Updated:** Mon Apr 21, 2025 08:39 PM UTC
**Owner:** nobody


I would like all the images in the generated html to have width and height attributes to prevent content flashes. This is especially important with `loading: lazy`. The code to do this already mostly exists, but would be automatic if only I could set a default to `scale: 100%'.


---

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

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

[Docutils-develop] [docutils:feature-requests] #111 Docutils Enhancement Proposals

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

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

Committed in [r10101].



---

**[feature-requests:#111] Docutils Enhancement Proposals**

**Status:** open-fixed
**Group:** Default
**Created:** Thu Feb 13, 2025 10:05 PM UTC by Günter Milde
**Last Updated:** Wed Apr 09, 2025 03:18 PM UTC
**Owner:** nobody
**Attachments:**

- [0001-Set-up-enhancement-proposals-in-developer-documentat.patch](https://sourceforge.net/p/docutils/feature-requests/111/attachment/0001-Set-up-enhancement-proposals-in-developer-documentat.patch) (25.9 kB; text/x-patch)
- [ep-001.html](https://sourceforge.net/p/docutils/feature-requests/111/attachment/ep-001.html) (26.7 kB; text/html)


Set up a framework for *Docutils Enhancement Proposals*  as a mechanism for
  proposing major new features, collecting community input,
  and documenting important design decisions.
  
The *Docutils To Do List* and issue tickets on the project page are
sufficient for small changes or issues with an obvious solution.
However, we are missing a framework for complex cases with competing
alternatives and for documenting the internal processes at the Docutils
project.

Attached are a draft specification and a patch implementing EPs in the developer documentation.


---

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

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

[Docutils-develop] [docutils:bugs] #346 reST parser warns twice for short underline

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

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

Fixed in [r10093]. Thank you for the report.



---

**[bugs:#346] reST parser warns twice for short underline**

**Status:** open-fixed
**Created:** Sun Jul 29, 2018 11:37 AM UTC by Takeshi KOMIYA
**Last Updated:** Sat Apr 05, 2025 09:56 AM UTC
**Owner:** nobody


reST parser warns twice if the underline for second heading is short.
I think it is a bit verbose.

Input:
~~~
$ cat helper.rst
Issue #5214
===========

django_assert_num_queries
========
~~~
Output (warnings):
~~~
$ rst2html.py helpers.rst > /dev/null
helpers.rst:5: (WARNING/2) Title underline too short.

django_assert_num_queries
========
helpers.rst:5: (WARNING/2) Title underline too short.

django_assert_num_queries
========
~~~

It seems the parser does not warn if the short underline appears at first.

Note: originately this was reported to sphinx:  https://github.com/sphinx-doc/sphinx/issues/5214


---

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

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

[Docutils-develop] [docutils:patches] #213 Change section handling to not rely on exceptions and reparsing

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

An updated version of the patch is applied in [r10093].
Thank you for your patch.


---

**[patches:#213] Change section handling to not rely on exceptions and reparsing**

**Status:** open
**Group:** None
**Created:** Wed Mar 26, 2025 07:57 PM UTC by Arne Skjærholt
**Last Updated:** Thu Apr 17, 2025 09:47 PM UTC
**Owner:** nobody
**Attachments:**

- [section-handling.patch](https://sourceforge.net/p/docutils/patches/213/attachment/section-handling.patch) (13.3 kB; text/x-patch)


While waiting for responses to an email I sent to the -users I decided to dig further into the issue and ended up implementing a fix. To recap my issue, I was having problems with a custom directive's nested parse of its content when section headers were used, because the existing code throws an EOFError up the chain to find the correct place to attach a new section.

The proposed patch changes this by adding an explicit stack of sections to the memo object instead of using the Python call stack, and changing RSTState.section() to unwind this state in-place, instead of using exception throwing to find the right place. In fact, I think this is the kind of implementation suggested as an alternative in a comment in the existing code. This also lets us get rid of memo.section_bubble_up_kludge and Line.eofcheck, which only existed to handle the exceptions.

In addition to the changed code, I've had to make six changes to the test suite.

- Three diagnostics in test/functional/expected/standalone_rst_pseudoxml.txt now have line numbers relative to the beginning of the file rather than some other element. I think because we no longer initiate a nested parse for sections.
- Two diagnostics in test/test_parsers/test_rst/test_targets.py have different line numbers, indicating the second conflicting label, rather than the implicit label generated by the section. I think the reason is that due to the exception throwing approach, the existing code handled the section label later than the other, even if the section is earlier in the text.
- test/test_parsers/test_rst/test_section_headers.py has one diagnostic output less. I think this diagnostic is a duplicate, caused by the rethrowing of the exception for bubbling up the stack.




---

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

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

[Docutils-develop] [docutils:patches] Re: #213 Change section handling to not rely on exceptions and reparsing

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

Line numbers in rst_pseudoxml.txt are fixed in [r10078].


---

**[patches:#213] Change section handling to not rely on exceptions and reparsing**

**Status:** open
**Group:** None
**Created:** Wed Mar 26, 2025 07:57 PM UTC by Arne Skjærholt
**Last Updated:** Wed Apr 09, 2025 01:52 PM UTC
**Owner:** nobody
**Attachments:**

- [section-handling.patch](https://sourceforge.net/p/docutils/patches/213/attachment/section-handling.patch) (13.3 kB; text/x-patch)


While waiting for responses to an email I sent to the -users I decided to dig further into the issue and ended up implementing a fix. To recap my issue, I was having problems with a custom directive's nested parse of its content when section headers were used, because the existing code throws an EOFError up the chain to find the correct place to attach a new section.

The proposed patch changes this by adding an explicit stack of sections to the memo object instead of using the Python call stack, and changing RSTState.section() to unwind this state in-place, instead of using exception throwing to find the right place. In fact, I think this is the kind of implementation suggested as an alternative in a comment in the existing code. This also lets us get rid of memo.section_bubble_up_kludge and Line.eofcheck, which only existed to handle the exceptions.

In addition to the changed code, I've had to make six changes to the test suite.

- Three diagnostics in test/functional/expected/standalone_rst_pseudoxml.txt now have line numbers relative to the beginning of the file rather than some other element. I think because we no longer initiate a nested parse for sections.
- Two diagnostics in test/test_parsers/test_rst/test_targets.py have different line numbers, indicating the second conflicting label, rather than the implicit label generated by the section. I think the reason is that due to the exception throwing approach, the existing code handled the section label later than the other, even if the section is earlier in the text.
- test/test_parsers/test_rst/test_section_headers.py has one diagnostic output less. I think this diagnostic is a duplicate, caused by the rethrowing of the exception for bubbling up the stack.




---

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

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

[Docutils-develop] [docutils:patches] #132 Add SOURCE_DATE_EPOCH support to date directive

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

- **Comment**:

SOURCE_DATE_EPOCH seems to be established as a means for reproducible builds by now in a way that whenever someone were met by unexpected behaviour due to accident, a prank, or a malign actor a simple internet search may help to find the cause.
Hence I remove my objection and suggest that Docutils 1.0 will consider this environment variable.
In addition to the patch from Debian, we will need a patch for the documentation and a test case.



---

**[patches:#132] Add SOURCE_DATE_EPOCH support to date directive**

**Status:** pending-remind
**Group:** None
**Created:** Sun Jul 24, 2016 05:49 PM UTC by Dmitry Shachnev
**Last Updated:** Thu Jul 28, 2016 03:20 PM UTC
**Owner:** nobody
**Attachments:**

- [0001-Add-SOURCE_DATE_EPOCH-support-to-the-date-directive.patch](https://sourceforge.net/p/docutils/patches/132/attachment/0001-Add-SOURCE_DATE_EPOCH-support-to-the-date-directive.patch) (1.1 kB; text/x-diff)


Recently, a number of projects [joined efforts](https://reproducible-builds.org/) to make the builds of their software reproducible. One of the goals of this effort is getting rid of timestamps in generated files, such as the documentation and man pages.

For this purpose, [a specification of `SOURCE_DATE_EPOCH`](https://reproducible-builds.org/specs/source-date-epoch/) environment variable was developed, which various build systems can set and various projects can read.

The attached patch (initially submitted by Chris Lamb to [Debian #831779](https://bugs.debian.org/831779)) adds support for that environment variable to docutils `date` directive.


---

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

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