mirror of https://github.com/mkerrisk/man-pages
man-pages.7: Add a few more details on formatting conventions
Add some more details for Section 1 and 8 formatting. Separate out formatting discussion into commands, functions, and "general". In part triggered by https://bugzilla.kernel.org/show_bug.cgi?id=121211 Reported-by: Josh Triplett <josh@kernel.org> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This commit is contained in:
parent
0b9200154c
commit
c0ada844e0
|
@ -483,16 +483,43 @@ As far as possible, use gender-neutral language in the text of man
|
|||
pages.
|
||||
Use of "they" ("them", "themself", "their") as a gender-neutral singular
|
||||
pronoun is acceptable.
|
||||
.SS Font conventions
|
||||
.\"
|
||||
.SS Formatting conventions for manual pages describing functions
|
||||
.PP
|
||||
For functions, the arguments are always specified using italics,
|
||||
For manual pages that describe command (typically in Sections 1 and 8),
|
||||
the arguments are always specified using italics,
|
||||
.IR "even in the SYNOPSIS section" .
|
||||
|
||||
The name of the command, and its options, should
|
||||
always be formatted in bold.
|
||||
.\"
|
||||
.SS Formatting conventions for manual pages describing functions
|
||||
For manual pages that describe functions (typically in Sections 2 and 3),
|
||||
the arguments are always specified using italics,
|
||||
.IR "even in the SYNOPSIS section" ,
|
||||
where the rest of the function is specified in bold:
|
||||
.PP
|
||||
.BI " int myfunction(int " argc ", char **" argv );
|
||||
.PP
|
||||
Variable names should, like argument names, be specified in italics.
|
||||
.PP
|
||||
|
||||
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
|
||||
.BR fcntl (2)
|
||||
man page, references to the subject of the page would be written as:
|
||||
.BR fcntl ().
|
||||
The preferred way to write this in the source file is:
|
||||
.nf
|
||||
|
||||
.BR fcntl ()
|
||||
|
||||
.fi
|
||||
(Using this format, rather than the use of "\\fB...\\fP()"
|
||||
makes it easier to write tools that parse man page source files.)
|
||||
.\"
|
||||
.SS Formatting conventions (general)
|
||||
Filenames (whether pathnames, or references to header files)
|
||||
are always in italics (e.g.,
|
||||
.IR <stdio.h> ),
|
||||
|
@ -511,7 +538,7 @@ When enumerating a list of error codes, the codes are in bold (this list
|
|||
usually uses the
|
||||
.B \&.TP
|
||||
macro).
|
||||
.PP
|
||||
|
||||
Complete commands should, if long,
|
||||
be written as an indented line on their own,
|
||||
with a blank line before and after the command, for example
|
||||
|
@ -534,24 +561,15 @@ Expressions, if not written on a separate indented line, should
|
|||
be specified in italics.
|
||||
Again, the use of nonbreaking spaces may be appropriate
|
||||
if the expression is inlined with normal text.
|
||||
.PP
|
||||
Any reference to the subject of the current manual page
|
||||
should be written with the name in bold.
|
||||
If the subject is a function (i.e., this is a Section 2 or 3 page),
|
||||
then the name should be followed by a pair of parentheses
|
||||
in Roman (normal) font.
|
||||
For example, in the
|
||||
.BR fcntl (2)
|
||||
man page, references to the subject of the page would be written as:
|
||||
.BR fcntl ().
|
||||
The preferred way to write this in the source file is:
|
||||
|
||||
When showing example shell sessions, user input should be formatted in bold, for example
|
||||
|
||||
.nf
|
||||
|
||||
.BR fcntl ()
|
||||
|
||||
.in +4n
|
||||
$ \fBdate\fP
|
||||
Thu Jul 7 13:01:27 CEST 2016
|
||||
.in
|
||||
.fi
|
||||
(Using this format, rather than the use of "\\fB...\\fP()"
|
||||
makes it easier to write tools that parse man page source files.)
|
||||
.PP
|
||||
Any reference to another man page
|
||||
should be written with the name in bold,
|
||||
|
|
Loading…
Reference in New Issue