Substantial rewrite, revising and extending the discussion

about desired conventions for writing pages.

man7/man.7

@@ -25,7 +25,7 @@
 .\" Modified Sat Jun  8 00:39:52 1996 by aeb
 .\" Modified Wed Jun 16 23:00:00 1999 by David A. Wheeler (dwheeler@ida.org)
 .\" Modified Thu Jul 15 12:43:28 1999 by aeb
-.\"  [todo: split this into man.7 describing the macros
+.\" FIXME split this page into two parts: man.7 describing the macros
 .\"   and manpage.7 describing the Linux man page conventions]
 .\" Modified Sun Jan  6 18:26:25 2002 by Martin Schulze <joey@infodrom.org>
 .\" Modified Tue Jul 27 20:12:02 2004 by Colin Watson <cjwatson@debian.org>
@@ -121,7 +121,7 @@ command.
 The manual sections are traditionally defined as follows:
 .RS
 .TP 10
-.B 1 Commands
+.B 1 Commands (Programs)
 Those commands that can be executed by the user from within
 a shell.
 .TP
@@ -131,10 +131,9 @@ Those functions which must be performed by the kernel.
 .B 3 Library calls
 Most of the
 .I libc
-functions, such as
+functions.
-.BR qsort (3).
 .TP
-.B 4 Special files
+.B 4 Special files (devices)
 Files found in
 .IR /dev .
 .TP
@@ -146,21 +145,21 @@ and other human-readable files.
 .B 6 Games
 .TP
 .B 7 Conventions and miscellaneous
-A description of the standard file system layout, network protocols,
+Overviews of various topics, conventions and protocols,
-ASCII and other character codes, this man page, and other things.
+character set standards, and miscellaneous other things.
 .TP
 .B 8 System management commands
 Commands like
 .BR mount (8),
 many of which only root can execute.
-.TP
+.\" .TP
-.B 9 Kernel routines
+.\" .B 9 Kernel routines
-This is an obsolete manual section.
+.\" This is an obsolete manual section.
-Once it was thought a good idea to document the Linux kernel here,
+.\" Once it was thought a good idea to document the Linux kernel here,
-but in fact very little has been documented, and the documentation
+.\" but in fact very little has been documented, and the documentation
-that exists is outdated already.
+.\" that exists is outdated already.
-There are better sources of
+.\" There are better sources of
-information for kernel developers.
+.\" information for kernel developers.
 .RE
 .SH SECTIONS
 Sections are started with
@@ -171,17 +170,47 @@ followed by the heading name.
 .\" on the same line as
 .\" .BR \&.SH ,
 .\" then place the heading in double quotes.
-Traditional or suggested
+The list below shows conventional or suggested sewctions.
-headings include:
+Most manual pages should include at least the 
-NAME, SYNOPSIS, DESCRIPTION, RETURN VALUE,
+.B highlighted
-EXIT STATUS, ERROR HANDLING, ERRORS,
+sections.
-OPTIONS, USAGE, EXAMPLES, FILES, ENVIRONMENT, DIAGNOSTICS, SECURITY,
+Please try to arrange a new manual page so that sections
-CONFORMING TO, NOTES, BUGS, AUTHOR, and SEE ALSO.
+are placed in approximately the order shown in the list.
-Where a traditional heading would apply, please use it;
+.in +0.5i
+.nf
+
+\fBNAME\fP
+\fBSYNOPSIS\fP
+\fBDESCRIPTION\fP
+OPTIONS            [Normally only in sections 1, 8]
+ENVIRONMENT
+FILES
+RETURN VALUE       [Normally only in sections 2, 3]
+EXIT STATUS        [Normally only in sections 1, 8]
+.\" May 07: Few current man pages have an ERROR HANDLING section,,,
+.\" ERROR HANDLING,
+ERRORS             [Typically only in sections 2, 3]
+.\" May 07: Almost no current man pages have a USAGE section,,,
+.\" USAGE, 
+..\" DIAGNOSTICS, 
+.\" May 07: Almost no current man pages have a SECURITY section,,,
+.\" SECURITY,
+CONFORMING TO
+NOTES
+BUGS
+.\" AUTHOR sections are discouraged
+.\" AUTHOR, 
+EXAMPLE
+\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.
-However, feel free to create your own headings if they make things easier
+If you really feel it necessary, you cann create your own 
-to understand.
+headings if they make things easier to understand (this can
-The only required heading is NAME, which should be the first section and
+be especially useful for pages in sections 4 and 5).
+The only mandatory heading is NAME, which should be the first section and
 be followed on the next line by a one line description of the program:
 .RS
 .sp
@@ -215,20 +244,21 @@ For functions, it shows any required data declarations or
 directives, followed by the function declaration.
 .TP
 .B DESCRIPTION
-gives an explanation of what the command, function, or format does.
+gives 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
 understanding the interface.
-Describe the usual case; for information on options use the
+Describe the usual case;
+for information on command-line options of a program use the
 .B OPTIONS
 section.
