man.bsd.lv manual page server

Manual Page Search Parameters

MDOC(7) Miscellaneous Information Manual MDOC(7)

mdocsemantic markup language for formatting manual pages

The mdoc language supports authoring of manual pages for the man(1) utility by allowing semantic annotations of words, phrases, page sections and complete manual pages. Such annotations are used by formatting tools to achieve a uniform presentation across all manuals written in mdoc, and to support hyperlinking if supported by the output medium.

This reference document describes the structure of manual pages and the syntax and usage of the mdoc language. The reference implementation of a parsing and formatting tool is mandoc(1); the COMPATIBILITY section describes compatibility with other implementations.

In an mdoc document, lines beginning with the control character ‘.’ are called “macro lines”. The first word is the macro name. It consists of two or three letters. Most macro names begin with a capital letter. For a list of available macros, see MACRO OVERVIEW. The words following the macro name are arguments to the macro, optionally including the names of other, callable macros; see MACRO SYNTAX for details.

Lines not beginning with the control character are called “text lines”. They provide free-form text to be printed; the formatting of the text depends on the respective processing context:

.Sh Macro lines change control state.
Text lines are interpreted within the current state.

Many aspects of the basic syntax of the mdoc language are based on the roff(7) language; see the and sections in the roff(7) manual for details, in particular regarding comments, escape sequences, whitespace, and quoting. However, using roff(7) requests in mdoc documents is discouraged; mandoc(1) supports some of them merely for backward compatibility.

A well-formed mdoc document consists of a document prologue followed by one or more sections.

The prologue, which consists of the Dd, Dt, and Os macros in that order, is required for every document.

The first section (sections are denoted by Sh) must be the NAME section, consisting of at least one Nm followed by Nd.

Following that, convention dictates specifying at least the SYNOPSIS and DESCRIPTION sections, although this varies between manual sections.

The following is a well-formed skeleton mdoc file for a utility "progname":

.Dd $Mdocdate$
.Dt PROGNAME section
.Os
.Sh NAME
.Nm progname
.Nd one line about what it does
.\" .Sh LIBRARY
.\" For sections 2, 3, and 9 only.
.\" Not used in OpenBSD.
.Sh SYNOPSIS
.Nm progname
.Op Fl options
.Ar
.Sh DESCRIPTION
The
.Nm
utility processes files ...
.\" .Sh CONTEXT
.\" For section 9 functions only.
.\" .Sh IMPLEMENTATION NOTES
.\" Not used in OpenBSD.
.\" .Sh RETURN VALUES
.\" For sections 2, 3, and 9 function return values only.
.\" .Sh ENVIRONMENT
.\" For sections 1, 6, 7, and 8 only.
.\" .Sh FILES
.\" .Sh EXIT STATUS
.\" For sections 1, 6, and 8 only.
.\" .Sh EXAMPLES
.\" .Sh DIAGNOSTICS
.\" For sections 1, 4, 6, 7, 8, and 9 printf/stderr messages only.
.\" .Sh ERRORS
.\" For sections 2, 3, 4, and 9 errno settings only.
.\" .Sh SEE ALSO
.\" .Xr foobar 1
.\" .Sh STANDARDS
.\" .Sh HISTORY
.\" .Sh AUTHORS
.\" .Sh CAVEATS
.\" .Sh BUGS
.\" .Sh SECURITY CONSIDERATIONS
.\" Not used in OpenBSD.

The sections in an mdoc document are conventionally ordered as they appear above. Sections should be composed as follows:

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.

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:
.Lb libarm

See Lb.

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.

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.

This section lists the contexts in which functions can be called in section 9. The contexts are autoconf, process, or interrupt.
Implementation-specific notes should be kept here. This is useful when implementing standard functions that may have side effects or notable algorithmic implications.
This section documents the return values of functions in sections 2, 3, and 9.

See Rv.

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.

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.

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.

Example usages. This often contains snippets of well-formed, well-tested invocations. Make sure that examples work properly!
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.

