OxideBSD
MDOC(7) Miscellaneous Information Manual MDOC(7)

mdoc — semantic markup language for manual pages

The mdoc language describes a manual page by what its parts mean — a flag, an argument, a file name, a cross-reference — rather than by how they look. It is written as roff(7) input: text lines, and macro lines starting with a dot and a macro name. OxideBSD's own manual pages are written in it, and oxdoc(1) formats it.

A macro's arguments are separated by spaces; an argument containing spaces is quoted with double quotes, and a double quote inside one is written twice.

.Sh DESCRIPTION
The
.Nm
utility reads
.Ar file
and writes
.Qq results .

Text lines are filled and adjusted into paragraphs. A sentence should end at the end of an input line, so that it can be followed by two spaces; a new sentence starts on a new line. Blank lines should not be used; paragraphs are separated with Pp.

A page starts with a prologue of three macros and continues with sections, in this order where present:

.Dd Month day, year
.Dt TITLE section [architecture]
.Os [system [version]]
.Sh NAME
.Nm name , name ...
.Nd one-line description
.Sh LIBRARY            (sections 2, 3, 9)
.Sh SYNOPSIS
.Sh DESCRIPTION
.Sh CONTEXT            (section 9)
.Sh IMPLEMENTATION NOTES
.Sh RETURN VALUES      (sections 2, 3, 9)
.Sh ENVIRONMENT
.Sh FILES
.Sh EXIT STATUS        (sections 1, 6, 8)
.Sh EXAMPLES
.Sh DIAGNOSTICS
.Sh ERRORS             (sections 2, 3, 4, 9)
.Sh SEE ALSO
.Sh STANDARDS
.Sh HISTORY
.Sh AUTHORS
.Sh CAVEATS
.Sh BUGS
.Sh SECURITY CONSIDERATIONS

The sections are:

1
General commands.
2
System calls.
3
Library functions.
4
Device drivers.
5
File formats.
6
Games.
7
Miscellaneous information.
8
System administration.
9
Kernel interfaces.

Dd date: month day, year
Dt title: TITLE section [arch]
Os operating system: [system [version]]
Sh section heading
Ss subsection heading
Sx reference to a section or subsection
Pp paragraph break
Nm the name of the page's subject
Nd one-line description, in NAME

Bd, Ed display block: -literal, -filled, -ragged, -unfilled, -centered; -offset width; -compact
D1 indented display of one line
Dl indented literal display of one line
Bl, El list block: -tag, -hang, -ohang, -inset, -diag, -bullet, -dash, -enum, -item, -column; -width width; -offset width; -compact
It list item
Ta column separator in a column list
Bk, Ek keep the words of each line together
Bf, Ef font block: -emphasis, -literal, -symbolic

Fl a command-line flag; each argument gets a dash
Ar a command-line argument; default file ...
Cm a command modifier or keyword
Ic an internal or interactive command
Op an optional part, in brackets
Oo, Oc an optional part spanning lines
Ev an environment variable
Pa a file or directory name
Ex the standard exit status text: -std [utility ...]

Lb a function library
In an include file
Fd a preprocessor directive
Ft a function's type
Fn a function: name [argument ...]
Fo, Fc a function over several lines
Fa a function argument
Vt a variable type
Va a variable name
Dv a defined constant
Er an error constant
Rv the standard return value text: -std [function ...]

Em emphasis
Sy strong emphasis
Li literal text
No normal text inside another macro
Ns no space before the next word
Ap an apostrophe with no space around it
Pf a prefix with no space after it
Dq, Do, Dc double quotes
Sq, So, Sc single quotes
Qq, Qo, Qc typewriter double quotes
Ql quoted literal
Pq, Po, Pc parentheses
Bq, Bo, Bc brackets
braces
Aq, Ao, Ac angle brackets
Eo, Ec enclosure with any characters
Xo, Xc extend a macro's arguments over lines

Xr a cross-reference: name section
Lk a hyperlink: url [text]
Mt an e-mail address
An an author's name; -split, -nosplit
Rs, Re a bibliographic reference, with the fields %A (author), %B (book), %C (city), %D (date), %I (issuer), %J (journal), %N (number), %O (other), %P (pages), %Q (institution), %R (report), %T (title), %U (URL) and %V (volume)
St a standard, such as -p1003.1-2008
At, Bx, Bsx, Dx, Fx, Nx, Ox, Ux AT&T, BSD and other systems, with an optional version

Sm spacing mode: on or off

Macros belong to one of these classes:

Block, full-explicit
Enclose everything up to a closing macro: Bd, Bf, Bk, Bl, Rs.
Block, full-implicit
Enclose everything up to the next macro of the same or a higher level: Sh, Ss, It, Nd, and Nm at the start of a line in SYNOPSIS.
Block, partial-explicit
Enclose the rest of the line and later lines up to a closing macro, which may itself be on the middle of a line: Oo, Do, Xo and the other opening macros above.
Block, partial-implicit
Enclose the rest of their line: Op, Dq, Sq and the other quoting macros, and D1, Dl.
In-line
Format their own arguments: Fl, Ar, Pa and most others.

Most macros are : an argument that is the name of a macro starts that macro, so that ‘.Op -a file’ gives [-a file]. Prefix a word with ‘\&’ to use it literally.

The punctuation characters ‘.’, ‘,’, ‘:’, ‘;’, ‘)’, ‘]’, ‘?’ and ‘!’, given as separate arguments, close a macro: they are printed without a space before them and outside its font. ‘(’ and ‘[’ open: they are printed before the macro, without a space after them. ‘|’ separates, with spaces on both sides. Written as ‘\&.’ they are ordinary words.

A closing ‘.’, ‘?’ or ‘!’ at the end of a macro line ends a sentence, like one at the end of a text line.

man(1), oxdoc(1), eqn(7), man(7), roff(7), tbl(7)

The mdoc language first appeared in 4.4BSD.

The mdoc language was written by Cynthia Livingston. This manual was written for OxideBSD.

September 27, 2026 OxideBSD