NAME
The name(s) and a one line description of the documented material. The syntax for this as follows:
.Nm name0 ,
.Nm name1 ,
.Nm name2
.Nd a one line description
Multiple ‘Nm’ names should be separated by commas.
The Nm macro(s) must precede the Nd macro.
See Nm and Nd.
LIBRARY
The name of the library containing the documented material, which is assumed to be a function in a section 2, 3, or 9 manual. The syntax for this is as follows:
See Lb.
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:
.Nm bar
.Op Fl v
.Op Fl o Ar file
.Op Ar
.Nm foo
.Op Fl v
.Op Fl o Ar file
.Op Ar
Commands should be ordered alphabetically.
For the second, function calls (sections 2, 3, 9):
.In header.h
.Vt extern const char *global;
.Ft "char *"
.Fn foo "const char *src"
.Ft "char *"
.Fn bar "const char *src"
Ordering of In, Vt, Fn, and Fo macros should follow C header-file conventions.
And for the third, configurations (section 4):
.Cd "it* at isa? port 0x2e"
.Cd "it* at isa? port 0x4e"
Manuals not in these sections generally don't need a SYNOPSIS.
Some macros are displayed differently in the SYNOPSIS section, particularly Nm, Cd, Fd, Fn, Fo, In, Vt, and Ft. All of these macros are output on their own line. If two such dissimilar macros are pairwise invoked (except for Ft before Fo or Fn), they are separated by a vertical space, unless in the case of Fo, Fn, and Ft, which are always separated by vertical space.
When text and macros following an Nm macro starting an input line span multiple output lines, all output lines but the first will be indented to align with the text immediately following the Nm macro, up to the next Nm, Sh, or Ss macro or the end of an enclosing block, whichever comes first.
DESCRIPTION
This begins with an expansion of the brief, one line description in NAME:
The
.Nm
utility does this, that, and the other.
It usually follows with a breakdown of the options (if documenting a command), such as:
The options are as follows:
.Bl -tag -width Ds
.It Fl v
Print verbose information.
.El
List the options in alphabetical order, uppercase before lowercase for each letter and with no regard to whether an option takes an argument. Put digits in ascending order before all letter options.
Manuals not documenting a command won't include the above fragment.
Since the DESCRIPTION section usually contains most of the text of a manual, longer manuals often use the Ss macro to form subsections. In very long manuals, the DESCRIPTION may be split into multiple sections, each started by an Sh macro followed by a non-standard section name, and each having several subsections, like in the present mdoc manual.
CONTEXT
This section lists the contexts in which functions can be called in section 9. The contexts are autoconf, process, or interrupt.
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.
See Rv.
ENVIRONMENT
Lists the environment variables used by the utility, and explains the syntax and semantics of their values. The environ(7) manual provides examples of typical content and formatting.
See Ev.
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.).
See Pa.
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.
See Ex.
EXAMPLES
Example usages. This often contains snippets of well-formed, well-tested invocations. Make sure that examples work properly!
DIAGNOSTICS
Documents error messages. In section 4 and 9 manuals, these are usually messages printed by the kernel to the console and to the kernel log. In section 1, 6, 7, and 8, these are usually messages printed by userland programs to the standard error output.
Historically, this section was used in place of EXIT STATUS for manuals in sections 1, 6, and 8; however, this practise is discouraged.
See Bl -diag.
ERRORS
Documents errno(2) settings in sections 2, 3, 4, and 9.
See Er.
SEE ALSO
References other manuals with related topics. This section should exist for most manuals. Cross-references should conventionally be ordered first by section, then alphabetically (ignoring case).
References to other documentation concerning the topic of the manual page, for example authoritative books or journal articles, may also be provided in this section.
See Rs and Xr.
STANDARDS
References any standards implemented or used. If not adhering to any standards, the HISTORY section should be used instead.
See St.
HISTORY
A brief history of the subject, including where it was first implemented, and when it was ported to or reimplemented for the operating system at hand.
AUTHORS
Credits to the person or persons who wrote the code and/or documentation. Authors should generally be noted by both name and email address.
See An.
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.