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

[Michael Kerrisk (man-pages)]

Hi Pádraig, hi Bernhard

On 1/3/21 3:39 PM, Pádraig Brady wrote:
> 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.

For what it's worth, formatting of the form

.BR name (n)

(i.e., bold interface name, normal text section reference) seems to
be the norm. Looking at the SEE ALSO sections in the 140 or so projects
whose pages I render at https://man7.org/linux/man-pages, the vast majority
of the cross references are formatted this way. Next most common is no
formatting (i.e., just "name(n)") followed by italic (underline) formatting.
(My rendering scripts try to convert everything to bold.)

When I inherited man-pages, the formatting was rather inconsistent.
.BR was the majority, but there were many cases of .IR or no formatting
at all. I fixed those early on.

>> 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 strongly agree on that last point. Single line entries is a much 
easier form to read in *roff source.

>>> 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,

Just by the way, the norm in man-pages (and in many other projects) is 
bold for page references, not just those in SEE ALSO.

> 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?

Indeed! Fixed.

Thanks,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/