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.
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.
In general, IMPLEMENTATION NOTES is not used, and is thus rarely found in UNIX manuals.
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.
Note that the std flag is a required argument to Rv, for historical reasons.
For non-system functions, be as brief as possible.
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.
Some historical manuals use ENVIRONMENT VARIABLES instead of ENVIRONMENT.
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.
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.
More complex commands should document all possible exit status.
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:
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.
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.
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.
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.
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.
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.
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.
Bibliographic references should be ordered by document title. Advanced references will be covered later in this book.
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.
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.
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.
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.
However, in as e-mail addresses are a ubiquitous form of contact, it's considered good practise to use the correct semantic notation.
The term reference in this fragment should reflect the content of the manual.
The CAVEATS section is not often used. It consists of text relevant to unexpected (but unchangeable) behaviour of the component.
If the component has known bugs, they should be listed here. In some historic manuals, authors used this section to
no bugs present; however, this text can be misleading for machine-readers of manuals and should be avoided
in new manuals.
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.