MDOC(7) FreeBSD Miscellaneous Information Manual MDOC(7)
NAME
mdoc -- mdoc language reference
DESCRIPTION
The mdoc language is used to format BSD UNIX manuals. In this reference
document, we describe its syntax, structure, and usage. Our reference
implementation is mandoc(1). The COMPATIBILITY section describes compat-
ibility with groff(1).
An mdoc document follows simple rules: lines beginning with the control
character `'. are parsed for macros. Other lines are interpreted within
the scope of prior macros:
.Sh Macro lines change control state.
Other lines are interpreted within the current state.
LANGUAGE SYNTAX
mdoc documents may contain only graphable 7-bit ASCII characters, the
space character, and, in certain circumstances, the tab character. All
manuals must have UNIX line terminators.
Comments
Text following a `\"', whether in a macro or free-form text line, is
ignored to the end of line. A macro line with only a control character
and comment escape, `.\"', is also ignored. Macro lines with only a con-
trol charater and optionally whitespace are stripped from input.
Reserved Characters
Within a macro line, the following characters are reserved:
. (period)
, (comma)
: (colon)
; (semicolon)
( (left-parenthesis)
) (right-parenthesis)
[ (left-bracket)
] (right-bracket)
? (question)
! (exclamation)
| (vertical bar)
Use of reserved characters is described in MACRO SYNTAX. For general use
in macro lines, these characters must either be escaped with a non-break-
ing space (`\&') or, if applicable, an appropriate escape sequence used.
Special Characters
Special characters may occur in both macro and free-form lines.
Sequences begin with the escape character `\' followed by either an open-
parenthesis `(' for two-character sequences; an open-bracket `[' for n-
character sequences (terminated at a close-bracket `]'); or a single one-
character sequence. See mandoc_char(7) for a complete list. Examples
include `\(em' (em-dash) and `\e' (back-slash).
Text Decoration
Terms may be text-decorated using the `\f' escape followed by an indica-
tor: B (bold), I, (italic), or P and R (Roman, or reset). This form is
not recommended for mdoc, which encourages semantic, not presentation,
annotation.
Predefined Strings
Historically, groff(1) also defined a set of package-specific
``predefined strings'', which, like Special Characters, demark special
output characters and strings by way of input codes. Predefined strings
are escaped with the slash-asterisk, `\*': single-character `\*X', two-
character `\*(XX', and N-character `\*[N]'. See mandoc_char(7) for a
complete list. Examples include `\*(Am' (ampersand) and `\*(Ba'
(vertical bar).
Whitespace
In non-literal free-form lines, consecutive blocks of whitespace are
pruned from input and added later in the output filter, if applicable:
These spaces are pruned from input.
.Bd -literal
These are not.
.Ed
In macro lines, whitespace delimits arguments and is discarded. If argu-
ments are quoted, whitespace within the quotes is retained.
Blank lines are only permitted within literal contexts, as are lines con-
taining only whitespace. Tab characters are only acceptable when delim-
iting `Bl -column' or when in a literal context.
Quotation
Macro arguments may be quoted with a double-quote to group space-delim-
ited terms or to retain blocks of whitespace. A quoted argument begins
with a double-quote preceded by whitespace. The next double-quote not
pair-wise adjacent to another double-quote terminates the literal,
regardless of surrounding whitespace.
This produces tokens `a"', `b c', `de', and `fg"'. Note that any quoted
term, be it argument or macro, is indiscriminately considered literal
text. Thus, the following produces `Em a':
.Em "Em a"
In free-form mode, quotes are regarded as opaque text.
MANUAL STRUCTURE
Each mdoc document must begin with a document prologue, containing, in
order, `Dd', `Dt', and `Os', then the NAME section containing at least
one `Nm' followed by `Nd':
.Dd $Mdocdate$
.Dt mdoc 7
.Os
.
.Sh NAME
.Nm foo
.Nd a description goes here
.\" The next is for sections 2 & 3 only.
.\" .Sh LIBRARY
.
.Sh SYNOPSIS
.Nm foo
.Op Fl options
.Ar
.
.Sh DESCRIPTION
The
.Nm
utility processes files ...
.\" .Sh IMPLEMENTATION NOTES
.\" The next is for sections 1 & 8 only.
.\" .Sh EXIT STATUS
.\" The next is for sections 2, 3, & 9 only.
.\" .Sh RETURN VALUES
.\" The next is for sections 1, 6, 7, & 8 only.
.\" .Sh ENVIRONMENT
.\" .Sh FILES
.\" .Sh EXAMPLES
.\" The next is for sections 1, 4, 6, 7, & 8 only.
.\" .Sh DIAGNOSTICS
.\" The next is for sections 2, 3, & 9 only.
.\" .Sh ERRORS
.\" .Sh SEE ALSO
.\" .Xr foobar 1
.\" .Sh STANDARDS
.\" .Sh HISTORY
.\" .Sh AUTHORS
.\" .Sh CAVEATS
.\" .Sh BUGS
.\" .Sh SECURITY CONSIDERATIONS
Subsequent SYNOPSIS and DESCRIPTION sections are strongly encouraged, but
non-compulsory.
MACRO SYNTAX
Macros are one to three three characters in length and begin with a con-
trol character , `.', at the beginning of the line. An arbitrary amount
of whitespace may sit between the control character and the macro name.
Thus, `.Pp' and `. Pp' are equivalent. Macro names are two or three
characters in length.
The syntax of a macro depends on its classification. In this section,
`-arg' refers to macro arguments, which may be followed by zero or more
`parm' parameters; `Yo' opens the scope of a macro; and if specified,
`Yc' closes it out.
The Callable column indicates that the macro may be called subsequent to
the initial line-macro. If a macro is not callable, then its invocation
after the initial line macro is interpreted as opaque text, such that
`.Fl produces `-
The Parsable column indicates whether the macro may be followed by fur-
ther (ostensibly callable) macros. If a macro is not parsable, subse-
quent macro invocations on the line will be interpreted as opaque text.
The Scope column, if applicable, describes closure rules.
Block full-explicit
Multi-line scope closed by an explicit closing macro. All macros con-
tains bodies; only (`Bf') contains a head.
.Yo [-arg [parm...]] [head...]
[body...]
.Yc
Macro Callable Parsable Scope
Bd No No closed by Ed
Bf No No closed by Ef
Bk No No closed by Ek
Bl No No closed by El
Ed No No opened by Bd
Ef No No opened by Bf
Ek No No opened by Bk
El No No opened by Bl
Block full-implicit
Multi-line scope closed by end-of-file or implicitly by another macro.
All macros have bodies; some (`It -bullet', `-hyphen', `-dash', `-enum',
`-item') don't have heads, while `It -column' may have multiple heads.
.Yo [-arg [parm...]] [head... [Ta head...]]
[body...]
Macro Callable Parsable Scope
It No Yes closed by It, El
Nd No No closed by Sh
Sh No No closed by Sh
Ss No No closed by Sh, Ss
Block partial-explicit
Like block full-explicit, but also with single-line scope. Each has at
least a body and, in limited circumstances, a head (`Fo', `Eo') and/or
tail (`Ec').
.Yo [-arg [parm...]] [head...]
[body...]
.Yc [tail...]
.Yo [-arg [parm...]] [head...] [body...] Yc [tail...]
Macro Callable Parsable Scope
Ac Yes Yes opened by Ao
Ao Yes Yes closed by Ac
Bc Yes Yes closed by Bo
Bo Yes Yes opened by Bc
Brc Yes Yes opened by Bro
Bro Yes Yes closed by Brc
Dc Yes Yes opened by Do
Do Yes Yes closed by Dc
Ec Yes Yes opened by Eo
Eo Yes Yes closed by Ec
Fc Yes Yes opened by Fo
Fo No No closed by Fc
Oc Yes Yes closed by Oo
Oo Yes Yes opened by Oc
Pc Yes Yes closed by Po
Po Yes Yes opened by Pc
Qc Yes Yes opened by Oo
Qo Yes Yes closed by Oc
Re No No opened by Rs
Rs No No closed by Re
Sc Yes Yes opened by So
So Yes Yes closed by Sc
Xc Yes Yes opened by Xo
Xo Yes Yes closed by Xc
Block partial-implicit
Like block full-implicit, but with single-line scope closed by Reserved
Characters or end of line.
.Yo [-arg [val...]] [body...] [res...]
Macro Callable Parsable
Aq Yes Yes
Bq Yes Yes
Brq Yes Yes
D1 No Yes
Dl No Yes
Dq Yes Yes
Op Yes Yes
Pq Yes Yes
Ql Yes Yes
Qq Yes Yes
Sq Yes Yes
In-line
Closed by Reserved Characters, end of line, fixed argument lengths,
and/or subsequent macros. In-line macros have only text children. If a
number (or inequality) of arguments is (n), then the macro accepts an
arbitrary number of arguments.
.Yo [-arg [val...]] [args...] `-res...-'
.Yo [-arg [val...]] [args...] Yc...
.Yo [-arg [val...]] arg0 arg1 argN
Macro Callable Parsable Arguments
%A No No >0
%B No No >0
%C No No >0
%D No No >0
%I No No >0
%J No No >0
%N No No >0
%O No No >0
%P No No >0
%R No No >0
%T No No >0
%V No No >0
Ad Yes Yes n
An Yes Yes n
Ap Yes Yes 0
Ar Yes Yes n
At Yes Yes 1
Bsx Yes Yes n
Bt No No 0
Bx Yes Yes n
Cd Yes Yes >0
Cm Yes Yes n
Db No No 1
Dd No No >0
Dt No No n
Dv Yes Yes n
Dx Yes Yes n
Em Yes Yes >0
En No No 0
Er Yes Yes >0
Es No No 0
Ev Yes Yes n
Ex No No n
Fa Yes Yes n
Fd No No >0
Fl Yes Yes n
Fn Yes Yes >0
Fr No No n
Ft Yes Yes n
Fx Yes Yes n
Hf No No n
Ic Yes Yes >0
In No No n
Lb No No 1
Li Yes Yes n
Lk Yes Yes n
Lp No No 0
Ms Yes Yes >0
Mt Yes Yes >0
Nm Yes Yes n
No Yes Yes 0
Ns Yes Yes 0
Nx Yes Yes n
Os No No n
Ot No No n
Ox Yes Yes n
Pa Yes Yes n
Pf No Yes 1
Pp No No 0
Rv No No n
Sm No No 1
St No Yes 1
Sx Yes Yes >0
Sy Yes Yes >0
Tn Yes Yes >0
Ud No No 0
Ux Yes Yes n
Va Yes Yes n
Vt Yes Yes >0
Xr Yes Yes >0, <3
br No No 0
sp No No 1
COMPATIBILITY
This section documents compatibility with other roff implementations, at
this time limited to groff(1). The term "historic groff" refers to those
versions before the doc.tmac file re-write (somewhere between 1.15 and
1.19).
- The `-split' or `-nosplit' argument to `An' applies to the whole doc-
ument, not just to the current section as it does in groff.
- In quoted literals, groff allowed pair-wise double-quotes to produce
a standalone double-quote in formatted output. This idiosyncratic
behaviour is no longer applicable.
- The `sp' macro does not accept negative numbers.
- Blocks of whitespace are stripped from both macro and free-form text
lines (except when in literal mode), while groff would retain white-
space in free-form text lines.
- Historic groff has many un-callable macros. Most of these (excluding
some block-level macros) are now callable, conforming to the non-his-
toric groff version.
- The vertical bar `|' made historic groff "go orbital" but is a proper
delimiter in this implementation.
- `It -nested' is assumed for all lists (it wasn't in historic groff):
any list may be nested and `-enum' lists will restart the sequence
only for the sub-list.
- `It -column' syntax where column widths may be preceded by other
arguments (instead of proceeded) is not supported.
- The `At' macro only accepts a single parameter.
- Some manuals use `Li' incorrectly by following it with a reserved
character and expecting the delimiter to render. This is not sup-
ported.
- In groff, the `Fo' macro only produces the first parameter. This is
no longer the case.
SEE ALSO
mandoc(1), mandoc_char(7)
AUTHORS
The mdoc reference was written by Kristaps Dzonsons <kristaps@kth.se>.
CAVEATS
There are many ambiguous parts of mdoc.
- `Fa' should be `Va' as function arguments are variables.
- `Ft' should be `Vt' as function return types are still types. Fur-
thermore, the `Ft' should be removed and `Fo', which ostensibly fol-
lows it, should follow the same convention as `Va'.
- `Va' should formalise that only one or two arguments are acceptable:
a variable name and optional, preceding type.
- `Fd' is ambiguous. It's commonly used to indicate an include file in
the synopsis section. `In' should be used, instead.
- Only the `-literal' argument to `Bd' makes sense. The remaining ones
should be removed.
- The `Xo' and `Xc' macros should be deprecated.
- The `Dt' macro lacks clarity. It should be absolutely clear which
title will render when formatting the manual page.
- A `Lx' should be provided for Linux (a la `Ox', `Nx' etc.).
- There's no way to refer to references in `Rs/Re' blocks.
- The -split and -nosplit dictates via `An' are re-set when entering
and leaving the AUTHORS section.
FreeBSD 7.2 May 24, 2012 FreeBSD 7.2
NAME - DESCRIPTION - LANGUAGE SYNTAX - MANUAL STRUCTURE - MACRO SYNTAX -
COMPATIBILITY - SEE ALSO - AUTHORS - CAVEATS -
|