Each
man document must contain the
TH macro describing the document's section and title. It may occur anywhere in the document, although conventionally it appears as the first macro.
Beyond
TH, at least one macro or text node must appear in the document. Documents are generally structured as follows:
.TH FOO 1 2009-10-10
.SH NAME
\fBfoo\fR \(en a description goes here
.\" The next is for sections 2 & 3 only.
.\" .SH LIBRARY
.SH SYNOPSIS
\fBfoo\fR [\fB\-options\fR] arguments...
.SH DESCRIPTION
The \fBfoo\fR utility processes files...
.\" .SH IMPLEMENTATION NOTES
.\" The next is for sections 2, 3, & 9 only.
.\" .SH RETURN VALUES
.\" The next is for sections 1, 6, 7, & 8 only.
.\" .SH ENVIRONMENT
.\" .SH FILES
.\" The next is for sections 1 & 8 only.
.\" .SH EXIT STATUS
.\" .SH EXAMPLES
.\" The next is for sections 1, 4, 6, 7, & 8 only.
.\" .SH DIAGNOSTICS
.\" The next is for sections 2, 3, & 9 only.
.\" .SH ERRORS
.\" .SH SEE ALSO
.\" .BR foo ( 1 )
.\" .SH STANDARDS
.\" .SH HISTORY
.\" .SH AUTHORS
.\" .SH CAVEATS
.\" .SH BUGS
.\" .SH SECURITY CONSIDERATIONS
The sections in a
man document are conventionally ordered as they appear above. Sections should be composed as follows:
NAME
The name(s) and a short description of the documented material. The syntax for this is generally as follows:
\fBname\fR \(en description
LIBRARY
The name of the library containing the documented material, which is assumed to be a function in a section 2 or 3 manual. For functions in the C library, this may be as follows:
Standard C Library (libc, -lc)
SYNOPSIS
Documents the utility invocation syntax, function call syntax, or device configuration.
For the first, utilities (sections 1, 6, and 8), this is generally structured as follows:
\fBname\fR [-\fBab\fR] [-\fBc\fR\fIarg\fR] \fBpath\fR...
For the second, function calls (sections 2, 3, 9):
.B char *name(char *\fIarg\fR);
And for the third, configurations (section 4):
.B name* at cardbus? function?
Manuals not in these sections generally don't need a
SYNOPSIS.
DESCRIPTION
This expands upon the brief, one-line description in NAME. It usually contains a break-down of the options (if documenting a command).
IMPLEMENTATION NOTES
Implementation-specific notes should be kept here. This is useful when implementing standard functions that may have side effects or notable algorithmic implications.
RETURN VALUES
This section documents the return values of functions in sections 2, 3, and 9.
ENVIRONMENT
Documents any usages of environment variables, e.g.,
environ(7).
FILES
Documents files used. It's helpful to document both the file name and a short description of how the file is used (created, modified, etc.).
EXIT STATUS
This section documents the command exit status for section 1, 6, and 8 utilities. Historically, this information was described in DIAGNOSTICS, a practise that is now discouraged.
EXAMPLES
Example usages. This often contains snippets of well-formed, well-tested invocations. Make sure that examples work properly!
DIAGNOSTICS
Documents error conditions. This is most useful in section 4 manuals. Historically, this section was used in place of EXIT STATUS for manuals in sections 1, 6, and 8; however, this practise is discouraged.
ERRORS
Documents error handling in sections 2, 3, and 9.
SEE ALSO
References other manuals with related topics. This section should exist for most manuals.
.BR bar ( 1 ),
Cross-references should conventionally be ordered first by section, then alphabetically.
STANDARDS
References any standards implemented or used, such as
IEEE Std 1003.2 (\(lqPOSIX.2\(rq)
If not adhering to any standards, the
HISTORY section should be used.
HISTORY
The history of any manual without a STANDARDS section should be described in this section.
AUTHORS
Credits to authors, if applicable, should appear in this section. Authors should generally be noted by both name and email address.
CAVEATS
Common misuses and misunderstandings should be explained in this section.
BUGS
Known bugs, limitations, and work-arounds should be described in this section.
SECURITY CONSIDERATIONS
Documents any security precautions that operators should consider.