docutils-develop — For developer discussions of the implementation.

[Docutils-develop] docutils 0.22rc4

[engelbert g. <eng...@gm...>]

Hei everyone,

next pre-release,

This release often works in clarifying things, thanks to all the testers
and many thanks to Günter for the work.

Changes that should be run through pre-release

* Drop the "name" option of the "target-notes" directive. (Report an
  error instead of silently ignoring the value.)

* New alias "rst-class" for the "class" directive to improve the
  compatibility with Sphinx.

* "Downgrade" targets generated from hyperlink references with embedded
  URI or alias from explicit to implicit (i.e. similar to the targets for
  sections, see implicit hyperlink targets for details).

thanks for your patience and help
 e

[Docutils-develop] [docutils:bugs] #502 Duplicate target not always recognized.

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

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



---

**[bugs:#502] Duplicate target not always recognized.**

**Status:** open
**Created:** Tue Jun 03, 2025 09:33 AM UTC by Günter Milde
**Last Updated:** Mon Jun 16, 2025 01:02 PM UTC
**Owner:** nobody


Hyperlinks with embedded alias generate both, a `<reference>` and a `<target>`. 
This allows simple references to the target:
~~~
See `here <example.html>`_.

As we have shown here_, ...
~~~
However, it may lead to duplicates:
~~~
_`Here` is an explicit inline target.

See `here <example.html>`_.

As we have shown here_, ...
~~~
The second target gives a WARNING `Duplicate explicit target name: "here".`
Using the reference name results in an ERROR `Duplicate target name, cannot be used as a unique reference: "here".`

However (in versions up to 0.22.rc2), the duplicate target is ignored in case of **embedded internal** targets:
~~~
_`Here` is an explicit inline target.

See `here <elsewhere_>`_.

As we have shown here_, ...

The target is _`elsewhere`.
~~~
There is no WARNING or ERROR and both references link to "elsewhere".

This is fixed in [r10151].


---

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] #502 Duplicate target not always recognized.

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

It seems, that up to now many users did not know that ````link text <target>`_```
creates a <target> with the reference name "link text".

The Sphinx rST primer did start with
~~~rst
Use ```Link text <https://domain.invalid/>`_`` for inline web links. 
~~~
without mentioning that this *named hyperlink reference with embedded URI* also generates a target.

