Subject: Re: bug#53977: Improve markup in man pages

From: Pádraig Brady <[email-masked]>
Date: Mon, 14 Feb 2022 12:15:27 +0000

On 13/02/2022 13:19, Mario Blättermann wrote:
> Hello,
> 
> the SEE ALSO sections in the man pages contain links which will be
> pulled in from *.x files by help2man. While help2man evaluates the
> Groff markup from --help and --version output, it doesn't bother with
> the markup in the *.x files. See the attached patch. The bold
> formatting of the links is especially useful in HTML output (but also
> in terminal output); the links become clickable and point to the
> respective man page in online collections [1]. You can test the
> behavior in the German version, where the links are already properly
> formatted [2].
> 
> [1] https://man.archlinux.org/man/cat.1
> [2] https://man.archlinux.org/man/cat.1.de

Sorry. I'm still not convinced on this.
It seems like a layering violation to stipulate a style here.
The renderer should have enough context to highlight appropriately.
See for example:

https://man7.org/linux/man-pages/man1/sort.1.html

Note the man7.org renderer only highlights the SEE ALSO references,
when ideally it would highlight all instances of this pattern.
Anyway handling references outside of the SEE ALSO section,
is another reason to have the renderer do this consistently.
See for example all the appropriately highlighted references in:

http://man.he.net/?topic=sort&section=all
https://man.cx/sort

thanks,
Pádraig