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

[Pádraig Brady]

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