docutils-develop — For developer discussions of the implementation.

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

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

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

Fixed in Docutils 0.22. 
Commit [r10176]  makes targets from hyperlink references with embedded URI or alias implicit.



---

**[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:** 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:patches] #214 Give better messages on malformed tables

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

I looked at the patch and found a number of issues:

* Message "details" misleading if the right border is not misaligned but missing.

* system exit with corrupt bottom border:
   The compulsory "details" and "offset" arguments for `malformed_table()` lead to a system exit with traceback - for document authors this is worse than a generic error message. It is also an incompatible change in the Docutils library  (some 3rd party extension may use the function...).

       +-----------------------+
       | A table with one cell |
       | & corrupt bottom.     |
       +---------------------- +

* Indicated line for simple table with non-matching bottom border is wrong, if the table does not start on line 1 of the document!

* If there is no bottom border for a simple table, the complete remaining document may be scanned. Therefore it is both, simpler and more helpful to indicate the start line of a simple table with missing bottom border.

* The error "No bottom table border found or no blank line after table bottom." is raised because the markup is ambiguous:

        ==============  ======
        content or      header
        ==============  ======
        this could be   cell content
        or text after   the table

* According to the coding policy, lines should be < 80 characters.

The attached patch adresses these points and solves some more issues with the original code.


Attachments:

