Re: style: .MR

[Alejandro Colomar (man-pages)]

On 2/7/22 20:41, Humm wrote:
> For functions, although perhaps looking fine, it’s semantically wrong. 
> The parentheses when referring to a function approximate its parameter
> or argument list.  Man page references, and thus uses of .MR, always
> include a number.

Tradition seems to differ:


man-pages(7):
       Any reference to the subject of the current  manual  page
       should  be  written  with  the name in bold followed by a
       pair of parentheses in Roman (normal) font.  For example,
       in the fcntl(2) man page, references to  the  subject  of
       the page would be written as: fcntl().  The preferred way
       to write this in the source file is:

           .BR fcntl ()


And some random FreeBSD man3 page:

printf(3):
     The printf() family of functions produces output according to a
format as
     described below.  The printf() and vprintf() functions write output to
     stdout, the standard output stream; fprintf() and vfprintf() write
output
     to the given output stream; dprintf() and vdprintf() write output
to the
     given file descriptor; sprintf(), snprintf(), vsprintf(), and
vsnprintf()
     write to the character string str; and asprintf() and vasprintf()
dynami-
     cally allocate a new string with malloc(3).

<https://www.freebsd.org/cgi/man.cgi?query=printf&apropos=0&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports&arch=default&format=html>

Both the Linux and FreeBSD man-pages use empty parentheses to refer to
the thing described (man2 and man3 only, of course).


> 
>> And if you specify the
>> section, you're a bit repetitive (but that's better than nothing).  And
>> then there's the option of using .B, or .I, but as we know, there's no
>> consensus on which of them should be used.
> 
> If you really want to refer to the man page itself, you can use wording
> like q.v.  If you want to refer to the thing described, you can fight
> for a consensus by using the one and only correct .I.  (Or .MR could be
> changed with only one or an empty second argument to not emit parentheses.)
> 



BTW, I just realized that FreeBSD man-pages also seem to use the one and
_in_correct bold to refer to the thing described :p


I think we should either use .MR without a number, or use .I/.B,
probably .I/.B, since there's no manual page reference going on.  From
there, man(7) tradition seems to prescribe .B, and groff(1) style seems
to prescribe .I...


Cheers,

Alex

-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/