-If there is some kind of input grammar or complex set of subcommands,
+.\" If there is some kind of input grammar or complex set of subcommands,
-consider describing them in a separate
+.\" consider describing them in a separate
-.B USAGE
+.\" .B USAGE
-section (and just place an overview in the
+.\" section (and just place an overview in the
-.B DESCRIPTION
+.\" .B DESCRIPTION
-section).
+.\" section).
 .TP
 .B RETURN VALUE
 gives a
@@ -236,20 +266,22 @@ list of the values the library routine will return to the caller
 and the conditions that cause these values to be returned.
 .TP
 .B EXIT STATUS
-lists the possible exit status values or a program and
+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.
 .TP
 .B OPTIONS
-describes the options accepted by the program and how they change
+describes the command-line options accepted by a 
-its behavior.
+program and how they change its behavior.
-.TP
+This section should only appear for Section 1 and 8 manual pages.
-.B USAGE
+.\" .TP
-describes the grammar of any sublanguage this implements.
+.\" .B USAGE
+.\" describes the grammar of any sublanguage this implements.
 .\" FIXME document VERSIONS
 .\" FIXME document other common Section Heading types
 .\" FIXME make a clear statement about the order of Sections
 .TP
-.B EXAMPLES
+.B EXAMPLE
 provides one or more examples describing how this function, file or
 command is used.
 .TP
@@ -266,24 +298,27 @@ so your base manual page should use
 as the base.
 .TP
 .B ENVIRONMENT
-lists all environment variables that affect your program or function
+lists all environment variables that affect the program or function
 and how they affect it.
-.TP
+.\" May 07: Almost no current man pages have a DIAGNOSTICS section;
-.B DIAGNOSTICS
+.\"         "RETURN VALUE" or "EXIT STATUS" is preferred.
-gives an overview of the most common error messages and how to
+.\" .TP
-cope with them.
+.\" .B DIAGNOSTICS
-You don't need to explain system error messages
+.\" gives an overview of the most common error messages and how to
-or fatal signals that can appear during execution of any program
+.\" cope with them.
-unless they're special in some way to your program.
+.\" You don't need to explain system error messages
-.TP
+.\" or fatal signals that can appear during execution of any program
-.B SECURITY
+.\" unless they're special in some way to the program.
-discusses security issues and implications.
+.\" May 07: Almost no current man pages have a SECURITY section.
-Warn about configurations or environments that should be avoided,
+.\".TP
-commands that may have security implications, and so on, especially
+.\".B SECURITY
-if they aren't obvious.
+.\"discusses security issues and implications.
-Discussing security in a separate section isn't necessary;
+.\"Warn about configurations or environments that should be avoided,
-if it's easier to understand, place security information in the
+.\"commands that may have security implications, and so on, especially
-other sections (such as the
+.\"if they aren't obvious.
+.\"Discussing security in a separate section isn't necessary;
+.\"if it's easier to understand, place security information in the
+.\"other sections (such as the
 .B DESCRIPTION
 or
 .B USAGE
@@ -303,6 +338,13 @@ and other questionable activities.
 .B AUTHOR
 lists authors of the documentation or program so you can mail in bug
 reports.
+.IR "Use of an AUTHOR section is discouraged".
+(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 list
+of (over time potentially numerous) authors;
+if you write or significantly amend a page,
+add a copyright notice as a comment in the source file.
 .TP
 .B SEE ALSO
 lists related man pages in alphabetical order, possibly followed by
@@ -316,8 +358,9 @@ font standards:
 For functions, the arguments are always specified using italics,
 .IR "even in the SYNOPSIS section" ,
 where the rest of the function is specified in bold:
+.PP
 .RS
-.BI "int myfunction(int " argc ", char **" argv );
+.BI "    int myfunction(int " argc ", char **" argv );
 .RE
 .IP
 Filenames are always in italics (e.g.,
@@ -333,11 +376,35 @@ usually uses the
 .B \&.TP
 macro).
 .IP
-Any reference to another man page (or to the subject of the current man
+Any reference to the subject of the current manual page
-page) is in bold.
+should be written with the name in bold,
-If the manual section number is given, it is given in
+followed by a pair of parentheses in Roman (normal) font,
-Roman (normal) font, without any spaces (e.g.,
+e.g.,
-.BR man (7)).
+.BR man ().
+The preferred way to write this in the source file is:
+.nf
+
+    .BR man ()
+
+.fi
+(Using this format, rather than the use of "\\fB...\\fP()"
+makes it easier to write tools that parse man page source files.)
+.IP
+Any reference to another man page
+should be written with the name in bold,
+\fIalways\fP followed by the section number,
+formatted in Roman (normal) font, without any
+separating spaces (e.g.,
+.BR intro (2)).
+The preferred way to write this in the source file is:
+.nf
+
+    .BR intro (2)
+
+.fi
+(Including the section number in cross references lets tools like
+.B man2html
+create properly hyperlinked pages.)
 .LP
 The commands to select the type face are:
 .TP 4