OSDN Git Service
(root)
/
linuxjm
/
LDP_man-pages.git
/ blobdiff
commit
grep
author
committer
pickaxe
?
search:
re
summary
|
shortlog
|
log
|
commit
|
commitdiff
|
tree
raw
|
inline
| side by side
LDP: Update original to LDP v3.79
[linuxjm/LDP_man-pages.git]
/
original
/
man7
/
man-pages.7
diff --git
a/original/man7/man-pages.7
b/original/man7/man-pages.7
index
e9a0e94
..
bf0a3ea
100644
(file)
--- a/
original/man7/man-pages.7
+++ b/
original/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.
.\"
.\" 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
.SH NAME
man-pages \- conventions for writing Linux man pages
.SH SYNOPSIS
@@
-125,8
+125,12
@@
The section number in which the man page should be placed (e.g.,
.IR 7 ).
.TP
.I date
.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
Dates should be written in the form YYYY-MM-DD.
.TP
.I source
@@
-213,6
+217,7
@@
the above sections.
.TP 14
.B NAME
The name of this manual page.
.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
See
.BR man (7)
for important details of the line(s) that should follow the
@@
-223,7
+228,8
@@
except where English or technical terminological convention
dictates otherwise.
.TP
.B SYNOPSIS
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
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
@@
-242,10
+248,12
@@
then the SYNOPSIS should indicate this, as described in
.TP
.B CONFIGURATION
Configuration details for a device.
.TP
.B CONFIGURATION
Configuration details for a device.
+
This section normally appears only in Section 4 pages.
.TP
.B DESCRIPTION
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
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
@@
-274,21
+282,23
@@
list, in the following form (here, for a new system call flag):
Description of flag...
.RE
.IP
Description of flag...
.RE
.IP
-Including version information is
especially useful to users
+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
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
+
A description of
the command-line options accepted by a
program and how they change its behavior.
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
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.
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
This section should appear only for Section 1 and 8 manual pages.
.TP
.B RETURN VALUE
@@
-302,16
+312,18
@@
values that may be placed in
.I errno
in the event of an error, along with information about the cause
of the errors.
.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
.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
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.
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
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
@@
-348,6
+360,7
@@
as the base.
.B ATTRIBUTES
A summary of various attributes of the function(s) documented on this page,
broken into subsections.
.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
The following subsections are defined:
.sp
.RS
@@
-371,6
+384,7
@@
Details of these attributes can be found in
A brief summary of the Linux kernel or glibc versions where a
system call or library function appeared,
or changed significantly in its operation.
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,
As a general rule, every new interface should
include a VERSIONS section in its manual page.
Unfortunately,
@@
-390,11
+404,13
@@
manual page also provides information about kernel versions
in which various system calls first appeared.
.TP
.B CONFORMING TO
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.
or command described by the manual page.
+
The preferred terms to use for the various standards are listed as
headings in
.BR standards (7).
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,
For a page in Section 2 or 3,
this section should note the POSIX.1
version(s) that the call conforms to,
@@
-403,8
+419,6
@@
and also whether the call is specified in C99.
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.)
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.
If the call is not governed by any standards but commonly
exists on other systems, note them.
@@
-415,22
+429,31
@@
If this section consists of just a list of standards
terminate the list with a period (\(aq.\(aq).
.TP
.B NOTES
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.
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
.TP
.B BUGS
-
lists
limitations, known defects or inconveniences,
+
A list of
limitations, known defects or inconveniences,
and other questionable activities.
.TP
.B EXAMPLE
and other questionable activities.
.TP
.B EXAMPLE
-
provides one or more examples describ
ing how this function, file or
+
One or more examples demonstrat
ing how this function, file or
command is used.
command is used.
+
For details on writing example programs,
see \fIExample Programs\fP below.
.TP
.B AUTHORS
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;
\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;
@@
-440,11
+463,12
@@
If you are the author of a device driver and want to include
an address for reporting bugs, place this under the BUGS section.
.TP
.B SEE ALSO
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.
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
.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
@@
-456,6
+480,11
@@
and
directives.
Hyphenation of individual page names can be prevented
by preceding words with the string "\\%".
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
.SH STYLE GUIDE
The following subsections describe the preferred style for the
.IR man-pages
@@
-857,7
+886,7
@@
Avoid using the following forms to terminate a program:
.IP *
If there is extensive explanatory text before the
program source code, mark off the source code
.IP *
If there is extensive explanatory text before the
program source code, mark off the source code
-with a su
s
bsection heading
+with a subsection heading
.IR "Program source" ,
as in:
.IR "Program source" ,
as in:
@@
-894,10
+923,11
@@
and
.BR man (7),
.BR mdoc (7)
.SH COLOPHON
.BR man (7),
.BR mdoc (7)
.SH COLOPHON
-This page is part of release 3.
65
of the Linux
+This page is part of release 3.
79
of the Linux
.I man-pages
project.
A description of the project,
.I man-pages
project.
A description of the project,
-and information about reporting bugs,
+information about reporting bugs,
+and the latest version of this page,
can be found at
\%http://www.kernel.org/doc/man\-pages/.
can be found at
\%http://www.kernel.org/doc/man\-pages/.