mirror of https://github.com/mkerrisk/man-pages
Conventions for writing Linux man-pages.
This commit is contained in:
parent
e7cbacd4af
commit
ba83bc0d89
|
@ -0,0 +1,481 @@
|
|||
.\" (C) Copyright 1992-1999 Rickard E. Faith and David A. Wheeler
|
||||
.\" (faith@cs.unc.edu and dwheeler@ida.org)
|
||||
.\" and (C) Copyright 2007 Michael Kerrisk <mtk-manpages@gmx.net>
|
||||
.\"
|
||||
.\" Permission is granted to make and distribute verbatim copies of this
|
||||
.\" manual provided the copyright notice and this permission notice are
|
||||
.\" preserved on all copies.
|
||||
.\"
|
||||
.\" Permission is granted to copy and distribute modified versions of this
|
||||
.\" manual under the conditions for verbatim copying, provided that the
|
||||
.\" entire resulting derived work is distributed under the terms of a
|
||||
.\" permission notice identical to this one.
|
||||
.\"
|
||||
.\" Since the Linux kernel and libraries are constantly changing, this
|
||||
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
||||
.\" responsibility for errors or omissions, or for damages resulting from
|
||||
.\" the use of the information contained herein. The author(s) may not
|
||||
.\" have taken the same level of care in the production of this manual,
|
||||
.\" which is licensed free of charge, as they might when working
|
||||
.\" professionally.
|
||||
.\"
|
||||
.\" Formatted or processed versions of this manual, if unaccompanied by
|
||||
.\" the source, must acknowledge the copyright and authors of this work.
|
||||
.\"
|
||||
.\" FIXME Add some SEE ALSO references to this page from:
|
||||
.\" man.1, man.7, mdoc.7, and perhaps intro.*
|
||||
.\" Also write up in HOWTOHELP
|
||||
.\"
|
||||
.TH MAN-PAGES 7 2007-05-30 "Linux" "Linux Programmer's Manual"
|
||||
.SH NAME
|
||||
man-pages \- conventions for writing Linux man pages
|
||||
.SH SYNOPSIS
|
||||
.B man
|
||||
.RI [ section ]
|
||||
.I title
|
||||
.SH DESCRIPTION
|
||||
This page describes the conventions that should be employed
|
||||
when writing man pages for the Linux \fIman-pages\fP project,
|
||||
which comprises Sections 2, 3, 4, 5, and 7 of the Linux manual pages.
|
||||
The conventions described on this page may also be useful
|
||||
for authors writing man pages for other projects.
|
||||
.SS Sections of the Manual Pages
|
||||
.PP
|
||||
The manual Sections are traditionally defined as follows:
|
||||
.RS
|
||||
.TP 10
|
||||
.B 1 Commands (Programs)
|
||||
Those commands that can be executed by the user from within
|
||||
a shell.
|
||||
.TP
|
||||
.B 2 System calls
|
||||
Those functions which must be performed by the kernel.
|
||||
.TP
|
||||
.B 3 Library calls
|
||||
Most of the
|
||||
.I libc
|
||||
functions.
|
||||
.TP
|
||||
.B 4 Special files (devices)
|
||||
Files found in
|
||||
.IR /dev .
|
||||
.TP
|
||||
.B 5 File formats and conventions
|
||||
The format for
|
||||
.I /etc/passwd
|
||||
and other human-readable files.
|
||||
.TP
|
||||
.B 6 Games
|
||||
.TP
|
||||
.B 7 Conventions and miscellaneous
|
||||
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.
|
||||
.RE
|
||||
.SS Macro package
|
||||
New manual pages should be marked up using the
|
||||
.B groff tmac.an
|
||||
package described in
|
||||
.BR man (7).
|
||||
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
|
||||
wherever possible.
|
||||
This helps avoid line-wrapping in some mail clients when patches are
|
||||
submitted inline.
|
||||
|
||||
New sentences should be started on new lines.
|
||||
This makes it easier to see the effect of patches,
|
||||
which often operate at the level of individual sentences.
|
||||
.SS Title line
|
||||
The first command in a man page should be a \fBTH\fP command:
|
||||
.RS
|
||||
.sp
|
||||
.B \&.TH
|
||||
.IR "title section date source manual"
|
||||
.sp
|
||||
.RE
|
||||
where:
|
||||
.RS
|
||||
.TP 10
|
||||
.I title
|
||||
The title of the man page, written in all caps (e.g.,
|
||||
.IR MAN-PAGES ).
|
||||
.TP
|
||||
.I section
|
||||
The section number in which the man page should be placed (e.g.,
|
||||
.IR 7 ).
|
||||
.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.
|
||||
Dates should be written in the form YYYY-MM-DD.
|
||||
.TP
|
||||
.I source
|
||||
The source of the command, function, or system call.
|
||||
.sp
|
||||
For those few \fIman-pages\fP pages in Sections 1 and 8,
|
||||
probably you just want to write
|
||||
.IR GNU .
|
||||
.sp
|
||||
For system calls, just write
|
||||
.IR "Linux" .
|
||||
(An earlier practice was to write the version number
|
||||
of the kernel from which the manual page was being written/checked.
|
||||
However, this was never done consistently, and so was
|
||||
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
|
||||
other common GNU libraries, just use
|
||||
.IR "GNU C Library" ", " GNU ,
|
||||
or an empty string.
|
||||
.sp
|
||||
For Section 4 pages, use
|
||||
.IR "Linux" .
|
||||
.sp
|
||||
In cases of doubt, just write
|
||||
.IR Linux ", or " GNU .
|
||||
.TP
|
||||
.I manual
|
||||
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
|
||||
.B highlighted
|
||||
sections.
|
||||
Srrange a new manual page so that sections
|
||||
are placed in the order shown in the list.
|
||||
.in +0.5i
|
||||
.nf
|
||||
|
||||
\fBNAME\fP
|
||||
\fBSYNOPSIS\fP
|
||||
\fBDESCRIPTION\fP
|
||||
OPTIONS [Normally only in Sections 1, 8]
|
||||
EXIT STATUS [Normally only in Sections 1, 8]
|
||||
RETURN VALUE [Normally only in Sections 2, 3]
|
||||
.\" 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,
|
||||
ENVIRONMENT
|
||||
FILES
|
||||
VERSIONS [Normally only in Sections 2, 3]
|
||||
CONFORMING TO
|
||||
NOTES
|
||||
BUGS
|
||||
EXAMPLE
|
||||
.\" AUTHOR sections are discouraged
|
||||
AUTHOR [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
|
||||
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 above sections.
|
||||
.TP 14
|
||||
.B NAME
|
||||
The name of this manual page.
|
||||
See
|
||||
.BR man (7)
|
||||
for important details of the line(s) that should follow the
|
||||
\fB.SH NAME\fI command.
|
||||
.TP
|
||||
.B SYNOPSIS
|
||||
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.
|
||||
Brackets ([]) surround optional arguments, vertical bars (|)
|
||||
separate choices, and ellipses (\&...) can be repeated.
|
||||
For functions, it shows any required data declarations or
|
||||
.B #include
|
||||
directives, followed by the function declaration.
|
||||
.TP
|
||||
.B DESCRIPTION
|
||||
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 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).
|
||||
.TP
|
||||
.B OPTIONS
|
||||
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 EXIT STATUS
|
||||
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 RETURN VALUE
|
||||
For Section 2 and 3 pages, this section gives a
|
||||
list of the values the library routine will return to the caller
|
||||
and the conditions that cause these values to be returned.
|
||||
.TP
|
||||
.B ERRORS
|
||||
For Section 2 and 3 manual pages, this is a list of the
|
||||
values that may be placed in
|
||||
.I errno
|
||||
in the event of an error, along with information about the cause
|
||||
of the errors.
|
||||
.TP
|
||||
.B ENVIRONMENT
|
||||
lists all environment variables that affect the program or function
|
||||
and how they affect it.
|
||||
.TP
|
||||
.B FILES
|
||||
lists the files the program or function uses, such as
|
||||
configuration files, startup files,
|
||||
and files the program directly operates on.
|
||||
Give the full pathname of these files, and use the installation
|
||||
process to modify the directory part to match user preferences.
|
||||
For many programs, the default installation location is in
|
||||
.IR /usr/local ,
|
||||
so your base manual page should use
|
||||
.I /usr/local
|
||||
as the base.
|
||||
.\" 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
|
||||
.\" section).
|
||||
.\" However, please include security information somewhere!
|
||||
.TP
|
||||
.B VERSIONS
|
||||
A brief summary of the Linux kernel or glibc versions where a
|
||||
system call or library function appeared,
|
||||
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.
|
||||
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.
|
||||
For Section 2 and 3 man pages you may find it usful to include
|
||||
subsections (\fBSS\fP) named \fILinux Notes\fP and \fIGlibc Notes\fP.
|
||||
.TP
|
||||
.B BUGS
|
||||
lists limitations, known defects or inconveniences,
|
||||
and other questionable activities.
|
||||
.TP
|
||||
.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.
|
||||
.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".
|
||||
(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
|
||||
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, ordered by section number and
|
||||
alphabetically by name, possibly followed by
|
||||
other related pages or documents.
|
||||
.SS Font conventions
|
||||
.PP
|
||||
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 );
|
||||
.RE
|
||||
.PP
|
||||
Filenames are always in italics (e.g.,
|
||||
.IR "/usr/include/stdio.h" ),
|
||||
except in the SYNOPSIS section, where included files are in bold (e.g.,
|
||||
.BR "#include <stdio.h>" ).
|
||||
.PP
|
||||
Special macros, which are usually in upper case, are in bold (e.g.,
|
||||
.BR MAXINT ).
|
||||
Exception: don't boldface NULL.
|
||||
.PP
|
||||
When enumerating a list of error codes, the codes are in bold (this list
|
||||
usually uses the
|
||||
.B \&.TP
|
||||
macro).
|
||||
.PP
|
||||
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.)
|
||||
.PP
|
||||
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
|
||||
.BR man2html (1)
|
||||
create properly hyperlinked pages.)
|
||||
.SS Example Programs
|
||||
Manual pages can include example programs demonstrating how to
|
||||
use a system call or library function.
|
||||
However, note the following:
|
||||
.TP 3
|
||||
*
|
||||
Example programs should be written in C.
|
||||
.TP
|
||||
*
|
||||
An example program is only necessary and useful if it demonstrates
|
||||
something beyond what can easily be provided in a textual
|
||||
description of the interface.
|
||||
An example program that does nothing
|
||||
other than call an interface usually serves little purpose.
|
||||
.TP
|
||||
*
|
||||
Example programs should be fairly short (preferably < 100 lines;
|
||||
ideally < 50 lines).
|
||||
.TP
|
||||
*
|
||||
Example programs should do error checking after system calls and
|
||||
library function calls.
|
||||
.TP
|
||||
*
|
||||
Example programs should be complete, and compile without
|
||||
warnings when compiled with \fIcc -Wall\fP.
|
||||
.TP
|
||||
*
|
||||
Where possible and appropriate, example programs should allow
|
||||
experimentation, by varying their behaviour based on inputs
|
||||
(ideally from command-line arguments, or alternatively, via
|
||||
input read by the program).
|
||||
.TP
|
||||
*
|
||||
Example programs should be laid out according to Kernighan and
|
||||
Ritchie style, with a few concessions:
|
||||
.RS
|
||||
.TP 3
|
||||
\(bu
|
||||
4-space indents are preferred.
|
||||
(Avoid the use of TAB characters in source code!)
|
||||
.TP
|
||||
\(bu
|
||||
In the interests of keeping a program short, compressing
|
||||
error-handling code such as in the following is acceptable:
|
||||
.nf
|
||||
|
||||
if (func(...) == -1)
|
||||
{ perror("func"); exit(EXIT_FAILURE); }
|
||||
.fi
|
||||
.RE
|
||||
.PP
|
||||
For some examples of what example programs should look like, see
|
||||
.BR wait (2)
|
||||
and
|
||||
.BR pipe (2).
|
||||
.SH EXAMPLE
|
||||
For canonical examples of how man pages in the
|
||||
.BR man-pages
|
||||
package should look, see
|
||||
.BR pipe (2)
|
||||
and
|
||||
.BR fcntl (2).
|
||||
.SH SEE ALSO
|
||||
.BR man (1),
|
||||
.BR man2html (1),
|
||||
.BR man (7),
|
||||
.BR mdoc (7)
|
Loading…
Reference in New Issue