Documents errno(2) settings in sections 2, 3, 4, and 9.

See Er.

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.

References any standards implemented or used. If not adhering to any standards, the HISTORY section should be used instead.

See St.

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

Common misuses and misunderstandings should be explained in this section.
Known bugs, limitations, and work-arounds should be described in this section.
Documents any security precautions that operators should consider.

This overview is sorted such that macros of similar purpose are listed together, to help find the best macro for any given purpose. Deprecated macros are not included in the overview, but can be found below in the alphabetical MACRO REFERENCE.

Dd document date: $Mdocdate$ | month day, year
Dt document title: TITLE section [arch]
Os operating system version: [system [version]]
Nm document name (one argument)
Nd document description (one line)

Sh section header (one line)
Ss subsection header (one line)
Sx internal cross reference to a section or subsection
Xr cross reference to another manual page: name section
Tg tag the definition of a term (<= 1 arguments)
Pp start a text paragraph (no arguments)

Bd, Ed display block: -type [-offset width] [-compact]
D1 indented display (one line)
Dl indented literal display (one line)
Ql in-line literal display: ‘text
Bl, El list block: -type [-width val] [-offset val] [-compact]
It list item (syntax depends on -type)
Ta table cell separator in Bl -column lists
Rs, %*, Re bibliographic block (references)

Pf prefix, no following horizontal space (one argument)
Ns roman font, no preceding horizontal space (no arguments)
Ap apostrophe without surrounding whitespace (no arguments)
Sm switch horizontal spacing mode: [on | off]
Bk, Ek keep block: -words

Nm start a SYNOPSIS block with the name of a utility
Fl command line options (flags) (>=0 arguments)
Cm command modifier (>0 arguments)
Ar command arguments (>=0 arguments)
Op, Oo, Oc optional syntax elements (enclosure)
Ic internal or interactive command (>0 arguments)
Ev environmental variable (>0 arguments)
Pa file system path (>=0 arguments)

Lb function library (one argument)
In include file (one argument)
Fd other preprocessor directive (>0 arguments)
Ft function type (>0 arguments)
Fo, Fc function block: funcname
Fn function name: funcname [argument ...]
Fa function argument (>0 arguments)
Vt variable type (>0 arguments)
Va variable name (>0 arguments)
Dv defined variable or preprocessor constant (>0 arguments)
Er error constant (>0 arguments)
Ev environmental variable (>0 arguments)

An author name (>0 arguments)
Lk hyperlink: uri [display_name]
Mt “mailto” hyperlink: localpart@domain
Cd kernel configuration declaration (>0 arguments)
Ad memory address (>0 arguments)
Ms mathematical symbol (>0 arguments)

Em italic font or underline (emphasis) (>0 arguments)
Sy boldface font (symbolic) (>0 arguments)
No return to roman font (normal) (>0 arguments)
Bf, Ef font block: -type | Em | Li | Sy

Dq, Do, Dc enclose in typographic double quotes: “text”
Qq, Qo, Qc enclose in typewriter double quotes: "text"
Sq, So, Sc enclose in single quotes: ‘text’
Pq, Po, Pc enclose in parentheses: (text)
Bq, Bo, Bc enclose in square brackets: [text]
Brq, Bro, Brc enclose in curly braces: {text}
Aq, Ao, Ac enclose in angle brackets: ⟨text⟩
Eo, Ec generic enclosure

Ex -std standard command exit values: [utility ...]
Rv -std standard function return values: [function ...]
St reference to a standards document (one argument)
At AT&T UNIX
Bx BSD
Bsx BSD/OS
Nx NetBSD
Fx FreeBSD
Ox OpenBSD
Dx DragonFly

This section is a canonical reference of all macros, arranged alphabetically. For the scoping of individual macros, see MACRO SYNTAX.

