Optional Sections

As discussed previously, a section is begun by the Sh macro and continues until the end of file or another 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.

.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

.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

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

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.

.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.