соглашения для написания страниц руководства Linux (conventions for writing Linux man pages)
STYLE GUIDE
The following subsections describe the preferred style for the
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.
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.
Formatting conventions for manual pages describing commands
For manual pages that describe a command (typically in Sections 1
and 8), the arguments are always specified using italics, even in
the SYNOPSIS section.
The name of the command, and its options, should always be
formatted in bold.
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, even in
the SYNOPSIS section, where the rest of the function is specified
in bold:
int myfunction(int argc, char **argv);
Variable names should, like argument names, be specified in
italics.
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 fcntl(2) man page,
references to the subject of the page would be written as:
fcntl(). The preferred way to write this in the source file is:
.BR fcntl ()
(Using this format, rather than the use of "\fB...\fP()" makes it
easier to write tools that parse man page source files.)
Use semantic newlines
In the source of a manual page, new sentences should be started
on new lines, and long sentences should be split into lines at
clause breaks (commas, semicolons, colons, and so on). This
convention, sometimes known as "semantic newlines", makes it
easier to see the effect of patches, which often operate at the
level of individual sentences or sentence clauses.
Formatting conventions (general)
Paragraphs should be separated by suitable markers (usually
either .PP or .IP). Do not separate paragraphs using blank
lines, as this results in poor rendering in some output formats
(such as PostScript and PDF).
Filenames (whether pathnames, or references to header files) are
always in italics (e.g., <stdio.h>), except in the SYNOPSIS
section, where included files are in bold (e.g., #include
<stdio.h>). When referring to a standard header file include,
specify the header file surrounded by angle brackets, in the
usual C way (e.g., <stdio.h>).
Special macros, which are usually in uppercase, are in bold
(e.g., MAXINT). Exception: don't boldface NULL.
When enumerating a list of error codes, the codes are in bold
(this list usually uses the .TP macro).
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
man 7 man-pages
If the command is short, then it can be included inline in the
text, in italic format, for example, man 7 man-pages. In this
case, it may be worth using nonbreaking spaces ("\ ") at suitable
places in the command. Command options should be written in
italics (e.g., -l).
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.
When showing example shell sessions, user input should be
formatted in bold, for example
$ date
Thu Jul 7 13:01:27 CEST 2016
Any reference to another man page should be written with the name
in bold, always followed by the section number, formatted in
Roman (normal) font, without any separating spaces (e.g.,
intro(2)). The preferred way to write this in the source file
is:
.BR intro (2)
(Including the section number in cross references lets tools like
man2html(1) create properly hyperlinked pages.)
Control characters should be written in bold face, with no
quotes; for example, ^X.
Spelling
Starting with release 2.59, man-pages 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:
* American English tends to use the forms "backward", "upward",
"toward", and so on rather than the British forms "backwards",
"upwards", "towards", and so on.
* Opinions are divided on "acknowledgement" vs "acknowledgment".
The latter is predominant, but not universal usage in American
English. POSIX and the BSD license use the former spelling.
In the Linux man-pages project, we use "acknowledgement".
BSD version numbers
The classical scheme for writing BSD version numbers is x.yBSD,
where x.y is the version number (e.g., 4.2BSD). Avoid forms such
as BSD 4.3.
Capitalization
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
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 .in +4n and .in), format them using the .EX and EE
macros, and surround them with suitable paragraph markers (either
.PP or .IP). For example:
.PP
.in +4n
.EX
int
main(int argc, char *argv[])
{
return 0;
}
.EE
.in
.PP
Preferred terms
The following table lists some preferred terms to use in man
pages, mainly to ensure consistency across pages.
Term Avoid using Notes
─────────────────────────────────────────────────────────────
bit mask bitmask
built-in builtin
Epoch epoch For the UNIX
Epoch
(00:00:00, 1
Jan 1970 UTC)
filename file name
filesystem file system
hostname host name
inode i-node
lowercase lower case, lower-case
nonzero non-zero
pathname path name
pseudoterminal pseudo-terminal
privileged port reserved port, system
port
real-time realtime, real time
run time runtime
saved set-group-ID saved group ID, saved
set-GID
saved set-user-ID saved user ID, saved
set-UID
set-group-ID set-GID, setgid
set-user-ID set-UID, setuid
superuser super user, super-user
superblock super block, super-
block
timestamp time stamp
timezone time zone
uppercase upper case, upper-case
usable useable
user space userspace
username user name
x86-64 x86_64 Except if
referring to
result of
"uname -m" or
similar
zeros zeroes
See also the discussion Hyphenation of attributive compounds
below.
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.
Avoid Use instead Notes
────────────────────────────────────────────────────────
32bit 32-bit same for 8-bit,
16-bit, etc.
current process calling process A common mistake
made by kernel
programmers when
writing man pages
manpage man page, manual
page
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
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
NULL, NUL, null pointer, and null byte
A null pointer is a pointer that points to nothing, and is
normally indicated by the constant NULL. On the other hand, NUL
is the null byte, a byte with the value 0, represented in C via
the character constant '\0'.
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".
Hyperlinks
For hyperlinks, use the .UR/.UE macro pair (see 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
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.", "cf.", and "a.k.a." should be avoided, in favor of
suitable full wordings ("for example", "that is", "and so on",
"compare to", "also known as").
The only place where such abbreviations may be acceptable is in
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.
Em-dashes
The way to write an em-dash—the glyph that appears at either end
of this subphrase—in *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 without surrounding spaces.
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
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.
Generating optimal glyphs
Where a real minus character is required (e.g., for numbers such
as -1, for man page cross references such as utf-8(7), or when
writing options that have a leading dash, such as in ls -l), use
the following form in the man page source:
\-
This guideline applies also to code examples.
The use of real minus signs serves the following purposes:
* To provide better renderings on various targets other than
ASCII terminals, notably in PDF and on Unicode/UTF-8-capable
terminals.
* To generate glyphs that when copied from rendered pages will
produce real minus signs when pasted into a terminal.
To produce unslanted single quotes that render well in ASCII,
UTF-8, and PDF, use "\(aq" ("apostrophe quote"); for example
\(aqC\(aq
where C is the quoted character. This guideline applies also to
character constants used in code examples.
Where a proper caret (^) that renders well in both a terminal and
PDF is required, use "\(ha". This is especially necessary in
code samples, to get a nicely rendered caret when rendering to
PDF.
Using a naked "~" character results in a poor rendering in PDF.
Instead use "\(ti". This is especially necessary in code
samples, to get a nicely rendered tilde when rendering to PDF.
Example programs and shell sessions
Manual pages may include example programs demonstrating how to
use a system call or library function. However, note the
following:
* Example programs should be written in C.
* 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.
* Example programs should ideally be short (e.g., a good example
can often be provided in less than 100 lines of code), though
in some cases longer programs may be necessary to properly
illustrate the use of an API.
* Expressive code is appreciated.
* Comments should included where helpful. Complete sentences in
free-standing comments should be terminated by a period.
Periods should generally be omitted in "tag" comments (i.e.,
comments that are placed on the same line of code); such
comments are in any case typically brief phrases rather than
complete sentences.
* Example programs should do error checking after system calls
and library function calls.
* Example programs should be complete, and compile without
warnings when compiled with cc -Wall.
* 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).
* 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!) The following command can be used
to format your source code to something close to the preferred
style:
indent -npro -kr -i4 -ts4 -sob -l72 -ss -nut -psl prog.c
* 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;
* If there is extensive explanatory text before the program
source code, mark off the source code with a subsection
heading Program source, as in:
.SS Program source
Always do this if the explanatory text includes a shell
session log.
If you include a shell session log demonstrating the use of a
program or other system feature:
* Place the session log above the source code listing
* Indent the session log by four spaces.
* Boldface the user input text, to distinguish it from output
produced by the system.
For some examples of what example programs should look like, see
wait(2) and pipe(2).
