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

SourceForge Headquarters 1320 Columbia Street Suite 310 San Diego, CA 92101 +1 (858) 422-6466

This generated output looks really good to me.  I formatted the files as follows.

~~~
nroff -rCHECKSTYLE=4 -man ./authors.man
nroff -rCHECKSTYLE=4 -man ./authors-urue.man
nroff -rCHECKSTYLE=4 -rU0 -man ./authors-urue.man
nroff -rCHECKSTYLE=4 -man ./ref-2025.man
nroff -rCHECKSTYLE=4 -man ./ref-2025-urue.man
nroff -rCHECKSTYLE=4 -man -rU0 ./ref-2025-urue.man
~~~

I got a few warnings from the style checker, but they are solely due to the degenerate input affecting parts of the document that have nothing to do with formatting links, and which are unlikely to occur in practical, real-world _docutils_ input.

~~~
$ nroff -z -rCHECKSTYLE=4 -man ./authors.man 
an.tmac:./authors.man:31: style: .TH missing third argument; consider document modification date in ISO 8601 format (YYYY-MM-DD)
an.tmac:./authors.man:31: style: .TH missing fourth argument; consider package/project name and version (e.g., "groff 1.23.0")
an.tmac:./authors.man:31: style: .TH missing fifth argument and second argument '' not a recognized manual section; specify its title
an.tmac:./authors.man:33: style: 1 leading space(s) on input line
~~~

None of these alarm me or affect the correctness of your generated output with respect to the formatting of hyperlinks.

I checked output in two terminal emulators.

~~~
$ gnome-terminal --version
# GNOME Terminal 3.38.3 using VTE 0.66.1 +BIDI +GNUTLS +ICU +SYSTEMD
$ xterm -version
XTerm(395)
~~~

...and everything looks good to me.  _xterm_ of course does not honor OSC 8.  _gnome-terminal_ does, and the highlighting of the OSC 8-bracketed sequences are where I expect them to be, and the pop-up tooltips over them show correctly-formed URLs.

Even better, when I specify the additional `nroff` option `-T ascii`, your "text references" feature's output so closely resembles what _groff man_ does when OSC 8 support is disabled (`-r U0`) that neither my eyeballs nor _diff_ can detect a difference!  (There is a difference when using _groff_'s `utf8` device because the U+2010 hyphen and U+27E8 and U+27E9 angle brackets are available. )

This feature looks ready to ship to me!  Please advise if I can be of any further assistance.

---

**[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:** Sat Apr 26, 2025 05:29 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...),
`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...> ), 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...), 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.