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.
|
pages.
|
||||||
Use of "they" ("them", "themself", "their") as a gender-neutral singular
|
Use of "they" ("them", "themself", "their") as a gender-neutral singular
|
||||||
pronoun is acceptable.
|
pronoun is acceptable.
|
||||||
.SS Font conventions
|
.\"
|
||||||
|
.SS Formatting conventions for manual pages describing functions
|
||||||
.PP
|
.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" ,
|
.IR "even in the SYNOPSIS section" ,
|
||||||
where the rest of the function is specified in bold:
|
where the rest of the function is specified in bold:
|
||||||
.PP
|
.PP
|
||||||
.BI " int myfunction(int " argc ", char **" argv );
|
.BI " int myfunction(int " argc ", char **" argv );
|
||||||
.PP
|
.PP
|
||||||
Variable names should, like argument names, be specified in italics.
|
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)
|
Filenames (whether pathnames, or references to header files)
|
||||||
are always in italics (e.g.,
|
are always in italics (e.g.,
|
||||||
.IR <stdio.h> ),
|
.IR <stdio.h> ),
|
||||||
|
@ -511,7 +538,7 @@ When enumerating a list of error codes, the codes are in bold (this list
|
||||||
usually uses the
|
usually uses the
|
||||||
.B \&.TP
|
.B \&.TP
|
||||||
macro).
|
macro).
|
||||||
.PP
|
|
||||||
Complete commands should, if long,
|
Complete commands should, if long,
|
||||||
be written as an indented line on their own,
|
be written as an indented line on their own,
|
||||||
with a blank line before and after the command, for example
|
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.
|
be specified in italics.
|
||||||
Again, the use of nonbreaking spaces may be appropriate
|
Again, the use of nonbreaking spaces may be appropriate
|
||||||
if the expression is inlined with normal text.
|
if the expression is inlined with normal text.
|
||||||
.PP
|
|
||||||
Any reference to the subject of the current manual page
|
When showing example shell sessions, user input should be formatted in bold, for example
|
||||||
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:
|
|
||||||
.nf
|
.nf
|
||||||
|
.in +4n
|
||||||
.BR fcntl ()
|
$ \fBdate\fP
|
||||||
|
Thu Jul 7 13:01:27 CEST 2016
|
||||||
|
.in
|
||||||
.fi
|
.fi
|
||||||
(Using this format, rather than the use of "\\fB...\\fP()"
|
|
||||||
makes it easier to write tools that parse man page source files.)
|
|
||||||
.PP
|
.PP
|
||||||
Any reference to another man page
|
Any reference to another man page
|
||||||
should be written with the name in bold,
|
should be written with the name in bold,
|
||||||
|
|
Loading…
Reference in New Issue