.\"
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
-.\"
-.\" 2007-05-30 created by mtk, using text from old man.7 plus
+.\"
+.\" 2007-05-30 created by mtk, using text from old man.7 plus
.\" rewrites and additional text.
.\"
.TH MAN-PAGES 7 2007-05-30 "Linux" "Linux Programmer's Manual"
.B groff tmac.an
package described in
.BR man (7).
-This choice is mainly for consistency: the vast majority of
+This choice is mainly for consistency: the vast majority of
existing Linux manual pages are marked up using these macros.
.SS Conventions for source file layout
-Please limit source code line length to no more than about 75 characters
+Please limit source code line length to no more than about 75 characters
wherever possible.
This helps avoid line-wrapping in some mail clients when patches are
submitted inline.
probably worse than including no version number.
Henceforth, avoid including a version number.)
.sp
-For library calls that are part of glibc or one of the
+For library calls that are part of glibc or one of the
other common GNU libraries, just use
.IR "GNU C Library" ", " GNU ,
or an empty string.
.IR Linux ", or " GNU .
.TP
.I manual
-The title of the manual (e.g., for Section 2 and 3 pages in
+The title of the manual (e.g., for Section 2 and 3 pages in
the \fIman-pages\fP package, use
.IR "Linux Programmer's Manual" ).
.RE
.SS Sections within a manual page
The list below shows conventional or suggested sections.
-Most manual pages should include at least the
+Most manual pages should include at least the
.B highlighted
sections.
Arrange a new manual page so that sections
.\" ERROR HANDLING,
ERRORS [Typically only in Sections 2, 3]
.\" May 07: Almost no current man pages have a USAGE section,,,
-.\" USAGE,
-..\" DIAGNOSTICS,
+.\" USAGE,
+..\" DIAGNOSTICS,
.\" May 07: Almost no current man pages have a SECURITY section,,,
.\" SECURITY,
ENVIRONMENT
NOTES
BUGS
EXAMPLE
-.\" AUTHOR sections are discouraged
-.\" AUTHOR [Discouraged]
+.\" AUTHORS sections are discouraged
+.\" AUTHORS [Discouraged]
\fBSEE ALSO\fP
.fi
.in
.IR "Where a traditional heading would apply" ", " "please use it" ;
this kind of consistency can make the information easier to understand.
-If you must, you can create your own
+If you must, you can create your own
headings if they make things easier to understand (this can
be especially useful for pages in Sections 4 and 5).
However, before doing this, consider whether you could use the
traditional headings, with some subsections (\fI.SS\fP) within
those sections.
-The following list elaborates on the contents of each of
+The following list elaborates on the contents of each of
the above sections.
.TP 14
.B NAME
The name of this manual page.
-See
+See
.BR man (7)
for important details of the line(s) that should follow the
\fB.SH NAME\fI command.
.\" section).
.TP
.B OPTIONS
-describes the command-line options accepted by a
+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.
.\" .TP
(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.
If the call is Linux specific, note this.
.TP
.B NOTES
For details on writing example programs,
see \fIExample Programs\fP below.
.TP
-.B AUTHOR
+.B AUTHORS
lists authors of the documentation or program.
-\fBUse of an AUTHOR section is discouraged\fP.
+\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;
if you write or significantly amend a page,
an address for reporting bugs, place this under the BUGS section.
.TP
.B SEE ALSO
-lists related man pages, ordered by section number and
+lists related man pages, ordered by section number and
alphabetically by name, possibly followed by
other related pages or documents.
.SS Font conventions
Any reference to the subject of the current manual page
should be written with the name in bold.
If the subject is a function (i.e., this is a Section 2 or 3 page),
-then the name should be followed by a pair of parentheses
+then the name should be followed by a pair of parentheses
in Roman (normal) font.
For example, in the
.BR fcntl (2)
(Including the section number in cross references lets tools like
.BR man2html (1)
create properly hyperlinked pages.)
+.SS Spelling
+Starting with release 2.59,
+.I man-pages
+follows American spelling conventions;
+please write all new pages and patches according to these conventions.
.SS Example Programs
-Manual pages can include example programs demonstrating how to
+Manual pages can include example programs demonstrating how to
use a system call or library function.
However, note the following:
.TP 3
projects / thirdparty / man-pages.git / blobdiff