- [table-errors2.diff](https://sourceforge.net/p/docutils/patches/_discuss/thread/ecf1ca00d3/f025/attachment/table-errors2.diff) (7.6 kB; text/x-patch)


---

**[patches:#214] Give better messages on malformed tables**

**Status:** open
**Group:** None
**Created:** Sun Jun 08, 2025 05:58 PM UTC by Jynn Nelson
**Last Updated:** Sun Jul 20, 2025 09:57 PM UTC
**Owner:** nobody
**Attachments:**

- [tables.diff](https://sourceforge.net/p/docutils/patches/214/attachment/tables.diff) (5.2 kB; application/octet-stream)


This does several things:
- Specifies `Misaligned right border` for that error, instead of just "malformed table".
- Shows the line where each error happened, not the line where the table starts.
  - This had a complication that line numbers appear to be wrong when `include` directives are present (they include the lines in the source document, instead of being relative to the included document). Just disabled the new smarter logic in that case.
- Changes `malformed_table` to require both detail and an offset, so poor errors like this can't happen in the future.

Fixes https://sourceforge.net/p/docutils/bugs/504/.


---

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

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

[Docutils-develop] [docutils:bugs] #507 renamed files

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

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

Fixed. Thanks again.



---

**[bugs:#507] renamed files**

**Status:** closed-fixed
**Labels:** docs 
**Created:** Mon Jul 28, 2025 04:13 AM UTC by Chris Crawford
**Last Updated:** Tue Jul 29, 2025 07:43 AM UTC
**Owner:** nobody


some of the links are broken on 
https://docutils.sourceforge.io/rst.html
because .txt files were renamed to .rst:
https://docutils.sourceforge.io/docs/user/rst/quickstart.txt
https://docutils.sourceforge.io/docs/user/rst/cheatsheet.txt
there may be others


---

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

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

On 2025-07-29, engelbert gruber wrote:

> the final 0.22 is in the open

Thanks for the release.

Let's wait with new features and changes for some weeks, so we can easily
put out a 0.22.1 if required. Backwards-compatible bugfixes are welcome.

The first issue already came in: a release date typo reported in
docutils-users and corrected in the repo. As this is non-critical, we can
wait with a follow up release until there is more feedback.


Günter

[Docutils-develop] [docutils:patches] #187 Rename .txt files to .rst

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

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

The issue is fixed in Docutils 0.22 released 2025-07-29.
Thank you for the patch.




---

**[patches:#187] Rename .txt files to .rst**

**Status:** closed-fixed
**Group:** None
**Created:** Wed Jan 05, 2022 05:51 PM UTC by Adam  Turner
**Last Updated:** Thu Aug 15, 2024 08:20 AM UTC
**Owner:** Adam  Turner


This change is in two parts -- the first commit does the rename and the second goes through and updates references to .txt files. All tests pass.

The benefit of this change is primarily for people -- on user interfaces with syntax highlighting (e.g. IntelliJ / VSCode / Notepad++ editors, code mirrors, etc), the text is presented natively as reStructuredText, and editor features can assist with e.g. autocompletion.

Docutils itself of course does not care which file extension is used. 

I have not renamed any of the include files or template files in `docutils.parsers` or `docutils.writers`, as they form part of the public API and would need a deprecation cycle (or aliasing in the parsing code)

A

Please see https://github.com/AA-Turner/docutils/pull/3 and https://github.com/AA-Turner/docutils/pull/3.patch for the commits and patch.


---

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

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

[Docutils-develop] [docutils:patches] #211 Doctest nodes have incorrect `line` field

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

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

The patch is in Docutils 0.22 released 2025-07-29.
Thanks again.



---

**[patches:#211] Doctest nodes have incorrect `line` field **

**Status:** closed-accepted
**Group:** None
**Created:** Thu Sep 12, 2024 09:39 AM UTC by Hood Chatham
**Last Updated:** Mon Nov 11, 2024 05:40 PM UTC
**Owner:** nobody


For most nodes, `node.line` refers to the source line that the node started on. However, doctest nodes report the end line. 

This can be fixed with the following patch:
```patch
--- a/docutils/docutils/parsers/rst/states.py
+++ b/docutils/docutils/parsers/rst/states.py
@@ -1587,11 +1587,14 @@ def parse_option_marker(self, match):
         return optlist
 
     def doctest(self, match, context, next_state):
+        line = self.document.current_line
         data = '\n'.join(self.state_machine.get_text_block())
         # TODO: prepend class value ['pycon'] (Python Console)
         # parse with `directives.body.CodeBlock` (returns literal-block
         # with class "code" and syntax highlight markup).
-        self.parent += nodes.doctest_block(data, data)
+        n = nodes.doctest_block(data, data)
+        n.line = line
+        self.parent += n
         return [], next_state, []
 
     def line_block(self, match, context, next_state):
```



---

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

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

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

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

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

The issue is fixed in Docutils 0.22 released 2025-07-29.
Thank you for the patch.




---

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

**Status:** closed-fixed
**Group:** None
**Created:** Wed Mar 26, 2025 07:57 PM UTC by Arne Skjærholt
**Last Updated:** Fri Apr 25, 2025 10:37 AM UTC
**Owner:** nobody
**Attachments:**

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


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

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

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

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




---

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

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

[Docutils-develop] [docutils:feature-requests] #5 Emacs support; decoration styles

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

- **labels**:  --> emacs mode
- **Group**:  --> Default



---

**[feature-requests:#5] Emacs support; decoration styles**

**Status:** open-accepted
**Group:** Default
**Labels:** emacs mode 
**Created:** Wed Nov 16, 2005 08:42 AM UTC by Lalo Martins
**Last Updated:** Wed Nov 16, 2005 04:06 PM UTC
**Owner:** Martin Blais


The title decoration code allows for indentation in
over-and-under decorations \(rst-default-indent\).

In my "under" decorations, however, I like to run the
decoration one space bigger than the text.

Another style I have seen is to run decorations to the
full document width, regardless of the title text.  \(In
this style, over-and-under titles are usually centred.\)

It would be neat if rst.el had customizable options
allowing all these styles.

Suggestion: rst-right-only-indent for "under" decorations.

If rst-default-indent is nil \(rather than 0\), the
over-and-under deco goes to the right margin and the
text is centred.  If rst-right-only-indent is nil
\(rather than 0\), the "under" deco goes to the right margin.


---

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

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

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

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

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

The issue is fixed in Docutils 0.22 released 2025-07-29.
Thank you for reporting.



---

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

**Status:** closed-fixed
**Group:** Default
**Created:** Wed Mar 11, 2015 03:25 PM UTC by Jellby
**Last Updated:** Wed Apr 23, 2025 03:55 PM UTC
**Owner:** nobody


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


---

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

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

[Docutils-develop] [docutils:feature-requests] #57 add vh and vw as allowable length units

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

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

The issue is fixed in Docutils 0.22 released 2025-07-29.
Thank you for reporting.



---

**[feature-requests:#57] add vh and vw as allowable length units**

**Status:** closed-fixed
**Group:** Default
**Created:** Fri Oct 13, 2017 09:31 AM UTC by Robin Shannon
**Last Updated:** Tue Oct 01, 2024 07:22 AM UTC
**Owner:** nobody


In css, vh and vw are percentages of the view-window. It would be nice if these were added to the allowable length units (line 225 in parsers/rst/directives/__init__.py). For non html outputs it might make sense to convert them into percentages.


---

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

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

[Docutils-develop] [docutils:feature-requests] #60 Allow definition_list_item to have multiple terms

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

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



---

**[feature-requests:#60] Allow definition_list_item to have multiple terms**

**Status:** closed-fixed
**Group:** Default
**Created:** Thu Jan 03, 2019 09:10 AM UTC by Takeshi KOMIYA
**Last Updated:** Wed Jul 30, 2025 09:22 AM UTC
**Owner:** nobody
**Attachments:**

- [support_multiple_terms_on_definition_list_item.patch](https://sourceforge.net/p/docutils/feature-requests/60/attachment/support_multiple_terms_on_definition_list_item.patch) (3.7 kB; application/octet-stream)


In HTML  spec, definition list accepts multiple terms in a item.  This patch allows doctree model to have multiple terms as children of definition_list_item also.
https://www.w3.org/TR/html52/grouping-content.html#the-dl-element

In sphinx, a custom directive named "glossary" allows multiple terms for one definition_list_item.
https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#glossary


---

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

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

[Docutils-develop] [docutils:feature-requests] #60 Allow definition_list_item to have multiple terms

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

The issue is fixed in Docutils 0.22 released 2025-07-29.
Possible support in reStrucuredText markup is discussed in [patches:#95].
Thank you for reporting.



---

**[feature-requests:#60] Allow definition_list_item to have multiple terms**

**Status:** open-fixed
**Group:** Default
**Created:** Thu Jan 03, 2019 09:10 AM UTC by Takeshi KOMIYA
**Last Updated:** Sat Aug 31, 2024 10:35 AM UTC
**Owner:** nobody
**Attachments:**

- [support_multiple_terms_on_definition_list_item.patch](https://sourceforge.net/p/docutils/feature-requests/60/attachment/support_multiple_terms_on_definition_list_item.patch) (3.7 kB; application/octet-stream)


In HTML  spec, definition list accepts multiple terms in a item.  This patch allows doctree model to have multiple terms as children of definition_list_item also.
https://www.w3.org/TR/html52/grouping-content.html#the-dl-element

In sphinx, a custom directive named "glossary" allows multiple terms for one definition_list_item.
https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#glossary


---

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

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

[Docutils-develop] [docutils:feature-requests] #83 Support SVG images in LaTeX

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

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

The issue is fixed in Docutils 0.22 released 2025-07-29.
Thank you for reporting.




---

**[feature-requests:#83] Support SVG images in LaTeX**

**Status:** closed-fixed
**Group:** Default
**Created:** Sat Oct 09, 2021 12:05 AM UTC by Local State
**Last Updated:** Tue Dec 17, 2024 09:08 AM UTC
**Owner:** nobody


Hi there, this is Local State.

## Motivation
The current `Image` directive is not enough for svg files. Using `img` tag loses interactivities, and the width, and height can't be applied for svg files directly. It's better to use `style="width:50%"` instead. 

## 2 New Options
I'm hoping there could be 2 new options for `Image` directive.
    
   1. `tag`
        This would determine the html tag used to render the image. The default value would be `img`, and we could also use `object`, `iframe` and `embed` as alternatives. Currently, all images are rendered with `img` tag, which loses some interactivities (e.g., the text in svg file). We could avoid this by using `object` tag. I see there are some similar work in `html4css1` about `object_image_types`.  
        
        Example:
        ```
        <img src="a.png" width="50%" alt="alt msg">`
        <object data="a.png" style="width:50%">alt msg</object>
        <iframe src="a.png" width="50%" title="alt msg"></iframe>
        <embed src="a.png" width="50%">`
        ```
        
   2. `embed`
        If enabled, this option would embed the image into the html file using base64 encoding.  
        While I see there is already the if sentence in the `visit_image` function.
        ```
        if self.settings.embed_images or ('embed' in node):
        ```
        The `embed_images` could be set from command-line or setting, but I can't find how to satisfy the latter condition, since any node doesn't seem to have `embed` attribute. Could anyone tell me how to enable it? If we can't, then it's necessary to add the `embed` option, so that we could choose to embed one particular image or not. 
        Especially, I notice there exist a `todo` item for svg embedding. I'd like to implement it if possible. But the first option is still in demand, because most times we don't want our html files to be so large and need separate svg files.

##  Potential bugs
 
 svg files under `<img>` tag can't correctly render height and width if svg viewbox information is not contained in the file. It might be better to set the height and width in `style` indirectly.

##  Contribution
 I would like to fix and implement all these things if possible. But I'm not quite familiar with SourceForge and don't know how to submit a PR like what we do in github.


---

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

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

[Docutils-develop] [docutils:feature-requests] #94 Should docutils whine about nesting simple body elements?

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

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

The issue is fixed in Docutils 0.22 released 2025-07-29.
Thank you for reporting.




---

**[feature-requests:#94] Should docutils whine about nesting simple body elements?**

**Status:** closed-fixed
**Group:** Default
**Created:** Thu Feb 09, 2023 09:55 AM UTC by Julien Palard
**Last Updated:** Thu Jun 06, 2024 08:16 PM UTC
**Owner:** nobody


Context:

[This](https://github.com/python/cpython/blob/45fa12aec8f508c224a1521cfe3ae597f1026264/Doc/tools/extensions/pyspecific.py#L149) call to `nested_parse` adds a `Paragraph` node to a `Paragraph` node,  this look forbidden by [the doc](https://docutils.sourceforge.io/docs/ref/doctree.html#body-elements), and it also look to misbehave sphinx-side, when translating the document, where we completly loose the nested paragraph once translated.

It renders properly though when **not** translated.

The linked `nested_parse` returns:

```xml
<paragraph classes="availability">
    <pending_xref refdoc="index" refdomain="std" refexplicit="True" reftarget="availability" reftype="ref" refwarn="True">
        <inline classes="xref std std-ref">
            Availability
    : 
    Unix, not Emscripten, not WASI.
    <paragraph>
        Hello world I'm the content of the "availability" directive.
```

If it's really something that should not be done, maybe some kind of warning at build time could help debugging those issues?



---

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

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

[Docutils-develop] [docutils:feature-requests] #102 Image height/width attributes

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

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

The issue is fixed in Docutils 0.22 released 2025-07-29.
Thank you for reporting.




---

**[feature-requests:#102] Image height/width attributes**

**Status:** closed-fixed
**Group:** Default
**Created:** Wed Dec 20, 2023 02:35 PM UTC by toastal
**Last Updated:** Wed Sep 11, 2024 07:30 AM UTC
**Owner:** nobody


When setting `:width:` or `:height:` on an image, the output is a `<image style="width: $W; height: $H">`. This isn’t the expected out put as there are & have been `width` & `height` attributes for the `<img>` tag for a long time. One might assume this is the same affect, but there are some important problems & why I think this is a bug for incorrect implementation.

1. Tools like Lighthouse, et al. show users to have width/height as a optimization so the browser can calculate & the image size properly without having to do a layout shift which is great
2. A good CSP (Content Security Policy) should never include `unsafe-inline` as this can be an attack surface but the output of `:width:` & `:height:` do just this.

The way to solve this to keep out unneeded inline style practice for good CSP but still have the width/height is to just use `<img width="$W" height="$H">` (at least when units are not specified).

What I may not be accounting for: units. `12px` is not the same as `12rem` or `12ex` or `12vw`. However, what I had input in my image was just plain ol’ integers got back something I didn’t expect: a) something using `px` (I‘m exclusively using relative unit like `em`, `rem`, etc.) and b) not using the attributes since the number I gave had no units.


---

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

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

[Docutils-develop] [docutils:feature-requests] #105 manpage: would like more informative document comments

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

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

The issue is fixed in Docutils 0.22 released 2025-07-29.
Thank you for reporting.




---

**[feature-requests:#105] manpage: would like more informative document comments**

**Status:** closed-fixed
**Group:** Default
**Labels:** manpage writer 
**Created:** Wed Mar 27, 2024 01:07 AM UTC by G. Branden Robinson
**Last Updated:** Thu May 16, 2024 02:39 PM UTC
**Owner:** engelbert gruber


*man* documents generated by *rst2man*  have some indication that they were automatically generated but I would prefer to see more information along these lines.

Here's the status quo.
~~~
.\" Man page generated from reStructuredText.
.\" body of man page follows
.\" Generated by docutils manpage writer.
.
~~~

In my opinion, the comments should be coalesced at the top of the document and include tool versioning information.

More like this:

~~~
.\" Man page generated from reStructuredText by rst2man
.\" from docutils 0.21rc1.
~~~


---

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] #493 Test failure on Windows with embedded images

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

@aa-turner:  Can we close this bug? Is there still something to do after 0.22 is out?


---

**[bugs:#493] Test failure on Windows with embedded images**

**Status:** open-fixed
**Created:** Wed Aug 07, 2024 02:25 AM UTC by Adam  Turner
**Last Updated:** Mon Apr 14, 2025 01:10 PM UTC
**Owner:** nobody


xref [r9785], [r9853], [r9855]

Dear @milde,

Thank you for the fix to my recent patch. It seems neither my patch nor the fix addressed the root cause of the test failures, as tests have resumed failing on Windows.

I believe the following demonstrates the problem:

```pycon
>>> import sys; print(sys.platform)
win32
>>> import urllib.parse, urllib.request
>>> urllib.request.url2pathname('test/data/circle-broken.svg')
'test\\data\\circle-broken.svg'
>>> urllib.parse.unquote('test/data/circle-broken.svg')
'test/data/circle-broken.svg'
```

Currently, we use `imagepath = urllib.request.url2pathname(uri_parts.path)`, which converts path separators to their platform-native format. On UNIX, `url2pathname` simply calls `unquote`, but on Windows it handles UNC paths (``\\host\path\``) and escaped drive letters (``///C|/users/``).

I don't know what led to using `url2pathname()`, as it is quite specialised (the docstring notes "not recommended for general use"). Is it possible to use the simpler `unquote()` here?  

For local file paths (e.g. without a ``file:///`` scheme), should we even be using URI parsing? Perhaps we should use proper path handling if there is no URI scheme (i.e. the user has provided a file-path).

A


---

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] #346 reST parser warns twice for short underline

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

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

The issue is fixed in Docutils 0.22 released 2025-07-29.
Thank you for reporting.




---

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

**Status:** closed-fixed
**Created:** Sun Jul 29, 2018 11:37 AM UTC by Takeshi KOMIYA
**Last Updated:** Thu Apr 17, 2025 09:50 PM UTC
**Owner:** nobody


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

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

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

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

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

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

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


---

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

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

[Docutils-develop] [docutils:bugs] #481 manpage: please stop converting text to full capitals

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

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

The issue is fixed in Docutils 0.22 released 2025-07-29.
Thanks again for reporting.




---

**[bugs:#481] manpage: please stop converting text to full capitals**

**Status:** closed-fixed
**Labels:** manpage writer 
**Created:** Wed Mar 27, 2024 01:12 AM UTC by G. Branden Robinson
**Last Updated:** Sun May 19, 2024 04:18 PM UTC
**Owner:** engelbert gruber


*mandoc* maintainer Ingo Schwarze and I (*groff* lead developer) reached a consensus a few years ago that man pages should stop shouting.  This is a historical artifact of practices at Bell Labs in the 1970s.

It also can, reportedly, create accessibility problems, since a screen reader may pronounce words in FULL CAPS letter by letter instead of reading them as words.  (The KDE screen reader I tried with a PDF didn't do this.)

In _groff_ 1.23.0, this behavior is configurable, and the user can turn the full-caps conversion on at rendering time.  With _man-db_, these options can be passed in via the ``MANROFFOPT`` environment variable.

~~~
     -rCS=1   Set section headings (the argument(s) to .SH) in full
              capitals.  This transformation is off by default because
              it discards case distinction information.

     -rCT=1   Set the man page identifier (the first argument to .TH) in
              full capitals in headers and footers.  This transformation
              is off by default because it discards case distinction
              information.
~~~


---

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] #486 0.21.1: sdist is missing tox.ini

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

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

The bug is fixed in Docutils 0.22 released 2025-07-29.
Thank you for reporting.




---

**[bugs:#486] 0.21.1: sdist is missing tox.ini**

**Status:** closed-fixed
**Created:** Mon Apr 22, 2024 08:01 AM UTC by Marcel Telka
**Last Updated:** Fri May 03, 2024 11:47 AM UTC
**Owner:** nobody


The sdist package for version 0.21.1 is missing tox.ini.  Please add the missing tox.ini to sdist to make downstream testing easier.  Thank you.


---

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

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

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

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

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

The bug is fixed in Docutils 0.22 released 2025-07-29.



---

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

**Status:** closed-fixed
**Labels:** manpage writer 
**Created:** Sun May 12, 2024 03:55 PM UTC by engelbert gruber
**Last Updated:** Fri Apr 25, 2025 04:37 PM UTC
**Owner:** engelbert gruber


groff_man_style on hyperlinks

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


---

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

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

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

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

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

The bug is fixed in Docutils 0.22 released 2025-07-29.




---

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

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

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


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

footnote
--------

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

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

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

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

citation
--------

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

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

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

figure
------

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

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

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

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

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

Suggestion
----------

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

(Change in Docutils 1.0, announce in 0.22.)

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

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



---

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

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

[Docutils-develop] [docutils:bugs] #490 EncodingWarnings in io module

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

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

The bug is fixed in Docutils 0.22 released 2025-07-29.
Thanks agaoin for reporting.




---

**[bugs:#490] EncodingWarnings in io module**

**Status:** closed-fixed
**Created:** Fri Jun 28, 2024 03:34 PM UTC by Jason R. Coombs
**Last Updated:** Wed Aug 07, 2024 03:57 PM UTC
**Owner:** nobody


When running the [distutils](https://github.com/pypa/distutils) tests with `PYTHONWARNDEFAULTENCODING=1`, two warnings are emitted:

```
distutils/tests/test_check.py::TestCheck::test_check_restructuredtext
  /Users/jaraco/code/pypa/distutils/.tox/py/lib/python3.12/site-packages/docutils/io.py:381: EncodingWarning: 'encoding' argument not specified
    self.source = open(source_path, mode,

distutils/tests/test_check.py::TestCheck::test_check_restructuredtext
  /Users/jaraco/code/pypa/distutils/.tox/py/lib/python3.12/site-packages/docutils/io.py:151: EncodingWarning: UTF-8 Mode affects locale.getpreferredencoding(). Consider locale.getencoding() instead.
    fallback = locale.getpreferredencoding(do_setlocale=False)
```

Docutils should honor [PEP 597](https://peps.python.org/pep-0597/) and address these warnings (and possibly others). In my experience, adding `encoding='utf-8'` to any io operation is the best approach - it's straight-up compatible with the default on non-Windows systems and usually honoring the Unix convention is suitable if not preferable on Windows. Not only that, but that behavior will become the default in Python 3.15 or so.


---

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] #491 Don't hardcode interpreter in utils/smartquotes.py

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

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

The bug is fixed in Docutils 0.22 released 2025-07-29.
Thanks again for reporting.




---

**[bugs:#491] Don't hardcode interpreter in utils/smartquotes.py**

**Status:** closed-fixed
**Created:** Tue Jul 02, 2024 01:39 PM UTC by Ross Burton
**Last Updated:** Sat Jul 27, 2024 09:05 AM UTC
**Owner:** nobody


The interpreter is hardcoded in smartquotes.py:

https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/docutils/utils/smartquotes.py

Instead of using "/usr/bin/python3" directly, it's recommended to use "/usr/bin/env python3".


---

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] #494 rst2odt: TypeError with --stylesheet=styles.xml

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

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

The bug is fixed in Docutils 0.22 released 2025-07-29.
Thank you for reporting.



---

**[bugs:#494] rst2odt: TypeError with --stylesheet=styles.xml**

**Status:** closed-fixed
**Labels:** ODT Writer 
**Created:** Fri Oct 04, 2024 10:52 AM UTC by Paul Kishimoto
**Last Updated:** Fri Nov 29, 2024 08:29 AM UTC
**Owner:** nobody


The documentation (page “ODT Writer for Docutils”, section [“4 Styles and Classes”](https://docutils.sourceforge.io/docs/user/odt.html#styles-and-classes)) states:
> Note that with the `--stylesheet` command line option, you can use either `styles.odt` or `styles.xml`, as described below. Use of `styles.odt` is recommended over `styles.xml`.

With Python 3.12.3 and docutils 0.21.2, it appears that styles.xml is not usable, either from the command line or programmatically.

To reproduce from the command line:
1. A file `empty.rst`.
2. A file `styles.xml`, extracted from any valid ODT archive.
3. Run `$ docutils --writer=odt --stylesheet=styles.xml --traceback empty.rst >bug.odt`

The output is:
```
Traceback (most recent call last):
  File "/home/khaeru/.venv/3.12/bin/docutils", line 8, in <module>
    sys.exit(main())
             ^^^^^^
  File "/home/khaeru/.venv/3.12/lib/python3.12/site-packages/docutils/__main__.py", line 78, in main
    publish_cmdline(reader_name=args.reader,
  File "/home/khaeru/.venv/3.12/lib/python3.12/site-packages/docutils/core.py", line 402, in publish_cmdline
    output = publisher.publish(
             ^^^^^^^^^^^^^^^^^^
  File "/home/khaeru/.venv/3.12/lib/python3.12/site-packages/docutils/core.py", line 237, in publish
    output = self.writer.write(self.document, self.destination)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/khaeru/.venv/3.12/lib/python3.12/site-packages/docutils/writers/__init__.py", line 80, in write
    self.translate()
  File "/home/khaeru/.venv/3.12/lib/python3.12/site-packages/docutils/writers/odf_odt/__init__.py", line 510, in translate
    self.visitor.retrieve_styles(self.EXTENSION)
  File "/home/khaeru/.venv/3.12/lib/python3.12/site-packages/docutils/writers/odf_odt/__init__.py", line 941, in retrieve_styles
    self.dom_stylesheetcontent = etree.fromstring(
                                 ^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.12/xml/etree/ElementTree.py", line 1335, in XML
    parser.feed(text)
TypeError: a bytes-like object is required, not 'NoneType'
```

The same error occurs when calling:
```python
from docutils.core import publish_string

publish_string(
    source="",
    writer_name="odt",
    settings_overrides={"stylesheet": "styles.xml"},
)
```

This seems to be a consequence of `ODFTranslator.retrieve_styles()` ([here](https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/docutils/writers/odf_odt/__init__.py#l925)), wherein:

1. `s2 = None` is set.
2. If the provided path has extension `extension` (e.g. ".odt"), it is overwritten with content read from `content.xml` in the archive; **but** if the provided path has extension ".xml", it remains `None`.
3. This value is assigned to `self.str_stylesheetcontent` and then parsed with `etree.tostring()`.

Also, the parsed `self.dom_stylesheetcontent` does not appear to be used anywhere else in the module. It's not clear why it is needed.


---

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.