docutils-develop Mailing List for Docutils: Documentation Utilities

Sphinx uses parentheses in the [:abbr: role](https://sphinx--13576.org.readthedocs.build/en/13576/usage/restructuredtext/roles.html#role-abbr), for example:
~~~
:abbr:`LIFO (last-in, first-out)` 
~~~
+1 looks "natural" in source form
- 1 used as generic syntax, this would require escaping all opening parentheses in role content.


---

**[feature-requests:#68] Adding syntax for role parameters**

**Status:** open
**Group:** Default
**Created:** Fri Jan 31, 2020 11:28 PM UTC by adam
**Last Updated:** Tue Dec 12, 2023 06:25 PM UTC
**Owner:** nobody


Hello Docutils team,

Sometimes I would like to pass options to role functions for adding domain-specific metadata. For example,

For citation page numbers:

~~~rst
As discussed in :cite:[p.99]`knuth1968`, the implementation ...
~~~

In a cookbook:
~~~rst
If you like, add some :liquid-ingredient:[20ml, spicyness=7]`Tabasco sauce`. 
~~~


As discussed in [this Docutils mailing-list thread](https://sourceforge.net/p/docutils/mailman/message/34894112/), AsciiDoc [uses a syntax](https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#images) like this:

~~~
Click image:icons/play.png[Play, title="Play"] to get the party started.
~~~

I like the idea of passing positional and named options in brackets.

Is there a possibility of Docutils supporting this feature? 


---

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.

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

Thanks for the fast feedback. The patch is now in the repository [r10135].



---

**[bugs:#500] Html5WriterPublishPartsTestCase.test_publish skips too much when with_pygments is False**

**Status:** open-fixed
**Created:** Mon May 19, 2025 10:15 AM UTC by Michał Górny
**Last Updated:** Tue May 20, 2025 12:24 PM UTC
**Owner:** nobody


While debugging something else, I've noticed that the `Html5WriterPublishPartsTestCase.test_publish()` case contains the following bit:

```
        for name, (settings_overrides, cases) in totest.items():
            if name == 'syntax_highlight' and not with_pygments:
                self.skipTest('syntax highlight requires pygments')
```

This means that if `with_pygments` is `False`, all the remaining cases from `totest` are skipped. If I replace it with:

```
        for name, (settings_overrides, cases) in totest.items():
            if name == 'syntax_highlight' and not with_pygments:
                continue
```

I see some test regressions too.


---

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.

Hei everyone,

the plan changed

0.22rc2 is for thursday may, 22

0.22 if nothing crops up tuesday june, 10th

all the best
 e

I can confirm that the patch makes tests pass for me — and it definitely looks more reliable in the long run. Thanks!


---

**[bugs:#500] Html5WriterPublishPartsTestCase.test_publish skips too much when with_pygments is False**

**Status:** open
**Created:** Mon May 19, 2025 10:15 AM UTC by Michał Górny
**Last Updated:** Tue May 20, 2025 11:53 AM UTC
**Owner:** nobody


While debugging something else, I've noticed that the `Html5WriterPublishPartsTestCase.test_publish()` case contains the following bit:

```
        for name, (settings_overrides, cases) in totest.items():
            if name == 'syntax_highlight' and not with_pygments:
                self.skipTest('syntax highlight requires pygments')
```

This means that if `with_pygments` is `False`, all the remaining cases from `totest` are skipped. If I replace it with:

```
        for name, (settings_overrides, cases) in totest.items():
            if name == 'syntax_highlight' and not with_pygments:
                continue
```

I see some test regressions too.


---

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.

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

PIL error outputs seem to be hard to predict. I got absolute paths with 
Python  3.9.2 / Pillow 9.1.1 and Python 3.11.2  / Pillow 9.4.0.
It also depends on whether `Image.open()` is passed a `str` or a `Path`.
Could you try the following patch? (It works here with the versions above.)
~~~
diff --git a/docutils/test/test_writers/test_html5_polyglot.py b/docutils/test/test_writers/test_html5_polyglot.py
index f31277a36..b2fc3cc23 100644
--- a/docutils/test/test_writers/test_html5_polyglot.py
+++ b/docutils/test/test_writers/test_html5_polyglot.py
@@ -41,13 +41,11 @@
 if PIL:
     REQUIRES_PIL = ''
     ONLY_LOCAL = 'Cannot get file path corresponding to https://dummy.png.'
-    DUMMY_PNG_NOT_FOUND = "[Errno 2] No such file or directory: 'dummy.png'"
-    # Pillow reports the absolute path since version 10.3.0 (cf. [bugs: 485])
-    # Backported to version 9.1 (or does it depend on the Python version)?
-    pil_version = tuple(int(i) for i in PIL.__version__.split('.'))
-    if pil_version >= (10, 3) or pil_version[0] == 9 and pil_version[1] >= 1:
-        DUMMY_PNG_NOT_FOUND = ("[Errno 2] No such file or directory: '%s'"
-                               % Path('dummy.png').resolve())
+    # Pillow versions vary in their error output (cf. bugs: #485 and #500)
+    try:
+        PIL.Image.open(Path('dummy.png'))
+    except OSError as err:
+        DUMMY_PNG_NOT_FOUND = str(err)
     HEIGHT_ATTR = 'height="32" '
     WIDTH_ATTR = 'width="32" '
     NO_PIL_SYSTEM_MESSAGE = ''
@@ -90,7 +88,7 @@ def test_publish(self):
                             **settings_overrides,
                         }
                     )
-                    self.assertEqual(case_expected, parts['body'])
+                    self.assertEqual(case_expected, parts[ 'body'])
 
 
 totest = {}  # expected samples contain only the "body" part of the HMTL output
~~~



---

**[bugs:#500] Html5WriterPublishPartsTestCase.test_publish skips too much when with_pygments is False**

**Status:** open
**Created:** Mon May 19, 2025 10:15 AM UTC by Michał Górny
**Last Updated:** Tue May 20, 2025 12:52 AM UTC
**Owner:** nobody


While debugging something else, I've noticed that the `Html5WriterPublishPartsTestCase.test_publish()` case contains the following bit:

```
        for name, (settings_overrides, cases) in totest.items():
            if name == 'syntax_highlight' and not with_pygments:
                self.skipTest('syntax highlight requires pygments')
```

This means that if `with_pygments` is `False`, all the remaining cases from `totest` are skipped. If I replace it with:

```
        for name, (settings_overrides, cases) in totest.items():
            if name == 'syntax_highlight' and not with_pygments:
                continue
```

I see some test regressions too.


---

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.

Thanks. However, the original issue that I tried to debug is: for me Pillow 11.2.1 produces relative paths, i.e. now I'm seeing:

```
======================================================================
FAIL: test_publish (test_writers.test_html5_polyglot.Html5WriterPublishPartsTestCase.test_publish) (id="totest['system_messages-PIL'][0]")
----------------------------------------------------------------------
Traceback (most recent call last):
  File "/tmp/docutils/docutils/test/test_writers/test_html5_polyglot.py", line 93, in test_publish
    self.assertEqual(case_expected, parts['body'])
AssertionError: '<img[305 chars]y: \'/tmp/docutils/docutils/test/dummy.png\'</[280 chars]e>\n' != '<img[305 chars]y: \'dummy.png\'</p>\n</aside>\n<aside class="[252 chars]e>\n'
  <img alt="dummy.png" src="dummy.png" />
  <aside class="system-message">
  <p class="system-message-title">System Message: WARNING/2 (<span class="docutils literal"><string></span>, line 1)</p>
  <p>Cannot scale image!
    Could not get size from "dummy.png":
-   [Errno 2] No such file or directory: '/tmp/docutils/docutils/test/dummy.png'</p>
?                                         ----------------------------
+   [Errno 2] No such file or directory: 'dummy.png'</p>
  </aside>
  <aside class="system-message">
  <p class="system-message-title">System Message: ERROR/3 (<span class="docutils literal"><string></span>, line 1)</p>
  <p>Cannot embed image "dummy.png":
    [Errno 2] No such file or directory: 'dummy.png'</p>
  </aside>


----------------------------------------------------------------------
Ran 2285 tests in 4.599s

FAILED (failures=1, skipped=4)
```

Do you want me to open a separate bug for that? I can reproduce with Python 3.11.12, 3.12.10, 3.13.3.


---

**[bugs:#500] Html5WriterPublishPartsTestCase.test_publish skips too much when with_pygments is False**

**Status:** open-fixed
**Created:** Mon May 19, 2025 10:15 AM UTC by Michał Górny
**Last Updated:** Mon May 19, 2025 09:14 PM UTC
**Owner:** nobody


While debugging something else, I've noticed that the `Html5WriterPublishPartsTestCase.test_publish()` case contains the following bit:

```
        for name, (settings_overrides, cases) in totest.items():
            if name == 'syntax_highlight' and not with_pygments:
                self.skipTest('syntax highlight requires pygments')
```

This means that if `with_pygments` is `False`, all the remaining cases from `totest` are skipped. If I replace it with:

```
        for name, (settings_overrides, cases) in totest.items():
            if name == 'syntax_highlight' and not with_pygments:
                continue
```

I see some test regressions too.


---

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.

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

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



---

**[bugs:#500] Html5WriterPublishPartsTestCase.test_publish skips too much when with_pygments is False**

**Status:** open-fixed
**Created:** Mon May 19, 2025 10:15 AM UTC by Michał Górny
**Last Updated:** Mon May 19, 2025 10:15 AM UTC
**Owner:** nobody


While debugging something else, I've noticed that the `Html5WriterPublishPartsTestCase.test_publish()` case contains the following bit:

```
        for name, (settings_overrides, cases) in totest.items():
            if name == 'syntax_highlight' and not with_pygments:
                self.skipTest('syntax highlight requires pygments')
```

This means that if `with_pygments` is `False`, all the remaining cases from `totest` are skipped. If I replace it with:

```
        for name, (settings_overrides, cases) in totest.items():
            if name == 'syntax_highlight' and not with_pygments:
                continue
```

I see some test regressions too.


---

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.

---

**[bugs:#500] Html5WriterPublishPartsTestCase.test_publish skips too much when with_pygments is False**

**Status:** open
**Created:** Mon May 19, 2025 10:15 AM UTC by Michał Górny
**Last Updated:** Mon May 19, 2025 10:15 AM UTC
**Owner:** nobody


While debugging something else, I've noticed that the `Html5WriterPublishPartsTestCase.test_publish()` case contains the following bit:

```
        for name, (settings_overrides, cases) in totest.items():
            if name == 'syntax_highlight' and not with_pygments:
                self.skipTest('syntax highlight requires pygments')
```

This means that if `with_pygments` is `False`, all the remaining cases from `totest` are skipped. If I replace it with:

```
        for name, (settings_overrides, cases) in totest.items():
            if name == 'syntax_highlight' and not with_pygments:
                continue
```

I see some test regressions too.


---

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.

On 2025-05-06, engelbert gruber wrote:

> hei everyone

> Subject: Re: release 0.22rc1 is out
> please try and test.

Thank you for the release.

> ... for details see https://docutils.sourceforge.io/HISTORY.html

... and, as usual for the summary of important and backwards incompatible 
changes the RELEASE-NOTES:
https://docutils.sourceforge.io/RELEASE-NOTES.html#release-0-22rc1-2025-05-06


I have some fixups in preparation.


There is a current problem in Sphinx compatibility tests:

  `Tests: regression with current docutils HEAD dependency`__

It is caused by commit [r10093] 
"Change section handling to not rely on exceptions and reparsing."

I don't know whether the problem is in Sphinx or just in the test-suite.
We should wait for a clarification/solution until releasing 0.22 final.

Günter

__ https://github.com/sphinx-doc/sphinx/issues/13539

hei everyone

please try and test.

Many changes for details see https://docutils.sourceforge.io/HISTORY.html


reStructuredText:
  - Support `CSS3 units`_. This adds "ch", "rem", "vw", "vh", "vmin",
    "vmax", and "Q" to the `supported length units`__. Note that some
    output formats don't support all units.

  - New option "figname" for the `"figure"`_ directive.

  .. _CSS3 units: https://www.w3.org/TR/css-values-3/#lengths
  __ docs/ref/rst/restructuredtext.html#length-units

Document Tree / Docutils DTD
  - Allow multiple <term> elements in a `\<definition_list_item>`__
    (third-party writers may need adaption).
  - The first element in a <figure> may also be a <reference>
    (with nested "clickable" <image>).

  __ docs/ref/doctree.html#definition-list-item

Configuration changes
  - Make MathML the default math_output_ for the "html5" writer.

  - Change the default input_encoding_ from ``None`` (auto-detect) to
"utf-8".

  - Drop short options ``-i`` and ``-o``.
    Use the long equivalents ``--input-encoding`` and ``--output-encoding``.
    (See `command line interface`_ for the rationale.)

  - Rename configuration setting "output" to "output_path_".

  - The manpage writer now recognizes the sections [writers] and
    [manpage writer] with the new setting `text_references`_.

Output changes
  LaTeX:
     Don't wrap references with custom reference-label_ in a ``\hyperref``
     command. The "hyperref" package generates hyperlinks for labels by
     default, so there is no change in the PDF (except for "ref*").

     Stop requiring "ifthen.sty". Replace use of
     ``\ifthenelse{\isundefined...`` with the eTeX primitive ``\ifdefined``.

  HTML5:
     Unitless image_ size measures__ are written as <img> "width" and
     "hight" values instead of "style" rules.  The current behaviour
     is kept for values with units, so users may specify, e.g. ``:width:
     50px`` instead of ``:width: 50`` to override CSS stylesheet rules.

     __ docs/ref/doctree.html#measure

  manpage:
     Don't UPPERCASE section headings.
     Handle hyperlink references (see text_references_).

  null:
     The "null" writer output changed from None to the empty string.

     `publish_string()` now returns a `bytes` or `str` instance
     for all writers (as documented).

New objects
  `parsers.docutils_xml`
     parser for `Docutils XML`_ (e.g., the output of the "xml" writer).
     Provisional.

     Try ``docutils --parser=xml test/data/multiple-term-definitions.xml``
     or use the :parser: option of the `"include"`_ directive to include
     an XML file in a rST document.

  `nodes.Element.validate()`
     Raise `nodes.ValidationError` if the element does not comply with
     the `Docutils Document Model`_.
     Provisional.

  `writers.DoctreeTranslator`
     Generic Docutils document tree translator base class with
     `uri2path()` auxiliary method.
     Provisional.

Removed objects
  `core.Publisher.setup_option_parser()`
     internal, obsolete,
  `frontend.ConfigParser.get_section()`
     obsoleted by the configparser's "Mapping Protocol Access",
  `frontend.OptionParser.set_defaults_from_dict()`
     obsolete,
  `nodes.Element.set_class()`
     obsolete, append to Element['classes'] directly,
  `parsers.rst.directives.tables.CSVTable.decode_from_csv()`
     not required with Python 3,
  `parsers.rst.directives.tables.CSVTable.encode_from_csv()`
     not required with Python 3,
  `transforms.writer_aux.Compound`
     not used since Dec 2010,
  `utils.error_reporting`
     obsolete in Python 3,
  `utils.Reporter.set_conditions()`
     obsolete, set attributes via configuration settings or directly.

Removed localisations
  Mistranslations of the "admonition" directive name:
     Use "advies" (af), "varsel" (da), "warnhinweis" (de), "aviso" (es),
     "sciigo" (eo), "annonce" (fr), "avviso" (it), "advies" (nl),
     "zauważenie" (pl) (introduced in Docutils 0.21)
     or the English name "admonition".

New files
  ``docutils/parsers/rst/include/html-roles.txt``
     `Standard definition file`_ for additional roles matching HTML tags.

Removed files
  ``tools/rst2odt_prepstyles.py``
     Obsoleted by `writers.odf_odt.prepstyles`.
  ``docutils/utils/roman.py``
     Obsoleted by ``docutils/utils/_roman_numerals.py``

Bugfixes and improvements (see HISTORY_).

 the manpage writer support for references is very, very late comer
 
* 0.20 only did put the reference content in italic, uri were skipped.
* 0.21 puts uris in angle bracketts, no option for macro
* 0.22 is the first one with real output of references, which no one bothered for years

so actually there is no api changing it is new
and very few users. i once tried to find man-pages created with the manpage writer that included http-addresses in the source text ... no findings in some hours

the only negative point in post boning is remembering 

cheers


---

**[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:** Wed Apr 30, 2025 07:10 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.

The general Docutils policy with incompatible API changes is to do them only after an advance warning and establishing a way to opt out is provided one release earlier. I.e.:

* provide the configuration setting in 0.22 with default to the current behaviour.
* announce that it will change to "macro-references: True" in the next release.
* change the default to True in Docutils 0.23 or 1.0 (whichever is next).

The advantage is, that "early adopters" can use the new behaviour without the need to change in the next version while users that depend on unchanged behaviour can safeguard now, before the change kicks in in the next relase and their project will be safe whatever Docutils version it is compiled with.


---

**[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:** Wed Apr 30, 2025 05:34 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.

I will make macro-references default

if no one objects


---

**[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 29, 2025 10:13 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.

hello everyone,

the plan

* freeze now, only small corrections to the code till release
* 0.22rc1 on tuesday may 6th
* 0.22 on tuesday may 21th if no stopper shows up.

after more than a year a lot of changes have accumulated, some

* General
  - We have started to add type hints to Docutils (feature-request #87).
    This will be a complex programme of work and as such,
    for the time being, these type hints are "provisional"
    and should not be relied upon.

    By default, the Python interpreter treats type hints as annotations.
    Python >= 3.10 is required with active type hints
    (``typing.TYPE_CHECKING == True``).
* docutils/frontend.py
  - Drop short options ``-i`` and ``-o`` for ``--input-encoding``
    and ``--output-encoding``.
* very many internal changes, to clarify and stabilize
* docutils/writers/_html_base.py
  - Make MathML the default math_output_.
  - ...
* docutils/writers/latex2e
  - Support SVG image inclusion with the "svg" LaTeX package (see the
  - and more
* docutils/writers/manpage.py
  - better reference (URI) support

in detail https://docutils.sourceforge.io/HISTORY.html


all the best
 e

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

Enhancement proposals can now be reached under https://docutils.sourceforge.io/docs/eps/index.html.



---

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

**Status:** closed-fixed
**Group:** Default
**Created:** Thu Feb 13, 2025 10:05 PM UTC by Günter Milde
**Last Updated:** Tue Apr 22, 2025 02:05 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.

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

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

- **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.

- **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.

- **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.

- **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.

- **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.

- **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.

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.

- **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.