mirror of https://github.com/mkerrisk/man-pages
Substantial rewrite, revising and extending the discussion
about desired conventions for writing pages.
This commit is contained in:
Michael Kerrisk
parent
4a9af89a33
commit
226ae424f9
193
man7/man.7
193
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
|
||||
.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
|
||||
|
|
|
|||
Loading…
Reference in New Issue