docutils-develop — For developer discussions of the implementation.

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

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

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



---

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

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

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


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

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

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

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




---

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

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

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

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

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

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

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

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

Regards,

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

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

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

- Description has changed:

Diff:

~~~~

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

~~~~

- **Comment**:

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



---

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

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


latex2e: Propagate figure align to image

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

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



---

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

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

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

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

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

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



---

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

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


latex2e: Propagate figure align to image

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

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



---

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

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

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

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

---

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

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


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

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

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



---

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

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

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

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

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

Some alternatives come to mind:

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

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

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


---

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

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


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


---

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

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

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

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

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

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



---

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

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


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


---

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

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

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

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

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

Diff:

~~~~

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

~~~~

- **Comment**:

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

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

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

To solve this discrepancy, there are two alternatives:

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

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






---

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

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

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


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

footnote
--------

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

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

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

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

citation
--------

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

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

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

figure
------

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

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

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

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

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

Suggestion
----------

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

(Change in Docutils 1.0, announce in 0.22.)

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

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



---

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

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

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

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

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


---

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

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


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


---

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

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

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

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

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

Committed in [r10101].



---

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

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

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


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

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


---

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

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

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

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

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

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



---

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

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


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

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

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

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

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

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

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


---

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

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

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

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

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


---

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

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

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


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

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

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

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




---

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

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

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

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

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


---

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

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

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


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

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

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

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




---

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

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

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

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

- **Comment**:

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



---

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

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

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


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

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

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


---

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

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

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

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

1. `\:` to give breaking points.
2. prefix reference with `\%` to disallow hyphenation
3. think about the hyphen-minus 


---

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

**Status:** open
**Labels:** manpage writer 
**Created:** Sun May 12, 2024 03:55 PM UTC by engelbert gruber
**Last Updated:** Sun May 12, 2024 03:55 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] Re: #497 manpage writer renders links incorrectly

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

thanks Branden

portability is my main concern, `man xyz` should give the manual for xyz on any system.

therefore the text-references and macro-reference option, so people are able to choose.

again thanks for your help


---

**[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:** Fri Apr 11, 2025 10:07 PM 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] #493 Test failure on Windows with embedded images

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

- **status**: pending-works-for-me --> open-fixed



---

**[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:** Wed Dec 04, 2024 03:48 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:feature-requests] #112 The the include directive does not allow configuring a parser

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

- **status**: open --> pending-works-for-me
- **Group**:  --> Default
- **Comment**:

I don't fully understand the request of the upstream bug report, however it seems to regard documents parsed by the 3rd party parser MyST which is one of the available "markdown" parsers. The directives described in  https://docutils.sourceforge.io/docs/ref/rst/directives.html are specific to Docutil's reStructuredText parser.

