docutils-develop — For developer discussions of the implementation.

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

[Docutils-develop] [docutils:feature-requests] #41 Not all Node instances have the source and line attributes set

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

Commit [r10078] adds source and line info to `<enumerated_list>` elements.


---

**[feature-requests:#41] Not all Node instances have the source and line attributes set**

**Status:** open
**Group:** sandbox
**Created:** Sun Jan 12, 2014 07:21 PM UTC by Brecht Machiels
**Last Updated:** Sun Oct 13, 2024 01:58 PM UTC
**Owner:** nobody


The source and line attributes of Node elements are not set for all types of elements. For example, these attributes never get set on bulleted or enumerated list nodes. Other elements (such as literal block) don't have source set depending on the context.


---

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:patches] #213 Change section handling to not rely on exceptions and reparsing

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

How about the attached version?

Keep `check_subsection()` and `new_subsection()` functions for backwards compatibility.
Restructure and simplify code.


Attachments:

- [section-handling2.patch](https://sourceforge.net/p/docutils/patches/_discuss/thread/766093b15b/cdc3/attachment/section-handling2.patch) (12.0 kB; text/x-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:** Sat Apr 05, 2025 10:05 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.

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

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

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

cheers

On Wed, 19 Feb 2025 at 19:09, Guenter Milde via Docutils-develop <
doc...@li...> wrote:

> Dear Docutils developers,
>
> with a long list a fixes, improvements, and additions since
> release 0.21.2 (2024-04-23), how about releasing 0.22?
>
> IMO, we should start with a beta release, to give downstream users an easy
> chance to test without breaking installations with `pip` auto-updates.
>
> @Engelbert: would you take care of the release again?
>
> @Adam: I remember you announced interest in collaborating. Is this still
>        valid?
>
> Best regards,
> Günter
>
>
>
>
> _______________________________________________
> Docutils-develop mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-develop
>
> Please use "Reply All" to reply to the list.
>

Re: [Docutils-develop] A small detail on the syntax of field list markers

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

On 2025-04-06, Karl O. Pinc wrote:

...

>>   * Escaped whitespace characters are removed from the output document
>>     together with the escaping backslash. This allows for
>>     character-level inline markup.

...

> FYI, a more universal example
> is adding links to footnotes at the end of a sentence,
> without an extra space between the period and the footnote
> number/link.

>   A footnoted sentence.\ [#f1]_

>   .. rubric:: Footnotes

>   .. [#f1] Text of the footnote.

Yes, this is another use case. Thank you for reminding.


Personally, I rely on the `trim_footnote_reference_space`__ configuration
setting. It's default depends on the `footnote_reference`__ style:

  The footnote space is trimmed if the reference style is "superscript",
  and it is left if the reference style is "brackets".

The advantage is that this way, there is no need to change the source when
switching the footnote reference style between "superscript" and "brackets".

Regards,
Günter

__ https://docutils.sourceforge.io/docs/user/config.html#trim-footnote-reference-space
__ https://docutils.sourceforge.io/docs/user/config.html#footnote-references

Re: [Docutils-develop] A small detail on the syntax of field list markers

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

On Sun, 6 Apr 2025 15:26:24 -0000 (UTC)
Guenter Milde via Docutils-develop
<doc...@li...> wrote:

> The rST escaping rules are a bit more complex:
> 
>   * “Escaping” backslash characters are represented by NULL
> characters in the Document Tree and removed from the output document
> by the Docutils writers.
> 
>   * Escaped non-white characters are prevented from playing a role in
> any markup interpretation. The escaped character represents the
> character itself. (A literal backslash can be specified by two
> backslashes in a row – the first backslash escapes the second.)
>   
>   * Escaped whitespace characters are removed from the output document
>     together with the escaping backslash. This allows for
> character-level inline markup.
>   
>     In "URI context", backslash-escaped whitespace represents a
> single space.
> 
>   ---
> https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#escaping-mechanism 
> The third rule provides for character level inline markup, e.g.,
> "re\ *Structured*\ text" or hyper\ `links`_ to a part of a word.
> 
> .. _links: example.org/word
> 
> The escape-character and space are removed by the writer, i.e. the
> space char is present and interpreted as space char when parsing.

FYI, a more universal example
is adding links to footnotes at the end of a sentence,
without an extra space between the period and the footnote
number/link.

  A footnoted sentence.\ [#f1]_

  .. rubric:: Footnotes

  .. [#f1] Text of the footnote.

Then you get: A footnoted sentence.1

Where the "1" is superscripted and hyperlinked.

(If you're looking for an example to include in
the docs.)

Regards,

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

Re: [Docutils-develop] A small detail on the syntax of field list markers

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

On 2025-04-06, Guenter Milde via Docutils-develop wrote:

> On the downside, there is no way to specify a field name with trailing
> whitespace.

I found a way to circumvent this restriction: Inside field names, inline
syntax is recognized, so you can use a substitution::

  .. |space| unicode:: 32
     :trim:

  :strange field name |space|: and field

Günter

Re: [Docutils-develop] A small detail on the syntax of field list markers

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

Dear Arne,

thanks for your feedback.

On 2025-04-05, Arne Skjærholt wrote:
> While spelunking in the code, I came across the following regex
> (docutils.parsers.rst.states.Body.patterns["field_marker"]) defining
> the syntax of field list names and their surrounding colons:

>     :(?![: ])([^:\\]|\\.|:(?!([ `]|$)))*(?<! ):( +|$)

> I wonder if the final lookbehind assertion might not be slightly
> incorrect? The field name is not allowed to end with a space, which is
> fine, but given the allowance for backslash escapes one would normally
> expect ":foo\ :" to be a permitted (if odd) marker. 

The rST escaping rules are a bit more complex:

  * “Escaping” backslash characters are represented by NULL characters in
    the Document Tree and removed from the output document by the
    Docutils writers.

  * Escaped non-white characters are prevented from playing a role in any
    markup interpretation. The escaped character represents the character
    itself. (A literal backslash can be specified by two backslashes in a
    row – the first backslash escapes the second.)
  
  * Escaped whitespace characters are removed from the output document
    together with the escaping backslash. This allows for character-level
    inline markup.
  
    In "URI context", backslash-escaped whitespace represents a single space.

  --- https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#escaping-mechanism
  
The third rule provides for character level inline markup, e.g.,
"re\ *Structured*\ text" or hyper\ `links`_ to a part of a word.

.. _links: example.org/word

The escape-character and space are removed by the writer, i.e. the space
char is present and interpreted as space char when parsing.

On the downside, there is no way to specify a field name with trailing
whitespace. (The same holds for inline markup: you cannot specify an
emphasised text with trailing whitespace either::

   *this\ * results in a warning,
   
whild both, ``this\*`` and ``this\ *`` results in ``this*``.)


> However, given that (?<! ) unconditionally looks for a single space
> before the terminating colon it is in fact rejected, and backslashes
> have a somewhat puzzling behaviour in field names.

> I couldn't find any indications in docs or tests either way for what
> is intended, but amending the assertion to be (?<![^\\] ) would yield
> a more intuitive syntax I think.

I agree, that the special case for ``\ `` may come as a surprise
(especially with the further special handling of ``\ `` in URIs).
However, changing this would break long existing documented behaviour.

Are there more "surprises" with backslashes in field names that differ
from backslash handling in inline markup or normal text?


As a side note: the following example works ::

  What is `this\ `_?

  .. _this: http://example.org

while I would expect the same warnings as for the variant without backslash:

  What is `this `_?

  .. _this: http://example.org



Günter

[Docutils-develop] A small detail on the syntax of field list markers

[Arne S. <arn...@gm...>]

While spelunking in the code, I came across the following regex
(docutils.parsers.rst.states.Body.patterns["field_marker"]) defining
the syntax of field list names and their surrounding colons:

    :(?![: ])([^:\\]|\\.|:(?!([ `]|$)))*(?<! ):( +|$)

I wonder if the final lookbehind assertion might not be slightly
incorrect? The field name is not allowed to end with a space, which is
fine, but given the allowance for backslash escapes one would normally
expect ":foo\ :" to be a permitted (if odd) marker. However, given
that (?<! ) unconditionally looks for a single space before the
terminating colon it is in fact rejected, and backslashes have a
somewhat puzzling behaviour in field names.

I couldn't find any indications in docs or tests either way for what
is intended, but amending the assertion to be (?<![^\\] ) would yield
a more intuitive syntax I think.

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

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

Thank you for reporting.
This is due to the current setup of the rST parser regarding section level handling.
The issue is solved by  a recent patch by Arne Skjærholt [patches:#213] (which still needs to be tested for side-effects).


---

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

**Status:** open
**Created:** Sun Jul 29, 2018 11:37 AM UTC by Takeshi KOMIYA
**Last Updated:** Tue Mar 03, 2020 09:41 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:patches] #213 Change section handling to not rely on exceptions and reparsing

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

The patch also solves [bugs:#346] "reST parser warns twice for short underline".


---

**[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:** Mon Mar 31, 2025 06:58 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] #213 Change section handling to not rely on exceptions and reparsing

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

Thank you for the patch. On a first inspection it looks like a genuine improvement. 

The changes to the test suite seem to be improvements/fixes, too.
Line numbers in test/functional/expected/standalone_rst_pseudoxml.txt are still incorrect (but nearer to the correct value). This needs to be looked at separately (the `<enumerated_list>` element is missing source/line internal attributes, too).

We will have to look into your use-case to see whether there is still something missing in the patch or whether the problem can/must be fixed in your custom directive.


---

**[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:** Mon Mar 31, 2025 01:39 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] test failure in test_writers/test_manpage.py

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

Dear Engelbert,

it seems the latest commit(s) introduced a problem with the manpage writer
test:


    FAIL: test_reference_macros (test_writers.test_manpage.WriterPublishTestCase.test_reference_macros) (id="totest_refs['ext hyperlink'][0]")
    ----------------------------------------------------------------------
    Traceback (most recent call last):
      File "/usr/local/src/docutils-git-svn/docutils/test/test_writers/test_manpage.py", line 72, in test_reference_macros
        self.assertEqual(case_expected, output)
    AssertionError: '.\\"[850 chars]ike \n.UR https://www.python.org/\nPython\n.UE[37 chars]e.\n' != '.\\"[850 chars]ike \\c\n.UR https://www.python.org/\nPython\n[40 chars]e.\n'
      .\" Man page generated from reStructuredText by manpage writer
      .\" from docutils 0.22b.dev.
      . 

[...]

      .TH "" "" "" ""
      .SH Name
       \- 
    - embedded External hyperlinks, like 
    + embedded External hyperlinks, like \c
    ?                                    ++
      .UR https://www.python.org/
      Python
      .UE
      \&.
      .\" End of generated man page.
    
    
    ----------------------------------------------------------------------
    Ran 2389 tests in 4.538s
    
    FAILED (failures=2, skipped=5)

Could you have a look?

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

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

macros have additional problems especially with spaces

attached the result without macros. so no OSC8 clicking info, but therefore visible references ... the macro version has non-clickable and invisible references in my kde terminal in default settings, which is the reason for having text-references by default.


Attachments:

- [authors.man](https://sourceforge.net/p/docutils/bugs/_discuss/thread/48dad27f08/9f79/09c4/2fe9/attachment/authors.man) (1.5 kB; application/x-troff-man)


---

**[bugs:#497] manpage writer renders links incorrectly**

**Status:** open
**Labels:** manpage writer 
**Created:** Tue Feb 11, 2025 11:03 PM UTC by Ulya Trofimovich
**Last Updated:** Thu Mar 20, 2025 10:49 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...>]

I try to sum up

Note: references in manpages are new ... to the manpage writer

two options

1. use man macros .UR/.UE .MT/.ME
2. render in the writer

references are uris and a label/content 
in html `<a href="the-reference">the-content</a>`

macros changed because terminals changed
macros put out OSC8 sequences so that terminal offer a clickable text (the-content)
Problem 1: not all terminals do this,
 some might simply skip the OSC8 thing, which means the reference is lost
 some might output the OSC8 which means it is ugly
 
mandoc (the manpage system of bsd) does not output OSC8 but renders the referencein angle brackets. most x-terms recognize references anyway and make them clickable. 

the option text-references tries to act like mandoc and making the transition stepwise

if content is missing, in your example the unmarked mailadresses this means
a) one gets a clickable nothing or 
b) rendered in text a duplication like `aa...@bb... <aa...@bb...> `

mulling it over again and again IMHO
macro-references is the preferred way.

is this understandably (i get a let off blank views all the time, so simply tell)
any objections ?


---

**[bugs:#497] manpage writer renders links incorrectly**

**Status:** open
**Labels:** manpage writer 
**Created:** Tue Feb 11, 2025 11:03 PM UTC by Ulya Trofimovich
**Last Updated:** Thu Mar 20, 2025 01:03 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...>]

your delay is no problem for me ... mine is


---

**[bugs:#497] manpage writer renders links incorrectly**

**Status:** open
**Labels:** manpage writer 
**Created:** Tue Feb 11, 2025 11:03 PM UTC by Ulya Trofimovich
**Last Updated:** Wed Mar 19, 2025 05:21 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 ?

[Adam T. <aat...@ou...>]

Dear Günter, Engelbert, all,

[Engelbert]
> adam should get a invitaionfrom pypi.

Thank you! I have accepted the invitation. Please could you also add me to the Docutils project on Test PyPI? [1]

[Engelbert]
> maybe we might put out more betas, for users to try before a release, if they are not developers this might help.

I agree.

[Günter]
> Feel free to commit small, non-controversial changes right away
> (bit for bit, so that I can have a look) and discuss the complex and
> ambiguous ones either on this list, in private mail or the project tickets.

I have made a series of commits starting at [r10019] through to [r10048]. The most notable is [r10043], which removes type annotations for ``docutils.nodes.Node``, as I would like more time to research what the ideal type annotations are, and talk to some static typing experts. Other than that, the commits are mainly small clean-ups, test fixes, etc.

[Günter]
> What would be your proposed timeframe? (I will be offline next week.)

I think we could publish a beta/release candidate at any point, but I have no strong views. I'm also not in any hurry to do so.

[Günter]
> We should try to solve the deprecation warnings. There should be a
> documented way forward, if not, report back and well find a solution
> (as a last restort, we'll turn them into pending deprecation warnings).

You can inspect the deprecation warnings on GitHub [2] (expand the "test with pytest" tab). These are::

    DeprecationWarning: Argument "parser_name" will be removed in Docutils 2.0.
      Specify parser name in the "parser" argument.
      reader: Reader[DocTreeInput] = docutils.readers.doctree.Reader(

    DeprecationWarning: The auxiliary function roles.set_classes() is obsoleted by roles.normalize_options() and will be removed in Docutils 1.0
      set_classes(self.options)

The ``set_classes()`` function is somewhat frequently used [3] and the replacement is very new. Perhaps we should delay the deprecation and use a PendingDeprecationWarning? Likewise with the 'parser_name' argument, support for strings in 'parser' is not yet released, and removal is planned for 2.0, so perhaps we should start with a PendingDeprecationWarning?

[Günter]
> Could you also test building a typical Sphinx doctree with the new
> "validate__" parser setting set to True?
> There may be problems with the custom nodes added by Sphinx.
> (The setting was added due to a feature-request by a Sphinx-extension
> developer.)
>
> __ https://docutils.sourceforge.io/docs/user/config.html#validate

I haven't had time to do so yet, but I will try at some point.

Thanks,
Adam

[1] https://test.pypi.org/project/docutils/
[2] https://github.com/sphinx-doc/sphinx/actions/runs/13728707556/job/38401038459
[3] https://github.com/search?q=%2Fdocutils%5C..*set_classes%2F+language%3APython+NOT+is%3Aarchived++NOT+is%3Afork&type=code

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

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

Dear Adam, Engelbert, docutils developers,

back from the winter holidays...

On 2025-02-22, Adam Turner wrote:

>> how about releasing 0.22?

> Sounds good! I want to review the situation around type annotations
> before releasing, and I might revert some of the changes I have made.
> There are also a few updates to the packaging metadata we can take the
> opportunity to make before releasing.

Fine. Feel free to commit small, non-controversial changes right away
(bit for bit, so that I can have a look) and discuss the complex and
ambiguous ones either on this list, in private mail or the project tickets.
What would be your proposed timeframe? (I will be offline next week.)

>> IMO, we should start with a beta release, to give downstream users an easy
>> chance to test without breaking installations with `pip` auto-updates.

> Sphinx 8.2. (released last week) is fully compatible with Docutils
> master (although there are some deprecation warnings). 

We should try to solve the deprecation warnings. There should be a
documented way forward, if not, report back and well find a solution 
(as a last restort, we'll turn them into pending deprecation warnings).

Could you also test building a typical Sphinx doctree with the new
"validate__" parser setting set to True?
There may be problems with the custom nodes added by Sphinx.
(The setting was added due to a feature-request by a Sphinx-extension
developer.)

__ https://docutils.sourceforge.io/docs/user/config.html#validate

> I think we can request that other projects test a release candidate, as
> with previous releases.

I have no strong preference whether we call the next release 0.22rc1 or
0.22b1. (It depends on the probability of pending non-trivial changes.)

> I am happy to help with the release (perhaps publishing a release
> candidate), I think it might be useful to have more people who can do
> releases, to share the work and remove pressure on individuals. If this
> would be helpful, please could I be added to the Docutils PyPI project
> [1]_? My username on PyPI is ``AA-Turner`` [2]_.

Could you co-ordinate this with Engelbert, please?

> I can probably also co-ordinate with the downstream projects, should
> this be useful.

Thanks for the offer. For projects where the contact is via github, this
may be helpfull.

sincerely,

Günter

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

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

not yet released you are correct

i did the processing with option --macro-references 
and get the attached file

the problem i have, aside from blanks and new lines, with this is

viewed with man uris are not shown and might be clickable on some systems
lost on others, like mine
that is why i did the rendering in the manpage-writer and set it as default.

on it, cheers


Attachments:

- [authors-urue.man](https://sourceforge.net/p/docutils/bugs/_discuss/thread/48dad27f08/9b01/dc49/attachment/authors-urue.man) (1.7 kB; application/x-troff-man)


---

**[bugs:#497] manpage writer renders links incorrectly**

**Status:** open
**Labels:** manpage writer 
**Created:** Tue Feb 11, 2025 11:03 PM UTC by Ulya Trofimovich
**Last Updated:** Mon Feb 24, 2025 10:40 AM UTC
**Owner:** engelbert gruber


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

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

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

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


---

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

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

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

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

hei

adam should get a invitaionfrom pypi. you are only maintainer ... for now,
i did set felix back to maintainer, as i his off for a long time

maybe we might put out more betas, for users to try before a release, if
they are not developers this might help.

welcome


On Sat, 22 Feb 2025 at 20:01, Adam Turner <aat...@ou...>
wrote:

> Dear Günter, all,
>
> >  with a long list a fixes, improvements, and additions since
> release 0.21.2 (2024-04-23), how about releasing 0.22?
>
> Sounds good! I want to review the situation around type annotations before
> releasing, and I might revert some of the changes I have made. There are
> also a few updates to the packaging metadata we can take the opportunity to
> make before releasing.
>
> > IMO, we should start with a beta release, to give downstream users an
> easy
> > chance to test without breaking installations with `pip` auto-updates.
>
> Sphinx 8.2. (released last week) is fully compatible with Docutils master
> (although there are some deprecation warnings). I think we can request that
> other projects test a release candidate, as with previous releases.
>
> I am happy to help with the release (perhaps publishing a release
> candidate), I think it might be useful to have more people who can do
> releases, to share the work and remove pressure on individuals. If this
> would be helpful, please could I be added to the Docutils PyPI project
> [1]_? My username on PyPI is ``AA-Turner`` [2]_.
>
> .. [1]: https://pypi.org/project/docutils/
> .. [2]: https://pypi.org/user/AA-Turner/
>
> I can probably also co-ordinate with the downstream projects, should this
> be useful.
>
> Best wishes,
> Adam
>
>
> _______________________________________________
> Docutils-develop mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-develop
>
> Please use "Reply All" to reply to the list.
>