diff options
| author | Michael Kerrisk <mtk.manpages@gmail.com> | 2016-07-07 13:14:21 +0200 |
|---|---|---|
| committer | Michael Kerrisk <mtk.manpages@gmail.com> | 2016-07-07 13:23:13 +0200 |
| commit | c0ada844e0176bebfec26ce9a3c097046b8bd07d (patch) | |
| tree | 3c951ecdd236ca74e24fd1b992e64da01c3b0060 /man7/man-pages.7 | |
| parent | 0b9200154c2e2cc3f9104390a01c124baacb20da (diff) | |
| download | man-pages-c0ada844e0176bebfec26ce9a3c097046b8bd07d.tar.gz | |
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>
Diffstat (limited to 'man7/man-pages.7')
| -rw-r--r-- | man7/man-pages.7 | 56 |
1 files changed, 37 insertions, 19 deletions
diff --git a/man7/man-pages.7 b/man7/man-pages.7 index 70a944340b..da73ff2aec 100644 --- a/man7/man-pages.7 +++ b/man7/man-pages.7 @@ -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: -.nf - .BR fcntl () +When showing example shell sessions, user input should be formatted in bold, for example +.nf +.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, |