LDP
/
man-pages
mirror of https://github.com/mkerrisk/man-pages
0
1
Fork 0
Code Releases Activity

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:
Michael Kerrisk 2016-07-07 13:14:21 +02:00
parent 0b9200154c
commit c0ada844e0
1 changed files with 38 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

58
man7/man-pages.7
View File

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