.\" 2007-05-30 created by mtk, using text from old man.7 plus
.\" rewrites and additional text.
.\"
-.TH MAN-PAGES 7 2013-06-21 "Linux" "Linux Programmer's Manual"
+.TH MAN-PAGES 7 2014-03-16 "Linux" "Linux Programmer's Manual"
.SH NAME
man-pages \- conventions for writing Linux man pages
.SH SYNOPSIS
.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
.\" SECURITY,
ENVIRONMENT
FILES
-ATTRIBUTES [Normally only in Sections 2, 3]
VERSIONS [Normally only in Sections 2, 3]
+ATTRIBUTES [Normally only in Sections 2, 3]
CONFORMING TO
NOTES
BUGS
.\" section (and just place an overview in the
.\" .B DESCRIPTION
.\" section).
+
+When describing new behavior or new flags for
+a system call or library function,
+be careful to note the kernel or C library version
+that introduced the change.
+The preferred method of noting this information for flags is as part of a
+.B .TP
+list, in the following form (here, for a new system call flag):
+.RS 22
+.TP
+.BR XYZ_FLAG " (since Linux 3.7)"
+Description of flag...
+.RE
+.IP
+Including version information is especially useful to users
+who are constrained to using older kernel or C library versions
+(which is typical in embedded systems, for example).
.TP
.B OPTIONS
describes the command-line options accepted by a
.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,
directives.
Hyphenation of individual page names can be prevented
by preceding words with the string "\\%".
+.SH STYLE GUIDE
+The following subsections describe the preferred style for the
+.IR man-pages
+project.
+For details not covered below, the Chicago Manual of Style
+is usually a good source;
+try also grepping for preexisting usage in the project source tree.
+.SS Use of gender-neutral language
+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
.PP
For functions, the arguments are always specified using italics,
.PP
Variable names should, like argument names, be specified in italics.
.PP
-Filenames (whether pathnames, or references to files in the
-.I /usr/include
-directory)
+Filenames (whether pathnames, or references to header files)
are always in italics (e.g.,
.IR <stdio.h> ),
except in the SYNOPSIS section, where included files are in bold (e.g.,
.BR "#include <stdio.h>" ).
-When referring to a standard include file under
-.IR /usr/include ,
+When referring to a standard header file include,
specify the header file surrounded by angle brackets,
in the usual C way (e.g.,
.IR <stdio.h> ).
.PP
-Special macros, which are usually in upper case, are in bold (e.g.,
+Special macros, which are usually in uppercase, are in bold (e.g.,
.BR MAXINT ).
Exception: don't boldface NULL.
.PP
macro).
.PP
Complete commands should, if long,
-be written as in an indented line on their own, for example
+be written as an indented line on their own,
+with a blank line before and after the command, for example
.in +4n
.nf
.IR "man 7 man-pages" .
In this case, it may be worth using nonbreaking spaces
("\e\ ") at suitable places in the command.
-Command options should be written in italics, e.g.,
-.IR \-l .
+Command options should be written in italics (e.g.,
+.IR \-l ).
.PP
Expressions, if not written on a separate indented line, should
be specified in italics.
(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;
+follows American spelling conventions
+(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 lowercase,
except where English usage (e.g., proper nouns) or programming
language requirements (e.g., identifier names) dictate otherwise.
+For example:
+
+ .SS Unicode under Linux
+
+.SS Indentation of structure definitions, shell session logs, and so on
+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.
+.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
+filesystem file system
+hostname host name
+inode i-node
+lowercase lower case, lower-case
+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}
+superblock T{
+super block,
+super-block
+T}
+timestamp time stamp
+timezone time zone
+uppercase upper case, upper-case
+usable useable
+user space userspace
+username user name
+zeros zeroes
+.TE
+.PP
+See also the discussion
+.IR "Hyphenation of attributive compounds"
+below.
+.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.
+.TS
+l l l
+---
+l l l.
+Avoid Use instead Notes
+
+32bit 32-bit T{
+same for 8-bit, 16-bit, etc.
+T}
+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
+tty terminal
+Unices UNIX systems
+Unixes UNIX systems
+.TE
+.SS Trademarks
+Use the correct spelling and case for trademarks.
+The following is a list of the correct spellings 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\(emthe glyph that appears
+at either end of this subphrase\(emin *roff is with the macro "\\(em".
+(On an ASCII terminal, an em-dash typically renders as two hyphens,
+but in other typographical contexts it renders as a long dash.)
+Em-dashes should be written
+.I without
+surrounding spaces.
+.SS Hyphenation of attributive compounds
+Compound terms should be hyphenated when used attributively
+(i.e., to qualify a following noun). Some examples:
+
+ 32-bit value
+ 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 minus character
+Where a real minus character is required (e.g., for numbers such as \-1,
+or when writing options that have a leading dash, such as in
+.IR "ls\ \-l"),
+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
+Manual pages may include example programs demonstrating how to
use a system call or library function.
However, note the following:
-.TP 3
-*
+.IP * 3
Example programs should be written in C.
-.TP
-*
+.IP *
An example program is necessary and useful only if it demonstrates
something beyond what can easily be provided in a textual
description of the interface.
An example program that does nothing
other than call an interface usually serves little purpose.
-.TP
-*
+.IP *
Example programs should be fairly short (preferably less than 100 lines;
ideally less than 50 lines).
-.TP
-*
+.IP *
Example programs should do error checking after system calls and
library function calls.
-.TP
-*
+.IP *
Example programs should be complete, and compile without
warnings when compiled with \fIcc\ \-Wall\fP.
-.TP
-*
+.IP *
Where possible and appropriate, example programs should allow
experimentation, by varying their behavior based on inputs
(ideally from command-line arguments, or alternatively, via
input read by the program).
-.TP
-*
+.IP *
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 should 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
+.IR "Program source" ,
+as in:
+
+ .SS Program source
+
+Always do this if the explanatory text includes a shell session log.
+.PP
+If you include a shell session log demonstrating the use of a program
+or other system feature:
+.IP * 3
+Place the session log above the source code listing
+.IP *
+Indent the session log by four spaces.
+.IP *
+Boldface the user input text,
+to distinguish it from output produced by the system.
.PP
For some examples of what example programs should look like, see
.BR wait (2)
and
.BR pipe (2).
-
-If you include a shell session demonstrating the use of a program
-or other system feature, boldface the user input text,
-to distinguish it from output produced by the system.
-.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
.BR groff_man (7),
.BR man (7),
.BR mdoc (7)
+.SH COLOPHON
+This page is part of release 3.65 of the Linux
+.I man-pages
+project.
+A description of the project,
+and information about reporting bugs,
+can be found at
+\%http://www.kernel.org/doc/man\-pages/.
OSDN Git Service