first_name ... last_name
Author name of an Rs block. Multiple authors should each be accorded their own %A line. Author names should be ordered with full or abbreviated forename(s) first, then full surname.
title
Book title of an Rs block. This macro may also be used in a non-bibliographic context when referring to book titles.
location
Publication city or location of an Rs block.
[month day,] year
Publication date of an Rs block. Provide the full English name of the month and all four digits of the year.
name
Publisher or issuer name of an Rs block.
name
Journal name of an Rs block.
number
Issue number (usually for journals) of an Rs block.
line
Optional information of an Rs block.
number
Book or journal page number of an Rs block. Conventionally, the argument starts with ‘p.’ for a single page or ‘pp.’ for a range of pages, for example:

.%P pp. 42\(en47
name
Institutional author (school, government, etc.) of an Rs block. Multiple institutional authors should each be accorded their own %Q line.
name
Technical report name of an Rs block.
title
Article title of an Rs block. This macro may also be used in a non-bibliographical context when referring to article titles.
protocol://path
URI of reference document.
number
Volume number of an Rs block.
Close an Ao block. Does not have any tail arguments.
Memory address. Do not use this for postal addresses.

Examples:

.Ad [0,$]
.Ad 0x00000000
An -split | | first_name ... last_name
Author name. Can be used both for the authors of the program, function, or driver documented in the manual, or for the authors of the manual itself. Requires either the name of an author or one of the following arguments:

Start a new output line before each subsequent invocation of An.
The opposite of -split.

The default is -nosplit. The effect of selecting either of the -split modes ends at the beginning of the AUTHORS section. In the AUTHORS section, the default is -nosplit for the first author listing and -split for all other author listings.

Examples:

.An -nosplit
.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
block
Begin a block enclosed by angle brackets. Does not have any head arguments. This macro is almost never useful. See Aq for more details.
Ap
Inserts an apostrophe without any surrounding whitespace. This is generally used as a grammatical device when referring to the verb form of a function.

Examples:

.Fn execve Ap d
Aq line
Enclose the rest of the input line in angle brackets. The only important use case is for email addresses. See Mt for an example.

Occasionally, it is used for names of characters and keys, for example:

Press the
.Aq escape
key to ...

For URIs, use Lk instead, and In for “#include” directives. Never wrap Ar in Aq.

Since Aq usually renders with non-ASCII characters in non-ASCII output modes, do not use it where the ASCII characters ‘<’ and ‘>’ are required as syntax elements. Instead, use these characters directly in such cases, combining them with the macros Pf, Ns, or Eo as needed.

See also Ao.

Ar [placeholder ...]
Command arguments. If an argument is not provided, the string “file ...” is used as a default.

Examples:

.Fl o Ar file
.Ar
.Ar arg1 , arg2 .

The arguments to the Ar macro are names and placeholders for command arguments; for fixed strings to be passed verbatim as arguments, use Fl or Cm.

At [version]
Formats an AT&T UNIX version. Accepts one optional argument:

|
A version of AT&T UNIX.
AT&T System III UNIX.
|
A version of AT&T System V UNIX.

Note that these arguments do not begin with a hyphen.

Examples:

.At
.At III
.At V.1

See also Bsx, Bx, Dx, Fx, Nx, and Ox.

Close a Bo block. Does not have any tail arguments.
Bd -type [-offset width] [-compact]
Begin a display block. Display blocks are used to select a different indentation and justification than the one used by the surrounding text. They may contain both macro lines and text lines. By default, a display block is preceded by a vertical space.

The type must be one of the following:

Produce one output line from each input line, and center-justify each line. Using this display type is not recommended; many mdoc implementations render it poorly.
Change the positions of line breaks to fill each line, and left- and right-justify the resulting block.
Produce one output line from each input line, and do not justify the block at all. Preserve white space as it appears in the input. Always use a constant-width font. Use this for displaying source code.
Change the positions of line breaks to fill each line, and left-justify the resulting block.
The same as -literal, but using the same font as for normal text, which is a variable width font if supported by the output device.

The type must be provided first. Additional arguments may follow:

width
Indent the display by the width, which may be one of the following:
  • One of the pre-defined strings indent, the width of a standard indentation (six constant width characters); indent-two, twice indent; left,