The [reStructuredText "include" directive](https://docutils.sourceforge.io/docs/ref/rst/directives.html#include) provides the option "parser" to select a parser module for the to-be-included file. This is intended to enable the inclusion of files in different markup languages (reStructuredText, markdown, XML).  3rd-party parsers can provide configuration settings that enable document-wide configuration via the the [Docutils Configuration](https://docutils.sourceforge.io/docs/user/config.html) system.
Configuring the parser modules on a per-inclusion level is not possible (an application may subclass and configure a parser in an importable Python module).
When using docutils programmatically to convert a file or string, the parser class can be passed as pre-configured Python object (see [The Docutils Publisher](https://docutils.sourceforge.io/docs/api/publisher.html).

The MyST parser also provides an "include" directive. However, according to its documentation, without the "parser" option. https://mystmd.org/guide/directives#directive-include



---

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

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


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

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


---

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

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

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

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

Ticket moved from /p/docutils/bugs/498/


---

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

**Status:** open
**Group:** None
**Created:** Sat Apr 05, 2025 03:14 PM UTC by Gabriel P
**Last Updated:** Mon Apr 14, 2025 09:21 AM UTC
**Owner:** nobody


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

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


---

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

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

[Docutils-develop] [docutils:bugs] #499 latex2e: field list absent from body when on start of input string

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

- **labels**: latex2e writer, field list --> latex2e writer
- **status**: open --> closed-invalid
- **Comment**:

Thank you for reporting.

The reason for the behaviour is, that [a field list at the start of a document is  transformed into a docinfo list](https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#bibliographic-fields). (It is returned as "docinfo" part also by the HTML writers.)

You can configure this behaviour with the [docinfo-xform](https://docutils.sourceforge.io/docs/user/config.html#docinfo-xform) setting. In the minimal example, add a line

    "docinfo_xform": False,

to the `overrides` dictionary in `latex_parts()`.



---

**[bugs:#499] latex2e: field list absent from body when on start of input string**

**Status:** closed-invalid
**Labels:** latex2e writer 
**Created:** Sun Apr 06, 2025 06:43 PM UTC by PJBrs
**Last Updated:** Sun Apr 06, 2025 06:43 PM UTC
**Owner:** nobody
**Attachments:**

- [latex_lists_test.py](https://sourceforge.net/p/docutils/bugs/499/attachment/latex_lists_test.py) (2.3 kB; text/x-python)


When I try to translate an RST string that begins with a field list to latex, the string is absent from the "body" part of what the writer returns.  Instead, it becomes part of "docinfo".

If I add some information before the field list, it is correctly added  to the "body" part of what core.publish_parts returns. 

I don't know docutils very well, so I've attached an MWE.

~~~
$ docutils -V
docutils (Docutils 0.21.2, Python 3.9.21, on linux)
~~~


---

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

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

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

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

Hi Engelbert,

I know you've sent me a couple of messages on this topic; I apologize for not getting back to you sooner.

> --macro-references Use man macros .UR/.UE and .MT/.ME for references

That should be the preferred approach everywhere possible.  The good news is that _groff_'s macros are written to degrade gracefully to plan text renderings of hyperlinked text if OSC 8 support is disabled at rendering time.  The bad news is that _grotty_, _groff_'s output driver for terminals, cannot determine whether OSC 8 support exists at runtime, because (1) it's not a _termcap_/_terminfo_ application, and (2) no standard terminal capability exists indicating OSC 8 support even if it were.  Nevertheless [a future version of _groff_ hopes to implement _terminfo_ support in _grotty_, and to use an _ncurses_ extension to sense OSC 8 support](https://savannah.gnu.org/bugs/index.php?63583). 

> --text-references Put references in plain text form.

An application using Python _docutils_ to generate its man pages might prefer this option if the deployment system is known to **not** support the aforementioned macros.

_groff_man_(7):
>      MT, ME, UR, and UE are GNU extensions supported by Heirloom
>     Doctools and mandoc (UR/UE since 1.12.3; MT/ME since 1.14.2) but
>     not by Documenter’s Workbench, Plan 9, or Solaris troffs.  Plan 9
>     from User Space’s troff implements MR.

An advantage to using MT/ME and UR/UE, as noted above, is that OSC 8 they can be dynamically deconfigured at rendering time.  The _man_ librarian program can simply call _nroff_ (or _groff_ directly) with the option `-rU0`.

_groff_man_(7):
>     -rU0     Disable generation of URI hyperlinks in output drivers
>              capable of them, making the arguments to MT and UR calls
>              visible as formatted text.  grohtml(1), gropdf(1), and
>              grotty(1) enable hyperlinks by default (the last only if
>              not in legacy output mode).

For example, user's of Colin Watson's _man-db_ implementation of _man_(1) can set the environment variable `MANROFFOPT` to `-rU0`.

> macro references might turn into clickable references in the console
> but the reference is invisible until you hover
> if your terminal does not support OSC8 the reference is lost.
> if the OSC8 support is disabled also.

Another thing the man librarian (or a wrapper program) might do is check `$TERM` and pass `-rU0` unless the terminal type matches a one known to support OSC 8 well.   For example, `xterm` and `xterm-256color` do not because their maintainer Thomas Dickey hasn't yet seen a proposal for support that he likes.  (I'm trying.  :) )

 > text references activates references rendering in the writer.
> terminals might recognize emails and URLs anyway and make them clickable
> without OSC8

Yes; unfortunately they tend to use simple regexes for matching so they often detect false positives or fail to correctly hyperlink link text that breaks across lines (or pages when "continuous rendering" is disabled with `-rcR=0`).

> long references might be hyphenated/broken at inconvenient places
this can/should be influenced by the writer ... needs some testing on my
side.

Long URLs are indeed a headache (which is why it's nice when OSC 8 enables us to not format them).  _groff_'s own man pages, like _roff_(7) provide many examples.

Here's one.

~~~
A sample of control words from a
.UR http://\:web\:.mit\:.edu/\:Saltzer/\:www/\:publications/\:ctss/\:AH\
\:.9\:.01\:.html
.I RUNOFF
manual of December 1966
.UE
was documented as follows
(with the parameter notation slightly altered).
~~~

Unfortunately, breaking a word without a hyphen is an application that did not occur to the original developers of _roff_, _nroff_, and _troff_ in the 1970s.  The `\:` escape sequence is a _groff_ extension.

_groff_man_style_(7):
> Portability
>     \:        Insert a non‐printing break point.  A word can break at
>               such a point, but a hyphen glyph is not written to the
>               output if it does.  The remainder of the word is subject
>               to hyphenation as normal.  You can use \: and \% in
>               combination to control breaking of a file name or URI or
>               to permit hyphenation only after certain explicit hyphens
>               within a word.  See subsection “Hyperlink macros” above
>               for an example.
>
>               \: is a GNU extension also supported by Heirloom Doctools
>               troff 050915 (September 2005), mandoc 1.13.1
>               (2014‐08‐10), and neatroff (commit 399a4936, 2014‐02‐17),
>               but not by Plan 9, Solaris, or Documenter’s Workbench
>               troffs.

I hope this helps.  I admit that the issues are complicated, but that is mostly due to portability concerns.  For projects targeting GNU/Linux systems, there's not much to worry about.






---

**[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:** Thu Apr 10, 2025 03:26 PM UTC
**Owner:** engelbert gruber


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

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

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

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


---

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

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

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

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

hei

it will be in the next release.
there will be a pre release ... we are at it, but not yet there.

if you want to test before.

there are two options

--macro-references      Use man macros .UR/.UE and .MT/.ME for references
--text-references       Put references in plain text form.

macro references might turn into clickable references in the console
but the reference is invisible until you hover
if your terminal does not support OSC8 the reference is lost.
if the OSC8 support is disabled also.

text references activates references rendering in the writer.
terminals might recognize emails and URLs anyway and make them clickable
without OSC8
links should look similar to mandoc rendering.

TOD/INWORK
long references might be hyphenated/broken at inconvenient places
this can/should be influenced by the writer ... needs some testing on my
side.

cheers


On Thu, 10 Apr 2025 at 17:26, Ulya Trofimovich <
skv...@us...> wrote:

> @grubert <https://sourceforge.net/u/grubert/profile/> Thanks for the fix.
> Will it be in the next release? And what options, if any, do I need to pass
> to rst2man to get the behavior as in
> https://sourceforge.net/p/docutils/bugs/discuss/thread/48dad27f08/9f79/09c4/2fe9/attachment/authors.man
> above?
> ------------------------------
>
> *[bugs:#497] <https://sourceforge.net/p/docutils/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:* Thu Apr 10, 2025 11:43 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)</oooooooo></nn>
>    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 you indicated interest in
> https://sourceforge.net/p/docutils/bugs/497/
>
> To unsubscribe from further messages, please visit
> https://sourceforge.net/auth/subscriptions/
>



---

**[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:** Thu Apr 10, 2025 03:26 PM 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...>]

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



---

**[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:** Sun Mar 23, 2025 10:43 PM 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.

Re: [Docutils-develop] time to release 0.22.b1 ?

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

Dear Docutils developers,

On 2025-04-08, engelbert gruber wrote:

> any objections for a beta release in the next week or so ?

I postponed the deprecations/removals that led to DeprecationErrors
downstream as suggested by Adam.

Before releasing, I would like to include 2 patches:

* Set up enhancement proposals in developer documentation.
  https://sourceforge.net/p/docutils/feature-requests/111/
  
  The idea is to expose the proposals to a wider public and catch
  feedback, so that after 0.22 (and possible fixups) we can prepare
  release 1.0 with a complete API definition and backup compatibility
  policy.
  
* Change section handling to not rely on exceptions and reparsing
  https://sourceforge.net/p/docutils/patches/213/

  This patch solves system-message duplicates
  (https://sourceforge.net/p/docutils/bugs/346/), 
  simplifies the rST parser code, and speeds up parsing (a little bit).
  It should be tested for backwards compatibility issues with Sphinx etc.,
  though.


Best regards,
Günter

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

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

An updated patch.


Attachments:

- [0001-Set-up-enhancement-proposals-in-developer-documentat.patch](https://sourceforge.net/p/docutils/feature-requests/_discuss/thread/7144ba7ba2/bccf/attachment/0001-Set-up-enhancement-proposals-in-developer-documentat.patch) (27.4 kB; text/x-patch)


---

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

**Status:** open
**Group:** Default
**Created:** Thu Feb 13, 2025 10:05 PM UTC by Günter Milde
**Last Updated:** Fri Feb 14, 2025 12:52 AM 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.