Optional Sections

As discussed previously, a section is begun by the Sh macro and continues until the end of file or another section.

.Sh SECTION NAME
Text and macros within the section.

What follows is a description of each optional section. An optional section is not required for a well-formed manual, but may be necessary for a manual of a given type. For example, the EXIT STATUS section is not required, but is necessary for utilities.

IMPLEMENTATION NOTES

For components describing an algorithm, or implementing a generic interface, it's at time useful to document the implementation itself. As this is not relevant to the calling syntax or description of a component, this is relegated to the IMPLEMENTATION NOTES section.

Consider a simple sorting function, mysort.

.Sh SYNOPSIS
.In mysort.h
.Ft void
.Fn mysort "int *input"
.Sh DESCRIPTION
The
.Fn mysort
function in-place sorts an integer array
.Fa input .
.Sh IMPLEMENTATION NOTES
The
.Fn mysort
function uses a bubble-sort algorithm for sorting and thus operates in
O(n^2) time with respect to input size.
Since swapping is in-place, a constant number of allocations occur.

In general, IMPLEMENTATION NOTES is not used, and is thus rarely found in UNIX manuals.

RETURN VALUES

Manuals describing functions (categories 2, 3, and 9) must use the RETURN VALUES section to document each function's return value. If a manual documents functions in a language without return values, or functions do not return a value, they need not use this section.

System calls (category 2) usually employ the Rv macro to stipulate a standard return value statement.

.Sh RETURN VALUES
.Rv -std

Note that the std flag is a required argument to Rv, for historical reasons.

For non-system functions, be as brief as possible.

.Sh RETURN VALUES
The
.Fn hello
function returns zero on success and non-zero on failure.

ENVIRONMENT

Both commands and functions may be affected by UNIX environmental variables. These must be documented in the ENVIRONMENT section of the manual. Each variable should be listed as a Ev along with its effect on the component.

.Sh ENVIRONMENT
.Bl -tag -width Ds
.It Ev TZ
The time zone for when displaying dates.
.El

Some historical manuals use ENVIRONMENT VARIABLES instead of ENVIRONMENT.

FILES

Both commands and functions may also be affected by files, although this is mainly the purview of commands. These files should be listed in the FILES section in a tagged list.

.Sh FILES
.Bl -tag -width Ds
.It Pa ~/.profile
User's login profile.
.El

EXIT STATUS

This section is the dual of RETURN VALUES for commands in categories 1, 6, and 8. It documents the exit status of commands.

If your utility exits with zero on success and greater than zero on failure (the standard for most utilities), use the Ex macro.

.Sh EXIT STATUS
.Ex -std

More complex commands should document all possible exit status.

EXAMPLES

In many situations of casual use, the EXAMPLES section is the first visited in a manual. It should consist of concise, documented examples of the most common uses of your component.

For commands, the EXAMPLES section should contain a handful of common use cases. In general, these should consist of standalone invocations and, if the input and output correspond to other utilities, invocations as part of a pipeline.

Although the hello example is almost too trivial for documentation, consider if it were used to greet new users to a Unix system. Thus, a common example would be the following:

