coreutils
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: man pages: formatting of entries in "SEE ALSO" section


From: Pádraig Brady
Subject: Re: man pages: formatting of entries in "SEE ALSO" section
Date: Sun, 3 Jan 2021 14:39:22 +0000
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:84.0) Gecko/20100101 Thunderbird/84.0

On 02/01/2021 14:23, Bernhard Voelker wrote:
Hi Padraig,

On 1/2/21 1:23 PM, Pádraig Brady wrote:
The man viewer has enough context to highlight these references as appropriate,
so we shouldn't be explicitly specifying style.

Hmm, 'man' on my system doesn't show them in bold, and neither does the
HTML view via 'man -H'.  Does it do for you?

I've used vim to view man pages since forever,
and that highlights blah(#), and allows one to
navigate into those references with tag stack navigation commands.
See MANPAGER in my .bashrc (and also I map <ALT>-{Left,Right}
to navigation in my .vimrc):
https://www.pixelbeat.org/settings/


man(1) and man-pages(7) explicitly mark the SEE ALSO entries as bold, so that 
seems
to be the general direction.  So I'm 55:45 for using the explicit variant.

Oh right. That's a bit of a layering violation in my mind, but fair enough.

One ML reader (Mingye Wang) wrote to me privately that he would also recommend
the bold formatting.

FWIW: if we'd consider changing to bold:
the syntax-check rule 'sc_prohibit_man_see_also_period' only works with 
'\fB...\fP'
entries in one line, while having each entry in a separate '.BR' line would be 
easier
to read.

I also agree with the cat(1) reference,
so +1 to the whole patch.

Thanks.  To have the formatting consistent for now, I've wrapped the
diff into a proper patch (attached).  Feel free to apply.

I've applied the patch so that we're consistent within coreutils at least.

I wouldn't be against a further patch to use bold everywhere,
so we're more consistent with other man pages.
BTW I see that the man-pages project uses .BR macros on separate lines for this
(which render to a single line):
https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/?id=05d13bf

BTW Michael, should the patch at the above URL have a trailing comma?

cheers,
Pádraig



reply via email to

[Prev in Thread] Current Thread [Next in Thread]