.\" 2007-05-30 created by mtk, using text from old man.7 plus
.\" rewrites and additional text.
.\"
-.TH MAN-PAGES 7 2014-03-16 "Linux" "Linux Programmer's Manual"
+.TH MAN-PAGES 7 2014-12-31 "Linux" "Linux Programmer's Manual"
.SH NAME
man-pages \- conventions for writing Linux man pages
.SH SYNOPSIS
.IR 7 ).
.TP
.I date
-The date of the last revision\(emremember to change this every time a
-nontrivial change is made to the man page.
+The date of the last nontrivial change that was made to the man page.
+(Within the
+.I man-pages
+project, the necessary updates to these timetamps are handled
+automatically by scripts, so there is no need to manually update
+them as part of a patch.)
Dates should be written in the form YYYY-MM-DD.
.TP
.I source
.TP 14
.B NAME
The name of this manual page.
+
See
.BR man (7)
for important details of the line(s) that should follow the
dictates otherwise.
.TP
.B SYNOPSIS
-briefly describes the command or function's interface.
+A brief summary of the command or function's interface.
+
For commands, this shows the syntax of the command and its arguments
(including options);
boldface is used for as-is text and italics are used to
.TP
.B CONFIGURATION
Configuration details for a device.
+
This section normally appears only in Section 4 pages.
.TP
.B DESCRIPTION
-gives an explanation of what the program, function, or format does.
+An explanation of what the program, function, or format does.
+
Discuss how it interacts with files and standard input, and what it
produces on standard output or standard error.
Omit internals and implementation details unless they're critical for
(which is typical in embedded systems, for example).
.TP
.B OPTIONS
-describes the command-line options accepted by a
+A description of the command-line options accepted by a
program and how they change its behavior.
+
This section should appear only for Section 1 and 8 manual pages.
.\" .TP
.\" .B USAGE
.\" describes the grammar of any sublanguage this implements.
.TP
.B EXIT STATUS
-lists the possible exit status values of a program and
+A list of the possible exit status values of a program and
the conditions that cause these values to be returned.
+
This section should appear only for Section 1 and 8 manual pages.
.TP
.B RETURN VALUE
.I errno
in the event of an error, along with information about the cause
of the errors.
+
.IR "The error list should be in alphabetical order" .
.TP
.B ENVIRONMENT
-lists all environment variables that affect the program or function
+A list of all environment variables that affect the program or function
and how they affect it.
.TP
.B FILES
-lists the files the program or function uses, such as
+A list of the files the program or function uses, such as
configuration files, startup files,
and files the program directly operates on.
+
Give the full pathname of these files, and use the installation
process to modify the directory part to match user preferences.
For many programs, the default installation location is in
.B ATTRIBUTES
A summary of various attributes of the function(s) documented on this page,
broken into subsections.
+
The following subsections are defined:
.sp
.RS
A brief summary of the Linux kernel or glibc versions where a
system call or library function appeared,
or changed significantly in its operation.
+
As a general rule, every new interface should
include a VERSIONS section in its manual page.
Unfortunately,
in which various system calls first appeared.
.TP
.B CONFORMING TO
-describes any standards or conventions that relate to the function
+A description of 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,
or the SVr4 and 4.xBSD implementation standards,
unless the call was specified in those standards,
but isn't in the current version of POSIX.1.)
-(See
-.BR standards (7).)
If the call is not governed by any standards but commonly
exists on other systems, note them.
terminate the list with a period (\(aq.\(aq).
.TP
.B NOTES
-provides miscellaneous notes.
+Miscellaneous notes.
+
For Section 2 and 3 man pages you may find it useful to include
subsections (\fBSS\fP) named \fILinux Notes\fP and \fIGlibc Notes\fP.
+
+In Section 2, use the heading
+.I "C library/kernel ABI differences"
+to mark off notes that describe the differences (if any) between
+the C library wrapper function for a system call and
+the raw system call interface provided by the kernel.
.TP
.B BUGS
-lists limitations, known defects or inconveniences,
+A list of limitations, known defects or inconveniences,
and other questionable activities.
.TP
.B EXAMPLE
-provides one or more examples describing how this function, file or
+One or more examples demonstrating how this function, file or
command is used.
+
For details on writing example programs,
see \fIExample Programs\fP below.
.TP
.B AUTHORS
-lists authors of the documentation or program.
+A list of authors of the documentation or program.
+
\fBUse of an AUTHORS section is strongly discouraged\fP.
Generally, it is better not to clutter every page with a list
of (over time potentially numerous) authors;
an address for reporting bugs, place this under the BUGS section.
.TP
.B SEE ALSO
-provides a comma-separated list of related man pages,
-ordered by section number and
-then alphabetically by name, possibly followed by
+A comma-separated list of related man pages, possibly followed by
other related pages or documents.
-Do not terminate this with a period.
+
+The list should be ordered by section number and
+then alphabetically by name
+Do not terminate this list with a period.
.IP
Where the SEE ALSO list contains many long manual page names,
to improve the visual result of the output, it may be useful to employ the
directives.
Hyphenation of individual page names can be prevented
by preceding words with the string "\\%".
+
+Given the distributed, autonomous nature of FOSS projects
+and their documentation, it is sometimes necessary\(emand in many cases
+desirable\(emthat the SEE ALSO section includes references to
+manual pages provided by other projects.
.SH STYLE GUIDE
The following subsections describe the preferred style for the
.IR man-pages
.BR man (7),
.BR mdoc (7)
.SH COLOPHON
-This page is part of release 3.68 of the Linux
+This page is part of release 3.79 of the Linux
.I man-pages
project.
A description of the project,
OSDN Git Service
