diff --git a/man7/man.7 b/man7/man.7 index 54ef0113f..f121eff32 100644 --- a/man7/man.7 +++ b/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 .\" Modified Tue Jul 27 20:12:02 2004 by Colin Watson @@ -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 -.BR qsort (3). +functions. .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, -ASCII and other character codes, this man page, and other things. +Overviews of various topics, conventions and protocols, +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 -.B 9 Kernel routines -This is an obsolete manual section. -Once it was thought a good idea to document the Linux kernel here, -but in fact very little has been documented, and the documentation -that exists is outdated already. -There are better sources of -information for kernel developers. +.\" .TP +.\" .B 9 Kernel routines +.\" This is an obsolete manual section. +.\" Once it was thought a good idea to document the Linux kernel here, +.\" but in fact very little has been documented, and the documentation +.\" that exists is outdated already. +.\" There are better sources of +.\" 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 -headings include: -NAME, SYNOPSIS, DESCRIPTION, RETURN VALUE, -EXIT STATUS, ERROR HANDLING, ERRORS, -OPTIONS, USAGE, EXAMPLES, FILES, ENVIRONMENT, DIAGNOSTICS, SECURITY, -CONFORMING TO, NOTES, BUGS, AUTHOR, and SEE ALSO. -Where a traditional heading would apply, please use it; +The list below shows conventional or suggested sewctions. +Most manual pages should include at least the +.B highlighted +sections. +Please try to arrange a new manual page so that sections +are placed in approximately the order shown in the list. +.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 -to understand. -The only required heading is NAME, which should be the first section and +If you really feel it necessary, you cann create your own +headings if they make things easier to understand (this can +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, -consider describing them in a separate -.B USAGE -section (and just place an overview in the -.B DESCRIPTION -section). +.\" If there is some kind of input grammar or complex set of subcommands, +.\" consider describing them in a separate +.\" .B USAGE +.\" section (and just place an overview in the +.\" .B DESCRIPTION +.\" 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 -its behavior. -.TP -.B USAGE -describes the grammar of any sublanguage this implements. +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 +.\" .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 -.B DIAGNOSTICS -gives an overview of the most common error messages and how to -cope with them. -You don't need to explain system error messages -or fatal signals that can appear during execution of any program -unless they're special in some way to your program. -.TP -.B SECURITY -discusses security issues and implications. -Warn about configurations or environments that should be avoided, -commands that may have security implications, and so on, especially -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 +.\" May 07: Almost no current man pages have a DIAGNOSTICS section; +.\" "RETURN VALUE" or "EXIT STATUS" is preferred. +.\" .TP +.\" .B DIAGNOSTICS +.\" gives an overview of the most common error messages and how to +.\" cope with them. +.\" You don't need to explain system error messages +.\" or fatal signals that can appear during execution of any program +.\" unless they're special in some way to the program. +.\" May 07: Almost no current man pages have a SECURITY section. +.\".TP +.\".B SECURITY +.\"discusses security issues and implications. +.\"Warn about configurations or environments that should be avoided, +.\"commands that may have security implications, and so on, especially +.\"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 -page) is in bold. -If the manual section number is given, it is given in -Roman (normal) font, without any spaces (e.g., -.BR man (7)). +Any reference to the subject of the current manual page +should be written with the name in bold, +followed by a pair of parentheses in Roman (normal) font, +e.g., +.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