docutils-develop — For developer discussions of the implementation.

[Docutils-develop] [docutils:feature-requests] #89 Public API, versioning, and deprecation

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

- Description has changed:

Diff:

~~~~

--- old
+++ new
@@ -1,6 +1,6 @@
 As requested by @milde in https://sourceforge.net/p/docutils/bugs/441/#7043/cdb8/8742/6e7f I'm opening this issue to allow for discussion on Docutils' public API, versioning policy, and deprecation.
 
-[enhancement proposal 10](https://docutils.sourceforge.io/docs/eps/ep-010.html) summarizes the discussion. It will be updated with new insights and decisions until a consensus is found.
+[Enhancement proposal 10](https://docutils.sourceforge.io/docs/eps/ep-010.html) summarizes the discussion. It will be updated with new insights and decisions until a consensus is found.
 
 This also relates to FR 87 on type annotations. 
 

~~~~




---

**[feature-requests:#89] Public API, versioning, and deprecation**

**Status:** open
**Group:** Default
**Created:** Sun Jan 16, 2022 01:39 AM UTC by Adam  Turner
**Last Updated:** Tue Apr 29, 2025 07:54 PM UTC
**Owner:** nobody


As requested by @milde in https://sourceforge.net/p/docutils/bugs/441/#7043/cdb8/8742/6e7f I'm opening this issue to allow for discussion on Docutils' public API, versioning policy, and deprecation.

[Enhancement proposal 10](https://docutils.sourceforge.io/docs/eps/ep-010.html) summarizes the discussion. It will be updated with new insights and decisions until a consensus is found.

This also relates to FR 87 on type annotations. 

From Günter, 

> The idea is to reconcile the reality (Docutils is used as if it were mature) and the version number (<1) once the API sufficiently defined a deprecation policy is agreed.

The only text I can find on library versioning is at https://docutils.sourceforge.io/docs/dev/policies.html#version-identification, excerpt below:

> **Major releases** (x.0, e.g. 1.0) will be rare, and will
represent major changes in API, functionality, or commitment.  The
major number will be bumped to 1 when the project is
feature-complete, and may be incremented later if there is a major
change in the design or API.  When Docutils reaches version 1.0,
the major APIs will be considered frozen.
For details, see the `backwards compatibility policy`_.

> Releases that change the minor number (x.y, e.g. 0.5) will be
**feature releases**; new features from the `Docutils core`_ will
be included.

> Releases that change the micro number (x.y.z, e.g. 0.4.1) will be
**bug-fix releases**.  No new features will be introduced in these
releases; only bug fixes will be included.

The proposed backwards compatability policy reads:

> Docutils' backwards compatibility policy follows the rules for Python in
PEP 387. ... The scope of the public API is laid out at the start of the backwards
  compatibility rules

I propose two modifications to the policies, which will make future changes to Docutils easier to review and reason about, for project members as well as outside contributors. 

Firstly, I propose adopting a formal versioning "system" such as Sematic Versioning ([SemVer](https://semver.org/)) or Calendar Versioning ([CalVer](https://calver.org/)). 

Semantic versioning is nearly identical to the current versioning policy, and has the benefit of being a known quantity, reducing misunderstandings. A potential phrasing would be:

**"Docutils follows SemVer. All changes must also follow the backwards compatability policy."**

What this does change is that the API is never considered complete, as in the original phrasing. Docutils [isn't slated for inclusion](https://www.python.org/dev/peps/pep-0258/#rejection-notice) in the standard library any more, and there will always be potential improvements and changes -- new parsers, new node types, changes in the HTML specification, et cetera. 

The 1.0 release then does not need to be a "big deal", and future breaking changes can go to 2.0, 3.0, etc -- setuptools is now on `60.5.0`!

Semantic versioning does have some drawbacks (https://snarky.ca/why-i-dont-like-semver/), so projects like pip have adopted calendar based versioning -- the major version is the year (22), and the minor version is either the current month or an increasing number.  This relies on strong documentation and changelogs, so that when users upgrade it is obvious what changed (the idea being that every change breaks someone, so there is no contract that version numbers within a certain range mean no breakage). Luckily, Docutils has a good culture around changelogs and histories etc, so this would be easy to adopt.

______


I also suggest enumerating all modules, classes, and functions that form the public API. The current backwards compatability policy references PEP 387, which is specifically for the Python project itself. Checking through the documentation on every change to identify if a name is public or private is error prone (we are all human, and can miss things with no malintent) and time consuming.

At the very least I would suggest, `docutils.nodes`, the reader/writer/parser aliases, `docutils.core`,  and the front end tools. (I'm happy to write out the full list if you give me modules/etc that should be part of the public API). It would also be useful to identify what parts of Docutils large downstream consumers use, and either create higher level abstractions or mark those as public API. (I would suggest Sphinx and MyST-parser). 

It is also the [established practice](https://www.python.org/dev/peps/pep-0008/#descriptive-naming-styles) to mark names as private by prefixing them with an underscore. I suggest adopting this, as it gives strong guidance to downstream library authors what Docutils considers private and public. Making a private name public is far easier than going through a deprecation cycle for the reverse.

I'd suggest adding the ability to have exceptions to the policy, with removal after one minor version. My full suggested text is:

**"Removal or significant alteration of any members of the public API will only take place after the behaviour has been marked as deprecated for two minor releases. Certain changes may have a shorter deprecation period of one minor release. This requires at least two project members to be in favour of doing so, and no members against.**

**Changes that may affect end-users (e.g. by requiring changes to the configuration file or potentially breaking custom style sheets) should be announced with a FutureWarning."**

This post is intentionally opinionated so as to provide something to talk over / edit -- I'm not massively attached to any one thing!

A

----
for reference, amongst others, I took inspiration from:
https://setuptools.pypa.io/en/latest/development/releases.html
https://pip.pypa.io/en/latest/development/release-process/
https://numpy.org/neps/nep-0023-backwards-compatibility.html



---

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] #89 Public API, versioning, and deprecation

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

- Description has changed:

Diff:

~~~~

--- old
+++ new
@@ -1,4 +1,6 @@
 As requested by @milde in https://sourceforge.net/p/docutils/bugs/441/#7043/cdb8/8742/6e7f I'm opening this issue to allow for discussion on Docutils' public API, versioning policy, and deprecation.
+
+[enhancement proposal 10](https://docutils.sourceforge.io/docs/eps/ep-010.html) summarizes the discussion. It will be updated with new insights and decisions until a consensus is found.
 
 This also relates to FR 87 on type annotations. 
 

~~~~




---

**[feature-requests:#89] Public API, versioning, and deprecation**

**Status:** open
**Group:** Default
**Created:** Sun Jan 16, 2022 01:39 AM UTC by Adam  Turner
**Last Updated:** Wed Feb 23, 2022 09:53 PM UTC
**Owner:** nobody


As requested by @milde in https://sourceforge.net/p/docutils/bugs/441/#7043/cdb8/8742/6e7f I'm opening this issue to allow for discussion on Docutils' public API, versioning policy, and deprecation.

[enhancement proposal 10](https://docutils.sourceforge.io/docs/eps/ep-010.html) summarizes the discussion. It will be updated with new insights and decisions until a consensus is found.

This also relates to FR 87 on type annotations. 

From Günter, 

> The idea is to reconcile the reality (Docutils is used as if it were mature) and the version number (<1) once the API sufficiently defined a deprecation policy is agreed.

The only text I can find on library versioning is at https://docutils.sourceforge.io/docs/dev/policies.html#version-identification, excerpt below:

> **Major releases** (x.0, e.g. 1.0) will be rare, and will
represent major changes in API, functionality, or commitment.  The
major number will be bumped to 1 when the project is
feature-complete, and may be incremented later if there is a major
change in the design or API.  When Docutils reaches version 1.0,
the major APIs will be considered frozen.
For details, see the `backwards compatibility policy`_.

> Releases that change the minor number (x.y, e.g. 0.5) will be
**feature releases**; new features from the `Docutils core`_ will
be included.

> Releases that change the micro number (x.y.z, e.g. 0.4.1) will be
**bug-fix releases**.  No new features will be introduced in these
releases; only bug fixes will be included.

The proposed backwards compatability policy reads:

> Docutils' backwards compatibility policy follows the rules for Python in
PEP 387. ... The scope of the public API is laid out at the start of the backwards
  compatibility rules

I propose two modifications to the policies, which will make future changes to Docutils easier to review and reason about, for project members as well as outside contributors. 

Firstly, I propose adopting a formal versioning "system" such as Sematic Versioning ([SemVer](https://semver.org/)) or Calendar Versioning ([CalVer](https://calver.org/)). 

Semantic versioning is nearly identical to the current versioning policy, and has the benefit of being a known quantity, reducing misunderstandings. A potential phrasing would be:

**"Docutils follows SemVer. All changes must also follow the backwards compatability policy."**

What this does change is that the API is never considered complete, as in the original phrasing. Docutils [isn't slated for inclusion](https://www.python.org/dev/peps/pep-0258/#rejection-notice) in the standard library any more, and there will always be potential improvements and changes -- new parsers, new node types, changes in the HTML specification, et cetera. 

The 1.0 release then does not need to be a "big deal", and future breaking changes can go to 2.0, 3.0, etc -- setuptools is now on `60.5.0`!

Semantic versioning does have some drawbacks (https://snarky.ca/why-i-dont-like-semver/), so projects like pip have adopted calendar based versioning -- the major version is the year (22), and the minor version is either the current month or an increasing number.  This relies on strong documentation and changelogs, so that when users upgrade it is obvious what changed (the idea being that every change breaks someone, so there is no contract that version numbers within a certain range mean no breakage). Luckily, Docutils has a good culture around changelogs and histories etc, so this would be easy to adopt.

______


I also suggest enumerating all modules, classes, and functions that form the public API. The current backwards compatability policy references PEP 387, which is specifically for the Python project itself. Checking through the documentation on every change to identify if a name is public or private is error prone (we are all human, and can miss things with no malintent) and time consuming.

At the very least I would suggest, `docutils.nodes`, the reader/writer/parser aliases, `docutils.core`,  and the front end tools. (I'm happy to write out the full list if you give me modules/etc that should be part of the public API). It would also be useful to identify what parts of Docutils large downstream consumers use, and either create higher level abstractions or mark those as public API. (I would suggest Sphinx and MyST-parser). 

It is also the [established practice](https://www.python.org/dev/peps/pep-0008/#descriptive-naming-styles) to mark names as private by prefixing them with an underscore. I suggest adopting this, as it gives strong guidance to downstream library authors what Docutils considers private and public. Making a private name public is far easier than going through a deprecation cycle for the reverse.

I'd suggest adding the ability to have exceptions to the policy, with removal after one minor version. My full suggested text is:

**"Removal or significant alteration of any members of the public API will only take place after the behaviour has been marked as deprecated for two minor releases. Certain changes may have a shorter deprecation period of one minor release. This requires at least two project members to be in favour of doing so, and no members against.**

**Changes that may affect end-users (e.g. by requiring changes to the configuration file or potentially breaking custom style sheets) should be announced with a FutureWarning."**

This post is intentionally opinionated so as to provide something to talk over / edit -- I'm not massively attached to any one thing!

A

----
for reference, amongst others, I took inspiration from:
https://setuptools.pypa.io/en/latest/development/releases.html
https://pip.pypa.io/en/latest/development/release-process/
https://numpy.org/neps/nep-0023-backwards-compatibility.html



---

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] #36 prevent accidential file overwrites by wildcard expansion

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

- **status**: open-accepted --> pending
- **Comment**:

This is a work in progress due to backwards incompatible changes. It will be finished in Docutils2.0.



---

**[feature-requests:#36] prevent accidential file overwrites by wildcard expansion**

**Status:** pending
**Group:** Default
**Created:** Fri Mar 15, 2013 10:43 PM UTC by Jakub Wilk
**Last Updated:** Tue Apr 18, 2023 11:51 AM UTC
**Owner:** nobody


A Debian user complained that if you use a wildcard as input file name, and the wildcard unexpectedly expands to two names, then rst2html will overwrite your files:
http://bugs.debian.org/654690

Would if be possible to add an option for not overwriting output files, that you could add to your configuration file, and later override from command line if needed?



---

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] #66 allow more characters when transforming "names" to "ids".

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

- **assigned_to**: David Goodger -->  nobody 



---

**[feature-requests:#66] allow more characters when transforming "names" to "ids".**

**Status:** pending
**Group:** Default
**Created:** Mon Sep 30, 2019 05:30 PM UTC by Roland Puntaier
**Last Updated:** Thu Mar 28, 2024 08:36 PM UTC
**Owner:** nobody


    `` encloses a role. There is a default role, else :<role>:`text`

    _ in front, is the special target role. For one word the backtick can be dropped.

    _`__init__` should produce a target named "__init__".

But instead the produced target is "init".
The backtick avoids ambiguity. There is no need for this behavior.



---

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] #62 code-block should support :caption:

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

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



---

**[feature-requests:#62] code-block should support :caption:**

**Status:** pending
**Group:** Default
**Created:** Tue Apr 09, 2019 09:50 AM UTC by Roberto Polli
**Last Updated:** Tue Apr 29, 2025 07:03 PM UTC
**Owner:** nobody


## I expect

This to work

    .. code-block:: 
        :caption: Hello
          
          print("ciao")
 
 ## Instead
 
 D000 Error in "code-block" directive:
unknown option: "caption".




---

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] #62 code-block should support :caption:

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

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



---

**[feature-requests:#62] code-block should support :caption:**

**Status:** pending-moreinfo
**Group:** Default
**Created:** Tue Apr 09, 2019 09:50 AM UTC by Roberto Polli
**Last Updated:** Sat Oct 19, 2024 10:18 AM UTC
**Owner:** nobody


## I expect

This to work

    .. code-block:: 
        :caption: Hello
          
          print("ciao")
 
 ## Instead
 
 D000 Error in "code-block" directive:
unknown option: "caption".




---

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] #92 Warn of problematic characters.

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

- **status**: open --> closed-later
- **Comment**:

Idea moved to the developer documentation (todo.rst).



---

**[feature-requests:#92] Warn of problematic characters.**

**Status:** closed-later
**Group:** Default
**Created:** Wed Jul 06, 2022 07:41 AM UTC by Günter Milde
**Last Updated:** Wed Jul 06, 2022 07:41 AM UTC
**Owner:** nobody


Unprintable characters like NULL in the rST source are most probable an indication of a problem
(corrupt source file, wrong encoding, ...). 
The same goes for combining characters at the start of a line, etc.
It may be helpful, if Docutils issued a Warning for problematic characters in the source (except for literals).


---

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] #56 :key:value not caught as badly formed option, but rather taken as an argument

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

- **status**: open --> pending
- **Priority**: 5 --> 3



---

**[feature-requests:#56] :key:value not caught as badly formed option, but rather taken as an argument**

**Status:** pending
**Group:** Default
**Created:** Fri Oct 13, 2017 09:44 AM UTC by Robin Shannon
**Last Updated:** Tue Oct 17, 2017 01:53 PM UTC
**Owner:** nobody


If your mistype your reST directive like this:

.. directive:: argument
    :key:value (note the lack of a space between ":" and "v")
    
docutils interprests this as a directive with two arguments (argument, :key:value) instead on one argument and an option key value pair. It seems like it would be nice if there was a check for the final argument given (if more than one argument is given) along the lines of:

 _emptystr, key, _emptystr, value = re.split(r"^\:(.*?)\:(.*?)", arg)
            if key in self.option_spec and key not in self.options:
                RAISE WARNING
    


---

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

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

many many thanks for the thorough testing


---

**[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:24 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...c),
`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...c> ), 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...c), 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:feature-requests] #84 Recognize syntax for optional and repeating arguments in option lists

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

- **status**: open --> pending
- **Priority**: 5 --> 3
- **Comment**:

Updating the option-list recognition rules to match the output of Pythons standard "argparse" module should be considered (but is not the priority problem right now).



---

**[feature-requests:#84] Recognize syntax for optional and repeating arguments in option lists**

**Status:** pending
**Group:** Default
**Labels:** reStructuredText 
**Created:** Mon Nov 01, 2021 05:44 PM UTC by Alkis Georgopoulos
**Last Updated:** Tue May 03, 2022 09:46 AM UTC
**Owner:** nobody


The [option-lists specs](https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#option-lists) state that "the syntax for short and long POSIX options is based on the syntax supported by Python's [getopt.py](https://docs.python.org/3/library/getopt.html) module".

This doesn't allow for optional or repeating arguments. A couple of examples from the [man man page](https://manpages.debian.org/bullseye/man-db/man.1.en.html#OPTIONS):

```shell
--warnings[=warnings]  This is an argument with an optional value

-m system[,...]  This is an argument with a repeating value
```

My feature request is for the square brackets `[]` to become allowed in the option lists spec and implementation in a similar way as the less than / great than symbols `<>`.

This will allow us to use docutils even when some binaries in our project do need optional or repeating arguments.
(I'm currently evaluating if it would be appropriate to migrate the https://ltsp.org and https://epoptes.org documentation and [man pages](https://ltsp.org/man/ltsp-image/), from markdown to restructuredtext)


---

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] #113 scale option in docutils.conf

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

- **status**: open --> closed-rejected
- **Comment**:

I don't want to overburden the standard Docutils with too many features and options.
If there are questions around implementing this in an extension or external script, feel free to ask on the Docutils mail list or in private mail.
Thank you for the suggestion.



---

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

**Status:** closed-rejected
**Group:** Default
**Created:** Mon Apr 21, 2025 08:39 PM UTC by Aaron Schif
**Last Updated:** Wed Apr 23, 2025 06:57 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] #101 New "doctree" element for hard line breaks.

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

-1 for backslash at line-end as "hard line break" in reStructuredText. This would not fit nice with

> Escaped whitespace characters are removed from the output document together with the escaping backslash. This allows for character-level inline markup.
— https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#escaping-mechanism

Rather, I suggest "backslash + newline" as a line continuation syntax for, e.g. wrapping long section titles.

+1 for a representation of hard line breaks in the Docutils Document Model ("doctree") for use in generated content or markup parsers.
Open question:  should we introduce
* a new `<br>` element,
* a "magic" class value like "pre-wrap" (or "line-break"), or
* an "xml:space" attribute for `<inline>` elements.


---

**[feature-requests:#101] New "doctree" element for hard line breaks.**

**Status:** pending-moreinfo
**Group:** Default
**Created:** Tue Dec 12, 2023 08:16 PM UTC by Günter Milde
**Last Updated:** Mon Apr 28, 2025 07:25 PM UTC
**Owner:** nobody


Not providing for "hard line break elements" in the Docutils document model and reStructuredText syntax was a deliberate decision at the time these two were devised.

However, times have changed and there are new arguments and use-cases for hard line breaks.
(cf.  the  [comments in #85](https://sourceforge.net/p/docutils/feature-requests/85/#d02b)).
Something like a `<br>` inline node or special handling of `<inline class=line-break>` inline nodes may be considered. The latter would not change the document model and could be implemented at the writer level or via stylesheet rules.

Whether to add a reStructuredText syntax for hard line breaks can be decided independently.
The current rules require a non-white character in a role defined with `.. role:: line-break`.
    



---

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] #101 New "doctree" element for hard line breaks.

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

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

Instead of relying on a "magic" class value, we may also allow the "xml:space" attribute for `<inline>` elements and represent a hard line break in the Document Tree as space-preserving inline element containing a newline character.
Markup parsers (like MyST and pycmark) could translate an end-of-line backslash to
~~~ xml
    <inline xml:space=preserve>\n</inline>
~~~
Writers would need to check inline elements for xml:space and translate it accordingly (e.g. HTML may use `<span style="white-space:pre-wrap;">...<\span>` in the general case and `<br>` if the content is just one newline character.)

The advantage it that there is a precedence: the "xml:space" attribute is defined by the XML standard "to signal an intention that in that element, white space should be preserved by applications." https://www.w3.org/TR/REC-xml/#sec-white-space

The Doctree uses the "xml:space" attribute already for the `<address>, <comment>, <doctest_block>, <literal_block>, <math_block>`, and `<raw>` elements.
https://docutils.sourceforge.io/docs/ref/doctree.html#xml-space



---

**[feature-requests:#101] New "doctree" element for hard line breaks.**

**Status:** pending-moreinfo
**Group:** Default
**Created:** Tue Dec 12, 2023 08:16 PM UTC by Günter Milde
**Last Updated:** Tue Dec 12, 2023 08:16 PM UTC
**Owner:** nobody


Not providing for "hard line break elements" in the Docutils document model and reStructuredText syntax was a deliberate decision at the time these two were devised.

However, times have changed and there are new arguments and use-cases for hard line breaks.
(cf.  the  [comments in #85](https://sourceforge.net/p/docutils/feature-requests/85/#d02b)).
Something like a `<br>` inline node or special handling of `<inline class=line-break>` inline nodes may be considered. The latter would not change the document model and could be implemented at the writer level or via stylesheet rules.

Whether to add a reStructuredText syntax for hard line breaks can be decided independently.
The current rules require a non-white character in a role defined with `.. role:: line-break`.
    



---

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] #112 The the include directive does not allow configuring a parser

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

- **status**: pending-works-for-me --> closed-works-for-me



---

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

**Status:** closed-works-for-me
**Group:** Default
**Created:** Sat Apr 05, 2025 03:14 PM UTC by Gabriel P
**Last Updated:** Mon Apr 28, 2025 03:48 PM 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] #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...c 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...c),
`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...c> ), 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...c), 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...c),
`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...c> ), 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...c), 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...c),
`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...c> ), 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...c), 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.