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

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 `[email protected] <[email protected]> `

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