.Sh EXAMPLES
The following sends a greeting message to the new user
.Qq joe .
.Pp
.Dl $ hello \(dqDear Joe, \(dq \(bv mail -s \(dqHi!\(dq joe

The Dl, used for one-line literal displays, is a common macro in the EXAMPLES section. For multi-line displays, use the Bd literal environment, usually with a default indentation with offset indent.

.Sh EXAMPLES
The following sends a greeting message to the new user
.Qq joe .
.Bd -literal -offset indent
$ hello \(dqDear Joe, \(dq \(bv \e
  mail -s \(dqHi!\(dq joe
.Ed

For functions and function libraries, it's more common to include a single, thorough source example than individual examples for each function. These always use the Bd literal display environment and an indentation.

.Sh EXAMPLES
The following is a simple utility interfacing with the
.Nm
library:
.Bd -literal -offset indent
#include <stdlib.h>
#include "hello.h"
 
int
main(int argc, char *argv[]) {
  hello(0, argc > r ? argv[1] : NULL);
  return(EXIT_SUCCESS);
}
.Ed

Use terse syntax for your example, without error checking for functions not being documented, e.g., open or scanf.

Some manuals will use the vS and vE macros around source code. These are not mdoc and should be avoided in portable manuals.

DIAGNOSTICS

If your component emits regular debug, status, error, or warning messages, document the syntax of these messages in DIAGNOSTICS.

Some historic manuals document function return values in this section, but modern practise is to do in RETURN VALUES or, if setting the error constant of the C library, ERRORS.

The Bl diag lists are most often used for documenting emitted messages.

.Sh DIAGNOSTICS
.Bl -diag
.It "%file:%line:%col: %msg[: %extra]"
An error occured when processing
.Cm %file
at line and column
.Cm %line
and
.Cm %col ,
respectively.
The error message
.Cm %msg
may be followed by additional debugging information in
.Cm %extra .
.El

ERRORS

This section is used exclusively by functions that set or return a regular error code. The most common use is for system calls (category two) setting error constants in the C library. In either case, this section should consist of a single list documenting all possible error codes. In the latter case, each error should be labelled within the Er macro.

SEE ALSO

This section consists of cross-references to other manuals or literature. It is a standard section in most UNIX manuals. Any components referenced in your manual should be duplicated here along with any other bibliographic texts.

For UNIX manual cross-references, use the Xr macro. These should be specified in a list ordered first by section, then by name. Non-terminal references should be comma-separated.

.Sh SEE ALSO
.Xr mandoc 1 ,
.Xr mandoc 3 ,
.Xr man 7 ,
.Xr mdoc 7

If your manual references other documents or literature, you may include them in this section within a bibliographic reference as well. The Rs block is used for bibliographic references. These should be specified after any UNIX manual cross-references.

.Sh SEE ALSO
.Xr mandoc 1 ,
.Xr mandoc 3 ,
.Xr man 7 ,
.Xr mdoc 7
.Rs
.%A Brian W. Kernighan
.%A Lorinda L. Cherry
.%T System for Typesetting Mathematics
.%J Communications of the ACM
.%V 18
.%P 151\(en157
.%D March, 1975
.Re

Bibliographic references should be ordered by document title. Advanced references will be covered later in this book.

STANDARDS

If your component references any standards literature, it should be mentioned here. Most standards (e.g., POSIX, ANSI, etc.) may be semantically noted with the St macro. When implementing standardised wire protocols, references to RFC and other literature should also be mentioned here. These differ from referenced standards in terms of being implemented versus referred.

.Sh STANDARDS
The
.Nm
utility is compliant with the
.St -xpg4
specification.

If your component consists of deviations from a given standard, they should be mentioned in this section as well. Some historic manuals use a special COMPATIBILITY section for this, but this is discouraged unless when discussing compatibility with non-standard but common utilities.

This section has also been referred to as CONFORMING TO on some GNU/Linux manuals.

HISTORY

Some components have a historical basis: this should be included here. Keep this information terse and, above all, correct.

If your manual includes prior implementations of your component, for example, it's common to include the dates and developers of those prior implementations.

AUTHORS

Another standard section for UNIX manuals is the AUTHORS section, which should always mention the current contact for the utility. The traditional text for this section is as follows.

.Sh AUTHORS
The
.Nm
reference was written by
.An Joe Foo Aq joe@example.com .

However, in as e-mail addresses are a ubiquitous form of contact, it's considered good practise to use the correct semantic notation.

.Sh AUTHORS
The
.Nm
reference was written by
.An Joe Foo ,
.Mt joe@example.com .

The term reference in this fragment should reflect the content of the manual.

CAVEATS

The CAVEATS section is not often used. It consists of text relevant to unexpected (but unchangeable) behaviour of the component.

BUGS

If the component has known bugs, they should be listed here. In some historic manuals, authors used this section to list no bugs present; however, this text can be misleading for machine-readers of manuals and should be avoided in new manuals.

SECURITY CONSIDERATIONS

The SECURITY CONSIDERATIONS section is reserved for components whose deployment may be sensitive to security conditions, such as network daemons. It should include suggestions on security measures beyond the scope of the component.

This section was historically called SECURITY.

Last edited by $Author: kristaps $ on $Date: 2012/01/01 15:13:33 $. Copyright © 2011, Kristaps Dzonsons. CC BY-SA.