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

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