mirror of https://github.com/mkerrisk/man-pages
man-pages.7: Add STYLE GUIDE section
Incorporate some of the existing material in the page into the STYLE GUIDE, and add a lot more material, mainly drawn from the "Global changes" sections in the release changelogs. Reported-by: Mike Frysinger <vapier@gentoo.org> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This commit is contained in:
Michael Kerrisk
parent
b437fdd90a
commit
7849287b90
273
man7/man-pages.7
273
man7/man-pages.7
|
|
@ -27,7 +27,7 @@
|
|||
.\" 2007-05-30 created by mtk, using text from old man.7 plus
|
||||
.\" rewrites and additional text.
|
||||
.\"
|
||||
.TH MAN-PAGES 7 2013-07-24 "Linux" "Linux Programmer's Manual"
|
||||
.TH MAN-PAGES 7 2014-01-03 "Linux" "Linux Programmer's Manual"
|
||||
.SH NAME
|
||||
man-pages \- conventions for writing Linux man pages
|
||||
.SH SYNOPSIS
|
||||
|
|
@ -126,8 +126,7 @@ The section number in which the man page should be placed (e.g.,
|
|||
.TP
|
||||
.I date
|
||||
The date of the last revision\(emremember to change this every time a
|
||||
change is made to the man page,
|
||||
since this is the most general way of doing version control.
|
||||
nontrivial change is made to the man page.
|
||||
Dates should be written in the form YYYY-MM-DD.
|
||||
.TP
|
||||
.I source
|
||||
|
|
@ -393,6 +392,9 @@ in which various system calls first appeared.
|
|||
.B CONFORMING TO
|
||||
describes any standards or conventions that relate to the function
|
||||
or command described by the manual page.
|
||||
The preferred terms to use for the various standards are listed as
|
||||
headings in
|
||||
.BR standards (7).
|
||||
For a page in Section 2 or 3,
|
||||
this section should note the POSIX.1
|
||||
version(s) that the call conforms to,
|
||||
|
|
@ -454,6 +456,20 @@ and
|
|||
directives.
|
||||
Hyphenation of individual page names can be prevented
|
||||
by preceding words with the string "\\%".
|
||||
.SH STYLE GUIDE
|
||||
The following subsections represent the beginnings of a style guide
|
||||
for the
|
||||
.IR "man-pages"
|
||||
project.
|
||||
For details not covered below, the Chicago Manual of Style
|
||||
is usually a good source.
|
||||
.SS Use of gender-neutral language
|
||||
As far as possible, use gender-neutral language in the text of man
|
||||
page.
|
||||
Use of "they" ("them", "themself", "their") as a gender-neutral singular
|
||||
pronoun is acceptable for pages in the
|
||||
.IR man-pages
|
||||
project.
|
||||
.SS Font conventions
|
||||
.PP
|
||||
For functions, the arguments are always specified using italics,
|
||||
|
|
@ -542,17 +558,245 @@ The preferred way to write this in the source file is:
|
|||
(Including the section number in cross references lets tools like
|
||||
.BR man2html (1)
|
||||
create properly hyperlinked pages.)
|
||||
|
||||
Control characters should be written in bold face,
|
||||
with no quotes; for example,
|
||||
.BR ^X .
|
||||
.SS Spelling
|
||||
Starting with release 2.59,
|
||||
.I man-pages
|
||||
follows American spelling conventions
|
||||
(previously, there was a random mix of British and American spallings);
|
||||
(previously, there was a random mix of British and American spellings);
|
||||
please write all new pages and patches according to these conventions.
|
||||
|
||||
Aside from the well-known spelling differences,
|
||||
there are a few other subtleties to watch for:
|
||||
.IP * 3
|
||||
American English tends to use the forms "backward" "upward", 'toward",
|
||||
and so on
|
||||
rather than the British forms "backwards", upwards", "towards", and so on.
|
||||
.SS BSD version numbers
|
||||
The classical scheme for writing BSD version numbers is
|
||||
.IR x.yBSD ,
|
||||
where
|
||||
.I x.y
|
||||
is the version number (e.g., 4.2BSD).
|
||||
Avoid forms such as
|
||||
.IR "BSD 4.3" .
|
||||
.SS Capitalization
|
||||
In subsection ("SS") headings
|
||||
capitalize the first word in heading, but otherwise use lower case,
|
||||
In subsection ("SS") headings,
|
||||
capitalize the first word in the heading, but otherwise use lower case,
|
||||
except where English usage (e.g., proper nouns) or programming
|
||||
language requirements (e.g., identifier names) dictate otherwise.
|
||||
.SS Indentation of structure definitions, shell session logs, etc.
|
||||
When structure definitions, shell session logs, and so on are included
|
||||
in running text, indent them by 4 spaces (i.e., a block enclosed by
|
||||
.I ".in\ +4n"
|
||||
and
|
||||
.IR ".in" ).
|
||||
.SS Preferred terms
|
||||
The following table lists some preferred terms to use in man pages,
|
||||
mainly to ensure consistency across pages.
|
||||
.ad l
|
||||
.TS
|
||||
l l l
|
||||
---
|
||||
l l l.
|
||||
Term Avoid using Notes
|
||||
|
||||
bit mask bitmask
|
||||
built-in builtin
|
||||
Epoch epoch T{
|
||||
For the UNIX Epoch (00:00:00, 1 Jan 1970 UTC)
|
||||
T}
|
||||
filename file name
|
||||
hostname host name
|
||||
inode i-node
|
||||
pathname path name
|
||||
pseudoterminal pseudo-terminal
|
||||
privileged port T{
|
||||
reserved port,
|
||||
system port
|
||||
T}
|
||||
real-time T{
|
||||
realtime,
|
||||
real-time
|
||||
T}
|
||||
run time runtime
|
||||
saved set-group-ID T{
|
||||
saved group ID,
|
||||
saved set-GID
|
||||
T}
|
||||
saved set-user-ID T{
|
||||
saved user ID,
|
||||
saved set-UID
|
||||
T}
|
||||
set-group-ID set-GID, setgid
|
||||
set-user-ID set-UID, setuid
|
||||
superuser T{
|
||||
super user,
|
||||
super-user
|
||||
T}
|
||||
timestamp time stamp
|
||||
timezone time zone
|
||||
user space userspace
|
||||
username user name
|
||||
zeros zeroes
|
||||
.TE
|
||||
.ad
|
||||
.SS Terms to avoid
|
||||
The following table lists some terms to avoid using in man pages,
|
||||
along with some suggested alternatives,
|
||||
mainly to ensure consistency across pages.
|
||||
.ad l
|
||||
.TS
|
||||
l l l
|
||||
---
|
||||
l l l.
|
||||
Avoid Use instead Notes
|
||||
|
||||
current process calling process T{
|
||||
A common mistake made by kernel programmers when writing man pages
|
||||
T}
|
||||
manpage T{
|
||||
man page, manual page
|
||||
T}
|
||||
minus infinity negative infinity
|
||||
non-root unprivileged user
|
||||
non-superuser unprivileged user
|
||||
nonprivileged unprivileged
|
||||
OS operating system
|
||||
plus infinity positive infinity
|
||||
pty pseudoterminal
|
||||
runtime run time
|
||||
tty terminal
|
||||
Unices UNIX systems
|
||||
Unixes UNIX systems
|
||||
.TE
|
||||
.ad
|
||||
.SS Trademarks
|
||||
Use the correct spelling of trademarks.
|
||||
The following is a list of the correct spelling of various
|
||||
relevant trademarks that are sometimes misspelled:
|
||||
|
||||
DG/UX
|
||||
HP-UX
|
||||
UNIX
|
||||
UnixWare
|
||||
.SS NULL, NUL, null pointer, and null character
|
||||
A
|
||||
.IR "null pointer"
|
||||
is a pointer that points to nothing,
|
||||
and is normally indicated by the constant
|
||||
.IR NULL .
|
||||
On the other hand,
|
||||
.I NUL
|
||||
is the
|
||||
.IR "null byte",
|
||||
a byte with the value 0, represented in C via the character constant
|
||||
.IR \(aq\e0\(aq .
|
||||
|
||||
The preferred term for the pointer is "null pointer" or simply "NULL";
|
||||
avoid writing "NULL pointer".
|
||||
|
||||
The preferred term for the byte is "null byte".
|
||||
Avoid writing "NUL", since it is too easily confused with "NULL".
|
||||
Avoid also the terms "zero byte" and "null character".
|
||||
The byte that terminates a C string should be described
|
||||
as "the terminating null byte";
|
||||
strings may be described as "null-terminated",
|
||||
but avoid the use of "NUL-terminated".
|
||||
.SS Hyperlinks
|
||||
For hyperlinks, use the
|
||||
.IR .UR / .UE
|
||||
macro pair
|
||||
(see
|
||||
.BR groff_man (7)).
|
||||
This produces proper hyperlinks that can be used in a web browser,
|
||||
when rendering a page with, say:
|
||||
|
||||
BROWSER=firefox man -H pagename
|
||||
.SS Use of e.g., i.e., etc., a.k.a., and similar
|
||||
In general, the use of abbreviations such as "e.g.", "i.e.", "etc.", "a.k.a."
|
||||
should be avoided, in favor of suitable full wordings
|
||||
("for example", "that is", "and so on", "also known as").
|
||||
|
||||
The only place where such abbreviations may be acceptable is in
|
||||
.I short
|
||||
parenthetical asides (e.g., like this one).
|
||||
|
||||
Always include periods in such abbreviations, as shown here.
|
||||
In addition, "e.g." and "i.e." should always be followed by a comma.
|
||||
.SS Em-dashes
|
||||
The way to write an em-dash (\(em) in *roff is with the macro "\\(em".
|
||||
Em-dashes should be written
|
||||
.I without
|
||||
surrounding spaces.
|
||||
.SS Hyphenation of attributive compounds
|
||||
Counpound terms should by hyphenated when used attributively
|
||||
(i.e., to qualify a following noun) Some examples:
|
||||
|
||||
command-line argument
|
||||
floating-point number
|
||||
run-time check
|
||||
user-space function
|
||||
wide-character string
|
||||
.SS Hyphenation with multi, non, pre, re, sub, and so on
|
||||
The general tendency in modern English is not to hyphenate
|
||||
after prefixes such as "multi", "non", "pre", "re", "sub", and so on.
|
||||
Manual pages should generally follow this rule when these prefixes are
|
||||
used in natural English constructions with simple suffixes.
|
||||
The following list gives some examples of the preferred forms:
|
||||
|
||||
interprocess
|
||||
multithreaded
|
||||
multiprocess
|
||||
nonblocking
|
||||
nondefault
|
||||
nonempty
|
||||
noninteractive
|
||||
nonnegative
|
||||
nonportable
|
||||
nonzero
|
||||
preallocated
|
||||
precreate
|
||||
prerecorded
|
||||
reestablished
|
||||
reinitialize
|
||||
rearm
|
||||
reread
|
||||
subcomponent
|
||||
subdirectory
|
||||
subsystem
|
||||
|
||||
Hyphens should be retained when the prefixes are used in nonstandard
|
||||
English words, with trademarks, proper nouns, acronyms, or compound terms.
|
||||
Some examples:
|
||||
|
||||
non-ASCII
|
||||
non-English
|
||||
non-NULL
|
||||
non-real-time
|
||||
|
||||
Finally, note that "re-create" and "recreate" are two different verbs,
|
||||
and the former is probably what you want.
|
||||
.SS Real hyphen character
|
||||
Where a real hyphen character is required (e.g., for numbers such as \-1),
|
||||
use the following form in the man page source
|
||||
|
||||
\\-
|
||||
|
||||
This guideline applies also to code examples.
|
||||
.SS Character constants
|
||||
To produce single quotes that render well in both ASCII and UTF-8,
|
||||
use the following form for character constants in the man page source:
|
||||
|
||||
\\(aqC\\(aq
|
||||
|
||||
where
|
||||
.I C
|
||||
is the quoted character.
|
||||
This guideline applies also to character constants used in code examples.
|
||||
.SS Example programs and shell sessions
|
||||
Manual pages can include example programs demonstrating how to
|
||||
use a system call or library function.
|
||||
|
|
@ -584,6 +828,17 @@ Example programs should be laid out according to Kernighan and
|
|||
Ritchie style, with 4-space indents.
|
||||
(Avoid the use of TAB characters in source code!)
|
||||
.IP *
|
||||
For consistency, all example programs terminate using either of;
|
||||
|
||||
exit(EXIT_SUCCESS);
|
||||
exit(EXIT_FAILURE);
|
||||
|
||||
Avoid using the following forms to terminate a program:
|
||||
|
||||
exit(0);
|
||||
exit(1);
|
||||
return n;
|
||||
.IP *
|
||||
If there is extensive explanatory text before the
|
||||
program source code, mark off the source code
|
||||
with a susbsection heading
|
||||
|
|
@ -608,12 +863,6 @@ For some examples of what example programs should look like, see
|
|||
.BR wait (2)
|
||||
and
|
||||
.BR pipe (2).
|
||||
.SS Indentation of structure definitions, shell session logs, etc.
|
||||
When structure definitions, shell session logs, and so on are included
|
||||
in running text, indent them by 4 spaces (i.e., a block enclosed by
|
||||
.I ".in\ +4n"
|
||||
and
|
||||
.IR ".in" ).
|
||||
.SH EXAMPLE
|
||||
For canonical examples of how man pages in the
|
||||
.I man-pages
|
||||
|
|
|
|||
Loading…
Reference in New Issue