The missing WARNING for *named hyperlink references with embedded alias* did contribute to the confusion. As a result, even the [Docutils Directives](https://docutils.sourceforge.io/docs/ref/rst/directives.html) documentation shows warnings after the fix in [r10151].

In order to avoid breaking lots of existing documents,  *named hyperlink references with embedded URI or alias* should not be interpreted as an explicit intention to create a target. 
Rather, like section titles, the  reference name should be treated as [**implicit** hyperlink targets]( https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#implicit-hyperlink-targets).




---

**[bugs:#502] Duplicate target not always recognized.**

**Status:** open-fixed
**Created:** Tue Jun 03, 2025 09:33 AM UTC by Günter Milde
**Last Updated:** Tue Jun 03, 2025 03:33 PM UTC
**Owner:** nobody


Hyperlinks with embedded alias generate both, a `<reference>` and a `<target>`. 
This allows simple references to the target:
~~~
See `here <example.html>`_.

As we have shown here_, ...
~~~
However, it may lead to duplicates:
~~~
_`Here` is an explicit inline target.

See `here <example.html>`_.

As we have shown here_, ...
~~~
The second target gives a WARNING `Duplicate explicit target name: "here".`
Using the reference name results in an ERROR `Duplicate target name, cannot be used as a unique reference: "here".`

However (in versions up to 0.22.rc2), the duplicate target is ignored in case of **embedded internal** targets:
~~~
_`Here` is an explicit inline target.

See `here <elsewhere_>`_.

As we have shown here_, ...

The target is _`elsewhere`.
~~~
There is no WARNING or ERROR and both references link to "elsewhere".

This is fixed in [r10151].


---

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] #504 errors for malformed tables do not indicate what the error is

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

Thank you for the report.

Note, that Docutils does report the line in the table for "simple" tables:
~~~
========================   =================
 Standard Code             Message(s)       
========================   =================
 M1, indicator undefined  Illegal reference
 M2, Invalid combination   None             
========================   =================
~~~
Compiling with `docutils` reports
~~~
/tmp/foo.rst:4: (ERROR/3) Malformed table.
Text in column margin in table line 4.
...
~~~


---

**[bugs:#504] errors for malformed tables do not indicate what the error is**

**Status:** open
**Created:** Thu Jun 05, 2025 09:04 PM UTC by Jynn Nelson
**Last Updated:** Thu Jun 05, 2025 09:04 PM UTC
**Owner:** nobody
**Attachments:**

- [table.rst](https://sourceforge.net/p/docutils/bugs/504/attachment/table.rst) (1.1 kB; application/octet-stream)


The error messages for malformed tables are quite long and do not indicate where the error occurred. I expect docutils to point at a single line of code, and say why it was malformed. Instead it points at the whole table and just says "malformed table".

~~~
$ grep PRETTY /etc/os-release
PRETTY_NAME="Pop!_OS 22.04 LTS"
$ python -V
Python 3.10.12
$ docutils -V
docutils (Docutils 0.21.2, Python 3.10.12, on linux)
$ docutils --traceback table.rst >/dev/null
table.rst:5: (ERROR/3) Malformed table.

+-------------------------+-------------------+
| Standard Code           | Message(s)       |
+=========================+===================+
| M1, indicator undefined | Illegal reference |
+-------------------------+-------------------+
| M1, indicator undefined | Illegal reference |
+-------------------------+-------------------+
| M1, indicator undefined | Illegal reference |
+-------------------------+-------------------+
| M1, indicator undefined | Illegal reference |
+-------------------------+-------------------+
| M1, indicator undefined | Illegal reference |
+-------------------------+-------------------+
| M1, indicator undefined | Illegal reference |
+-------------------------+-------------------+
| M1, indicator undefined | Illegal reference |
+-------------------------+-------------------+
| M1, indicator undefined | Illegal reference |
+-------------------------+-------------------+
| M2, Invalid combination | None              |
+-------------------------+-------------------+
~~~

Note that docutils *does*  have the information to report this bug, because I can see it in a debugger. It simply doesn't include that info in the error.

~~~
$ python -m pdb $(which docutils) --traceback table.rst
> /home/jyn/.local/bin/docutils(3)<module>()
-> import re
(Pdb) break docutils/parsers/rst/states.py:1787
Breakpoint 1 at /home/jyn/.local/lib/python3.10/site-packages/docutils/parsers/rst/states.py:1787
(Pdb) c
> /home/jyn/.local/lib/python3.10/site-packages/docutils/parsers/rst/states.py(1787)malformed_table()
-> message = 'Malformed table.'
(Pdb) up
> /home/jyn/.local/lib/python3.10/site-packages/docutils/parsers/rst/states.py(1737)isolate_grid_table()
-> messages.extend(self.malformed_table(block))
(Pdb) list
1732 	            else:
1733 	                messages.extend(self.malformed_table(block))
1734 	                return [], messages, blank_finish
1735 	        for i in range(len(block)):     # check right edge
1736 	            if len(block[i]) != width or block[i][-1] not in '+|':
1737 ->	                messages.extend(self.malformed_table(block))
1738 	                return [], messages, blank_finish
1739 	        return block, messages, blank_finish
1740 	
1741 	    def isolate_simple_table(self):
1742 	        start = self.state_machine.line_offset
(Pdb) p block[i]
'| Standard Code           | Message(s)       |'
(Pdb) p width
47
(Pdb) p len(block[i])
46
~~~


---

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 0.22rc3 is out

[engelbert g. <eng...@gm...>]

Hei

minimal changes and fixes

manpage writer no longer drops the text of internal targets

0.22 in one week ... if ... :-)

cheers and thanks to günter
 e

[Docutils-develop] [docutils:bugs] #503 LaTeX writer fails to generate "labels" for some elements with "ids".

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

---

**[bugs:#503] LaTeX writer fails to generate "labels" for some elements with "ids".**

**Status:** open
**Created:** Wed Jun 04, 2025 04:34 PM UTC by Günter Milde
**Last Updated:** Wed Jun 04, 2025 04:34 PM UTC
**Owner:** nobody


Most doctree elements (nodes) accept the "ids" attribute that can be used as end-point for internal cross references.
In LaTeX, "ids" are represented as "labels". This is only implemented for a small subset of elements.
For example the internal hyperlink in 
~~~
.. note::
   :name: my-note
   
   This is an admonition with ID
   
Link to my-note_. 
~~~
does not work because there is no `\label{my-note}`  in the LaTeX output.

See also [Sphinx issue #13609](https://github.com/sphinx-doc/sphinx/issues/13609#issuecomment-2937289148).


---

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] #502 Duplicate target not always recognized.

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

- Description has changed:

Diff:

~~~~

--- old
+++ new
@@ -26,6 +26,6 @@
 
 The target is _`elsewhere`.
 ~~~
-There no WARNING or ERROR and both references link to "elsewhere".
+There is no WARNING or ERROR and both references link to "elsewhere".
 
 This is fixed in [r10151].

~~~~




---

**[bugs:#502] Duplicate target not always recognized.**

**Status:** open-fixed
**Created:** Tue Jun 03, 2025 09:33 AM UTC by Günter Milde
**Last Updated:** Tue Jun 03, 2025 09:33 AM UTC
**Owner:** nobody


Hyperlinks with embedded alias generate both, a `<reference>` and a `<target>`. 
This allows simple references to the target:
~~~
See `here <example.html>`_.

As we have shown here_, ...
~~~
However, it may lead to duplicates:
~~~
_`Here` is an explicit inline target.

See `here <example.html>`_.

As we have shown here_, ...
~~~
The second target gives a WARNING `Duplicate explicit target name: "here".`
Using the reference name results in an ERROR `Duplicate target name, cannot be used as a unique reference: "here".`

However (in versions up to 0.22.rc2), the duplicate target is ignored in case of **embedded internal** targets:
~~~
_`Here` is an explicit inline target.

See `here <elsewhere_>`_.

As we have shown here_, ...

The target is _`elsewhere`.
~~~
There is no WARNING or ERROR and both references link to "elsewhere".

This is fixed in [r10151].


---

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] #502 Duplicate target not always recognized.

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

---

**[bugs:#502] Duplicate target not always recognized.**

**Status:** open-fixed
**Created:** Tue Jun 03, 2025 09:33 AM UTC by Günter Milde
**Last Updated:** Tue Jun 03, 2025 09:33 AM UTC
**Owner:** nobody


Hyperlinks with embedded alias generate both, a `<reference>` and a `<target>`. 
This allows simple references to the target:
~~~
See `here <example.html>`_.

As we have shown here_, ...
~~~
However, it may lead to duplicates:
~~~
_`Here` is an explicit inline target.

See `here <example.html>`_.

As we have shown here_, ...
~~~
The second target gives a WARNING `Duplicate explicit target name: "here".`
Using the reference name results in an ERROR `Duplicate target name, cannot be used as a unique reference: "here".`

However (in versions up to 0.22.rc2), the duplicate target is ignored in case of **embedded internal** targets:
~~~
_`Here` is an explicit inline target.

See `here <elsewhere_>`_.

As we have shown here_, ...

The target is _`elsewhere`.
~~~
There no WARNING or ERROR and both references link to "elsewhere".

This is fixed in [r10151].


---

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] #501 Typo in "Docutils Links" page

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

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

This is fixed as part of a general update to the page in [r10148].

Thank you for reporting.



---

**[bugs:#501] Typo in "Docutils Links" page**

**Status:** open-fixed
**Created:** Sat May 31, 2025 11:20 AM UTC by Edward K. Ream
**Last Updated:** Sat May 31, 2025 11:20 AM UTC
**Owner:** nobody


The [Docutils Links](https://docutils.sourceforge.io/docs/user/links.html) page contains a typo concerning Leo:

Please change:
It can be used as IDE for **literal** programming,
to
It can be used as IDE for **literate** programming,

Thanks.




---

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] release 0.22rc2

[engelbert g. <eng...@gm...>]

Hei everyone,

only a few changes, but necessary ones to remedy 3rd party problems

please try, test

next release day for 0.22 on my schedule is tuesday june 10.

all the best
 e

* docutils/parsers/rst/directives/misc.py

  - Pass default settings to custom parser for included file.

* docutils/parsers/rst/states.py

  - Remove the list`states.RSTStateMachine.memo.section_parents`
    (introduced in Docutils 0.22rc1) that broke 3rd-party applications
    setting up a "mock memo".
  - Use `types.SimpleNamespace` instead of a local definition for
    the auxilliary class `states.Struct`.

* docutils/writers/_html_base.py

  - Fix error when determining the document metadata title from the
    source path and the internal `source` attribute is None.

[Docutils-develop] [docutils:feature-requests] #68 Adding syntax for role parameters

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

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.

[Docutils-develop] [docutils:bugs] #500 Html5WriterPublishPartsTestCase.test_publish skips too much when with_pygments is False

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

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

[Docutils-develop] docutils 0.22 release plan changed

[engelbert g. <eng...@gm...>]

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

[Docutils-develop] [docutils:bugs] #500 Html5WriterPublishPartsTestCase.test_publish skips too much when with_pygments is False

[Michał G. <mgo...@us...>]

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.

[Docutils-develop] [docutils:bugs] #500 Html5WriterPublishPartsTestCase.test_publish skips too much when with_pygments is False

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

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

[Docutils-develop] [docutils:bugs] Re: #500 Html5WriterPublishPartsTestCase.test_publish skips too much when with_pygments is False

[Michał G. <mgo...@us...>]

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.

[Docutils-develop] [docutils:bugs] #500 Html5WriterPublishPartsTestCase.test_publish skips too much when with_pygments is False

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

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

[Docutils-develop] [docutils:bugs] #500 Html5WriterPublishPartsTestCase.test_publish skips too much when with_pygments is False

[Michał G. <mgo...@us...>]

---

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

Re: [Docutils-develop] release 0.22rc1 is out

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

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

[Docutils-develop] release 0.22rc1 is out

[engelbert g. <eng...@gm...>]

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

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

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

 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.

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

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

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.

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

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

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.

[Docutils-develop] docutils 0.22 release plan

[engelbert g. <eng...@gm...>]

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

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

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

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