.\"
.\" 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
+.\" rewrites and additional text.
.\"
.TH MAN-PAGES 7 2007-05-30 "Linux" "Linux Programmer's Manual"
.SH NAME
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 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.
.TP
.I date
The date of the last revision\(emremember to change this every time a
-change is made to the man page, since this is the most general way of doing
-version control.
+change is made to the man page,
+since this is the most general way of doing version control.
Dates should be written in the form YYYY-MM-DD.
.TP
.I source
Most manual pages should include at least the
.B highlighted
sections.
-Srrange a new manual page so that sections
+Arrange a new manual page so that sections
are placed in the order shown in the list.
.in +0.5i
.nf
BUGS
EXAMPLE
.\" AUTHOR sections are discouraged
-AUTHOR [Discouraged]
+.\" AUTHOR [Discouraged]
\fBSEE ALSO\fP
.fi
briefly describes 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 indicate replaceable
-arguments.
+boldface is used for as-is text and italics are used to
+indicate replaceable arguments.
Brackets ([]) surround optional arguments, vertical bars (|)
separate choices, and ellipses (\&...) can be repeated.
For functions, it shows any required data declarations or
or changed significantly in its operation.
.TP
.B CONFORMING TO
-describes any standards or conventions that relate to the function or command described by the manula page.
-For a page in Section 2 or 3, this section should note the POSIX.1
-version(s) that the call conforms to.
-If the call is not governed by any standards but exists on other
-systems, note them.
+describes any standards or conventions that relate to the function
+or command described by the manual page.
+For a page in Section 2 or 3,
+this section should note the POSIX.1
+version(s) that the call conforms to,
+and also whether the call is specified in C99.
+(Don't worry too much about other standards like SUS, SUSv2, and XPG,
+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 Linux specific, note this.
-When talking about standards and systems
-here is probably no need to talk about anything more than
-C89, C99, POSIX.1-2001 (or later), xBSD, and SVr4, and perhaps Solaris
-(see
-.BR standards (7)).
.TP
.B NOTES
provides miscellaneous notes.
.B EXAMPLE
provides one or more examples describing how this function, file or
command is used.
-For details on writing example programs, see \fIExample Programs\fP below.
+For details on writing example programs,
+see \fIExample Programs\fP below.
.TP
.B AUTHOR
lists authors of the documentation or program so you can mail in bug
reports.
-.BR "Use of an AUTHOR section is discouraged for pages in
-the \fIman-pages\fP package".
+\fBUse of an AUTHOR section is discouraged\fP for pages in
+the \fIman-pages\fP package.
(One exception is Section 4 pages that list the authors of
device drivers, to whom software bugs should be sent.)
Generally, it is better not to clutter every page with a list