.\" (faith@cs.unc.edu and dwheeler@ida.org)
.\" and (C) Copyright 2007 Michael Kerrisk <mtk.manpages@gmail.com>
.\"
+.\" %%%LICENSE_START(VERBATIM)
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
+.\" %%%LICENSE_END
.\"
.\" 2007-05-30 created by mtk, using text from old man.7 plus
.\" rewrites and additional text.
.\"
-.TH MAN-PAGES 7 2008-10-28 "Linux" "Linux Programmer's Manual"
+.TH MAN-PAGES 7 2013-02-24 "Linux" "Linux Programmer's Manual"
.SH NAME
man-pages \- conventions for writing Linux man pages
.SH SYNOPSIS
.SH DESCRIPTION
This page describes the conventions that should be employed
when writing man pages for the Linux \fIman-pages\fP project,
-which comprises Sections 2, 3, 4, 5, and 7 of the Linux manual pages.
+which documents the user-space API provided by the Linux kernel
+and the GNU C library.
+The project thus provides most of the pages in Section 2,
+as well as many of the pages that appear
+in Sections 3, 4, 5, and 7 of the man pages on a Linux system.
The conventions described on this page may also be useful
for authors writing man pages for other projects.
-.SS Sections of the Manual Pages
+.SS Sections of the manual pages
.PP
The manual Sections are traditionally defined as follows:
.TP 10
.TP
.B 6 Games
.TP
-.B 7 Conventions and miscellaneous
+.B 7 Overview, conventions, and miscellaneous
Overviews of various topics, conventions and protocols,
character set standards, and miscellaneous other things.
.TP
.BR man (7)
for important details of the line(s) that should follow the
\fB.SH NAME\fP command.
+All words in this line (including the word immediately
+following the "\\\-") should be in lowercase,
+except where English or technical terminological convention
+dictates otherwise.
.TP
.B SYNOPSIS
briefly describes the command or function's interface.
.TP
.B CONFIGURATION
Configuration details for a device.
-This section normally only appears in Section 4 pages.
+This section normally appears only in Section 4 pages.
.TP
.B DESCRIPTION
gives an explanation of what the program, function, or format does.
.B OPTIONS
describes the command-line options accepted by a
program and how they change its behavior.
-This section should only appear for Section 1 and 8 manual pages.
+This section should appear only for Section 1 and 8 manual pages.
.\" .TP
.\" .B USAGE
.\" describes the grammar of any sublanguage this implements.
.B EXIT STATUS
lists the possible exit status values of a program and
the conditions that cause these values to be returned.
-This section should only appear for Section 1 and 8 manual pages.
+This section should appear only for Section 1 and 8 manual pages.
.TP
.B RETURN VALUE
For Section 2 and 3 pages, this section gives a
(since there was no policy to do so when they were written).
Patches to remedy this are welcome,
but, from the perspective of programmers writing new code,
-this information probably only matters in the case of kernel
+this information probably matters only in the case of kernel
interfaces that have been added in Linux 2.4 or later
(i.e., changes since kernel 2.2),
and library functions that have been added to glibc since version 2.1
then alphabetically by name, possibly followed by
other related pages or documents.
Do not terminate this 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
+.I .ad l
+(don't right justify)
+and
+.I .nh
+(don't hyphenate)
+directives.
+Hyphenation of individual page names can be prevented
+by preceding words with the string "\\%".
.SS Font conventions
.PP
For functions, the arguments are always specified using italics,
.I man-pages
follows American spelling conventions;
please write all new pages and patches according to these conventions.
-.SS Example Programs and Shell Sessions
+.SS Capitalization
+In subsection ("SS") headings
+capitalize the first word in 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 Example programs and shell sessions
Manual pages can include example programs demonstrating how to
use a system call or library function.
However, note the following:
Example programs should be written in C.
.TP
*
-An example program is only necessary and useful if it demonstrates
+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
OSDN Git Service
