[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: style: .MR
|
From: |
Humm |
|
Subject: |
Re: style: .MR |
|
Date: |
Mon, 7 Feb 2022 21:24:29 +0000 |
Quoth Alejandro Colomar (man-pages):
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 ()
man-pages(7) is for “man-pages,” not for all man pages. I don’t see it
having much value here, historical or otherwise. Anyway, that could be
interpreted by my statements: Rather than referring to the current
manual page, they actually refer to a utility or function or something
else. They don’t write “as described in *echo*, that program prints
something” but “*echo* prints something”. So for functions, they use
a distinct tradition of using parentheses approximating parameter or
argument lists. That doesn’t matter too much though.
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() dynamically allocate
a new string with malloc(3).
(^ reformatted by me)
<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).
FreeBSD uses -mdoc’s .Fn. A reference would be .Xr.
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
Nope, they use -mdoc. And -mdoc uses, for whatever reason, Courier:
\fC\s10.
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...
I think -man tradition quite clearly prescribes the use of .I. See, for
example, v7’s printf(3S):
.I Printf
places output on the standard output stream
.IR stdout .
--
Humm