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

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

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

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


---

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

**Status:** open-fixed
**Labels:** manpage writer 
**Created:** Tue Feb 11, 2025 11:03 PM UTC by Ulya Trofimovich
**Last Updated:** Wed Apr 30, 2025 05:34 AM UTC
**Owner:** engelbert gruber


Hi! Here's an example bug.rst file (trimmed from a real-world manpage AUTHORS section and changed to hide real names):
~~~
$ cat bug.rst
Aaaaa ([email protected]),
`Bbb <https://github.com/cc>`_ ([email protected]),
`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 ( <[email protected]> ), Bbb <https://github.com/cc>
        ( <[email protected]> ), 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 ([email protected]), Bbb <https://github.com/cc> ([email protected]), 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 [email protected] 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.