GNU bug report logs - #53977
Improve markup in man pages

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 53977 in the body.
You can then email your comments to 53977 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Mario Blättermann <mario.blaettermann <at> gmail.com>
To: bug-coreutils <at> gnu.org
Subject: Improve markup in man pages
Date: Sun, 13 Feb 2022 14:19:32 +0100

[Message part 1 (text/plain, inline)]

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

Best Regards,
Mario

[seealso-markup.diff (text/x-patch, attachment)]

Message #8 received at 53977 <at> debbugs.gnu.org (full text, mbox):

From: Pádraig Brady <P <at> draigBrady.com>
To: Mario Blättermann <mario.blaettermann <at> gmail.com>,
 53977 <at> debbugs.gnu.org
Cc: man-pages <at> man7.org
Subject: Re: bug#53977: Improve markup in man pages
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

Message #11 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Mario Blättermann <mario.blaettermann <at> gmail.com>
To: bug-coreutils <at> gnu.org
Cc: 53977 <at> debbugs.gnu.org, man-pages <at> man7.org
Subject: Re: bug#53977: Improve markup in man pages
Date: Mon, 14 Feb 2022 14:52:08 +0100

Hello Pádraig,

Am Mo., 14. Feb. 2022 um 13:15 Uhr schrieb Pádraig Brady <P <at> draigbrady.com>:
>
> 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
>

Maybe some renderers are smart enough to highlight this. But it
shouldn't be up to the developers of such renderers to apply missing
formattings virtually.

> 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
>
Yes, but this doesn't work in all imaginable cases, because the
renderer needs to be able to evaluate if it is a link or not. In your
example, "shuf" is a link because it is tagged with the section
number, but this wouldn't, then "shuf" would be as plain as other
words. See the "diff3.1" man page [1]:

-e, --ed
output ed script incorporating changes from OLDFILE to YOURFILE into MYFILE

If "ed" would be "ed(1)" then it would be detected as a command name
here, but it isn't. Well, the best solution would be to dig in the
Help2man code and try to improve the detection of parts worth to be
formatted - provided solid Perl skills. But this would be outside of
the topic of this bug report; let's go back to the SEE ALSO links. The
man page man-pages(7) says [2]:

»The name of the command, and its options, should always be formatted in bold.«

In fact, the SEE ALSO links are also command names, although not the
command the current man page describes. Let's have a look at other
projects. The GRUB developers also use Help2man to generate man pages
dynamically, and they use *.h2m files to feed Help2man, like
Coreutils' *.x files do. An example [3]:

[NAME]
grub-editenv \- edit GRUB environment block
[SEE ALSO]
.BR grub-reboot (8),
.BR grub-set-default (8)

It seems to be obvious for them to format the links bold. But it is
not special to Help2man-based projects to do so. Example from GNU Grep
[4], which uses a static man page:

.SH "SEE ALSO"
.SS "Regular Manual Pages"
.BR awk (1),
.BR cmp (1),
.BR diff (1),
.BR find (1),
.BR perl (1),
...

Another example from the kernel's man pages [5]:

.SH SEE ALSO
.BR memusage (1),
.BR mtrace (3)

And last but not least, an example from an Mdoc based man page from FreeBSD [6]:

.Sh SEE ALSO
.Xr comm 1 ,
.Xr join 1 ,
.Xr uniq 1


I could mention lots of similar examples, but just open an arbitrary
man page in your terminal with "man", not in Vim; you will see that
(almost …) all SEE ALSO links are formatted bold. With the bold
formatting (and correct placing of the section number), you make sure
that *all* renderers, both the simple ones like "man" in the terminal
and the advanced HTML/DVI/PDF/whatever renderers, format the links
correctly. The additional lines in the *.x files don't eat up lots of
disk space or other resources. Please think about to apply my patch
once again.

[1] https://man.cx/diff3#heading3
[2] https://man.archlinux.org/man/man-pages.7.en#Formatting_conventions_for_manual_pages_describing_commands
[3] https://git.savannah.gnu.org/cgit/grub.git/tree/docs/man/grub-editenv.h2m
[4] https://git.savannah.gnu.org/cgit/grep.git/tree/doc/grep.in.1#n1359
[5] https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/man1/mtrace.1#n64
[6] https://github.com/freebsd/freebsd-src/blob/main/usr.bin/sort/sort.1.in#L580

Best Regards,
Mario

Message #19 received at 53977-done <at> debbugs.gnu.org (full text, mbox):

From: Pádraig Brady <P <at> draigBrady.com>
To: Mario Blättermann <mario.blaettermann <at> gmail.com>,
 53977-done <at> debbugs.gnu.org
Cc: man-pages <at> man7.org, Brendan O'Dea <bod <at> debian.org>
Subject: Re: bug#53977: Improve markup in man pages
Date: Mon, 14 Feb 2022 23:00:22 +0000

[Message part 1 (text/plain, inline)]

On 14/02/2022 13:52, Mario Blättermann wrote:
> Hello Pádraig,
> 
> Am Mo., 14. Feb. 2022 um 13:15 Uhr schrieb Pádraig Brady <P <at> draigbrady.com>:
>>
>> 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
>>
> 
> Maybe some renderers are smart enough to highlight this. But it
> shouldn't be up to the developers of such renderers to apply missing
> formattings virtually.

Thanks for the consideration on this.
I'm not strongly against hardcoding the formatting,
but I do think it's worth discussing the need.

Note we discussed this previously at:
https://lists.gnu.org/archive/html/coreutils/2021-01/msg00008.html

The summary there was things have trended over time
from a mixture of none,italic,bold style references
to mostly bold.

>> 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
>>
> Yes, but this doesn't work in all imaginable cases, because the
> renderer needs to be able to evaluate if it is a link or not. In your
> example, "shuf" is a link because it is tagged with the section
> number, but this wouldn't, then "shuf" would be as plain as other
> words. See the "diff3.1" man page [1]: > > -e, --ed
> output ed script incorporating changes from OLDFILE to YOURFILE into MYFILE
> 
> If "ed" would be "ed(1)" then it would be detected as a command name
> here, but it isn't.

But it isn't bold either.
I suggest this page should be updated to use "ed(1)".

> Well, the best solution would be to dig in the
> Help2man code and try to improve the detection of parts worth to be
> formatted - provided solid Perl skills. But this would be outside of
> the topic of this bug report;

Yes a `help2man --bold-refs` option seems useful.
It give the option to apply the formatting,
and more centrally, rather than inconsistently sprinkled
through all man pages.
Also this would be the only way to consistently
style all references in coreutils, since some are output
to the terminal through --help.

> let's go back to the SEE ALSO links. The
> man page man-pages(7) says [2]:
> 
> »The name of the command, and its options, should always be formatted in bold.«
>  
> In fact, the SEE ALSO links are also command names, although not the
> command the current man page describes. 

The bold here is pertaining to styling of the headers of the page,
rather than to any command references in general IMHO.
In general bold text interspersed in other text on the terminal
can be quite distracting to read. Some terminals can make it
bigger, brighter, blurrier, ...

> Let's have a look at other projects [that hardcode bold references]
> grub, grep, kernel.

I see Paul added the grep markup recently in a seemingly unrelated change:
https://git.savannah.gnu.org/gitweb/?p=grep.git;a=commit;h=fe630c9f

> I could mention lots of similar examples, but just open an arbitrary
> man page in your terminal with "man", not in Vim; you will see that
> (almost …) all SEE ALSO links are formatted bold.

I did check also, and see lots of inconsistencies.
BTW re vim, the match for references is:
  syn match manReference "\f\+([1-9][a-z]\=)"

> With the bold
> formatting (and correct placing of the section number), you make sure
> that *all* renderers, both the simple ones like "man" in the terminal
> and the advanced HTML/DVI/PDF/whatever renderers, format the links
> correctly.

"correctly" is a strong word here.

> [1] https://man.cx/diff3#heading3
> [2] https://man.archlinux.org/man/man-pages.7.en#Formatting_conventions_for_manual_pages_describing_commands
> [3] https://git.savannah.gnu.org/cgit/grub.git/tree/docs/man/grub-editenv.h2m
> [4] https://git.savannah.gnu.org/cgit/grep.git/tree/doc/grep.in.1#n1359
> [5] https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/man1/mtrace.1#n64
> [6] https://github.com/freebsd/freebsd-src/blob/main/usr.bin/sort/sort.1.in#L580

I've attached a patch to implement help2man --bold-refs.
Brendan is that something that might be added to official help2man?

coreutils enables this by default for generated man pages,
and it can be disabled if needed with:
  ./configure --disable-bold-man-page-references

Also attached is an ancillary patch I noticed with wrong section for exec(3p)

Marking this bug as done.

cheers,
Pádraig

[man-bold.patch (text/x-patch, attachment)]

[exec-3p.patch (text/x-patch, attachment)]

Message #22 received at 53977 <at> debbugs.gnu.org (full text, mbox):

From: Paul Eggert <eggert <at> cs.ucla.edu>
To: 53977 <at> debbugs.gnu.org
Cc: P <at> draigBrady.com, mario.blaettermann <at> gmail.com
Subject: Re: bug#53977: Improve markup in man pages
Date: Mon, 14 Feb 2022 19:07:34 -0800

On 2/14/22 15:00, Pádraig Brady wrote:
> 
> I see Paul added the grep markup recently in a seemingly unrelated change:
> https://git.savannah.gnu.org/gitweb/?p=grep.git;a=commit;h=fe630c9f
In the old days man pages' SEE ALSO sections mostly didn't use markup 
for references to other man pages. I see only one exception in 7th 
edition UNIX (1979): its man page for yacc used ".IR lex (1)" instead of 
plain "lex(1)".

Nowadays it seems that ".BR lex (1)" is what's preferred for this sort 
of thing, so I've been switching to this style desultorily in man pages 
when someone points it out, most recently in diffutils today:

https://git.savannah.gnu.org/gitweb/?p=diffutils.git;a=commitdiff;h=dd9deb765548679e821be565229bb2e142d93573

As usual man pages are low priority for the GNU project. That being 
said, this sort of thing is an easy change.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.