-.\" $Id: mdoc.7,v 1.10 2009/03/20 15:14:01 kristaps Exp $
+.\" $Id: mdoc.7,v 1.94 2010/04/13 05:26:49 kristaps Exp $
.\"
-.\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@openbsd.org>
+.\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@bsd.lv>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
-.\" purpose with or without fee is hereby granted, provided that the
-.\" above copyright notice and this permission notice appear in all
-.\" copies.
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
.\"
-.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
-.\" WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
-.\" WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
-.\" AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
-.\" DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
-.\" PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
-.\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
-.\" PERFORMANCE OF THIS SOFTWARE.
-.\"
-.Dd $Mdocdate: March 20 2009 $
-.Dt mdoc 7
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $Mdocdate: April 13 2010 $
+.Dt MDOC 7
.Os
-.\" SECTION
.Sh NAME
.Nm mdoc
-.Nd mdoc macro reference
-.\" SECTION
+.Nd mdoc language reference
.Sh DESCRIPTION
The
.Nm mdoc
-language is used to format
-.Bx
+language is used to format
+.Bx
.Ux
-manuals. An
+manuals. In this reference document, we describe its syntax, structure,
+and usage. Our reference implementation is mandoc; the
+.Sx COMPATIBILITY
+section describes compatibility with other troff \-mdoc implementations.
+.Pp
+An
.Nm
document follows simple rules: lines beginning with the control
character
.Sq \.
are parsed for macros. Other lines are interpreted within the scope of
-prior macros. This document describes the encoding, ontology and syntax
-of these macros.
-.\" SECTION
-.Sh CHARACTER ENCODING
+prior macros:
+.Bd -literal -offset indent
+\&.Sh Macro lines change control state.
+Other lines are interpreted within the current state.
+.Ed
+.Sh LANGUAGE SYNTAX
.Nm
-documents may contain only printable characters, the space character
-.Sq \ ,
-and, in certain circumstances, the tab character
-.Sq \et .
-All manuals must have
-.Sq \en
-line termination.
-.Pp
-The only time a blank line is acceptable is within
-the context of
-.Sq \&Bd \-literal
-or
-.Sq \&Bd \-unfilled .
-.Pp
-Tab characters
-.Pq \et
-are only acceptable when delimiting
-.Sq \&Bl \-column
-and in
-.Sq \&Bd \-literal
-or
-.Sq \&Bd \-unfilled
-contexts.
-.\" SUB-SECTION
+documents may contain only graphable 7-bit ASCII characters, the space
+character, and, in certain circumstances, the tab character. All
+manuals must have
+.Ux
+line terminators.
+.Ss Comments
+Text following a
+.Sq \e" ,
+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,
+.Sq \&.\e" ,
+is also ignored. Macro lines with only a control charater and optionally
+whitespace are stripped from input.
.Ss Reserved Characters
Within a macro line, the following characters are reserved:
-.Bl -tag -width 12n -offset XXXX -compact
+.Pp
+.Bl -tag -width Ds -offset indent -compact
.It \&.
.Pq period
.It \&,
.It \&?
.Pq question
.It \&!
-.Pq exclamation
+.Pq exclamation
+.It \&|
+.Pq vertical bar
.El
-.\" PARAGRAPH
.Pp
Use of reserved characters is described in
-.Sx Closure .
-For general non-reserved use, characters must either be escaped with a
-non-breaking space
+.Sx MACRO SYNTAX .
+For general use in macro lines, these characters must either be escaped
+with a non-breaking space
.Pq Sq \e&
-or, if applicable, an appropriate escape-sequence used.
-.\" SUB-SECTION
+or, if applicable, an appropriate escape sequence used.
.Ss Special Characters
-Special character sequences begin with the escape character
-.Sq \\
-followed by either an open-parenthesis
+Special characters may occur in both macro and free-form lines.
+Sequences begin with the escape character
+.Sq \e
+followed by either an open-parenthesis
.Sq \&(
for two-character sequences; an open-bracket
.Sq \&[
for n-character sequences (terminated at a close-bracket
.Sq \&] ) ;
-or a single one-character sequence.
+or a single one-character sequence. See
+.Xr mandoc_char 7
+for a complete list. Examples include
+.Sq \e(em
+.Pq em-dash
+and
+.Sq \ee
+.Pq back-slash .
+.Ss Text Decoration
+Terms may be text-decorated using the
+.Sq \ef
+escape followed by an indicator: B (bold), I, (italic), R (Roman), or P
+(revert to previous mode):
.Pp
-Characters may alternatively be escaped by a slash-asterisk,
-.Sq \\* ,
-with the same combinations as described above. This form is deprecated.
+.D1 \efBbold\efR \efIitalic\efP
.Pp
-The following is a table of all available escapes.
+A numerical representation 3, 2, or 1 (bold, italic, and Roman,
+respectively) may be used instead. A text decoration is valid within
+the current font scope only: if a macro opens a font scope alongside
+its own scope, such as
+.Sx \&Bf
+.Cm \&Sy ,
+in-scope invocations of
+.Sq \ef
+are only valid within the font scope of the macro. If
+.Sq \ef
+is specified outside of any font scope, such as in unenclosed, free-form
+text, it will affect the remainder of the document.
.Pp
-Grammatic:
-.Bl -tag -width 12n -offset "XXXX" -compact
-.It \\(em
-.Pq em-dash
-.It \\(en
-.Pq en-dash
-.It \e-
-.Pq hyphen
-.It \\\\
-.Pq back-slash
-.It \e'
-.Pq apostrophe
-.It \e`
-.Pq back-tick
-.It \\
-.Pq space
-.It \\.
-.Pq period
-.It \\(r!
-.Pq upside-down exclamation
-.It \\(r?
-.Pq upside-down question
-.El
-.\" PARAGRAPH
-.Pp
-Enclosures:
-.Bl -tag -width 12n -offset "XXXX" -compact
-.It \\(lh
-.Pq left hand
-.It \\(rh
-.Pq right hand
-.It \\(Fo
-.Pq left guillemet
-.It \\(Fc
-.Pq right guillemet
-.It \\(fo
-.Pq left guilsing
-.It \\(fc
-.Pq right guilsing
-.It \\(rC
-.Pq right brace
-.It \\(lC
-.Pq left brace
-.It \\(ra
-.Pq right angle
-.It \\(la
-.Pq left angle
-.It \\(rB
-.Pq right bracket
-.It \\(lB
-.Pq left bracket
-.It \\q
-.Pq double-quote
-.It \\(lq
-.Pq left double-quote
-.It \\(Lq
-.Pq left double-quote, deprecated
-.It \\(rq
-.Pq right double-quote
-.It \\(Rq
-.Pq right double-quote, deprecated
-.It \\(oq
-.Pq left single-quote
-.It \\(aq
-.Pq right single-quote
-.It \\(Bq
-.Pq right low double-quote
-.It \\(bq
-.Pq right low single-quote
-.El
-.\" PARAGRAPH
-.Pp
-Indicatives:
-.Bl -tag -width 12n -offset "XXXX" -compact
-.It \\(<-
-.Pq left arrow
-.It \\(->
-.Pq right arrow
-.It \\(ua
-.Pq up arrow
-.It \\(da
-.Pq down arrow
-.It \\(<>
-.Pq left-right arrow
-.It \\(lA
-.Pq left double-arrow
-.It \\(rA
-.Pq right double-arrow
-.It \\(uA
-.Pq up double-arrow
-.It \\(dA
-.Pq down double-arrow
-.It \\(hA
-.Pq left-right double-arrow
-.El
-.\" PARAGRAPH
-.Pp
-Mathematical:
-.Bl -tag -width 12n -offset "XXXX" -compact
-.It \\(es
-.Pq empty set
-.It \\(ca
-.Pq intersection
-.It \\(cu
-.Pq union
-.It \\(gr
-.Pq gradient
-.It \\(pd
-.Pq partial differential
-.It \\(ap
-.Pq similarity
-.It \\(=)
-.Pq proper superset
-.It \\((=
-.Pq proper subset
-.It \\(eq
-.Pq equals
-.It \\(di
-.Pq division
-.It \\(mu
-.Pq multiplication
-.It \\(pl
-.Pq addition
-.It \\(nm
-.Pq not element
-.It \\(mo
-.Pq element
-.It \\(Im
-.Pq imaginary
-.It \\(Re
-.Pq real
-.It \\(Ah
-.Pq aleph
-.It \\(te
-.Pq existential quantifier
-.It \\(fa
-.Pq universal quantifier
-.It \\(AN
-.Pq logical AND
-.It \\(OR
-.Pq logical OR
-.It \\(no
-.Pq logical NOT
-.It \\(st
-.Pq such that
-.It \\(tf
-.Pq therefore
-.It \\(~~
-.Pq approximate
-.It \\(~=
-.Pq approximately equals
-.It \\(=~
-.Pq congruent
-.It \\(Gt
-.Pq greater-than, deprecated
-.It \\(Lt
-.Pq less-than, deprecated
-.It \\(<=
-.Pq less-than-equal
-.It \\(Le
-.Pq less-than-equal, deprecated
-.It \\(>=
-.Pq greater-than-equal
-.It \\(Ge
-.Pq greater-than-equal
-.It \\(==
-.Pq equal
-.It \\(!=
-.Pq not equal
-.It \\(Ne
-.Pq not equal, deprecated
-.It \\(if
-.Pq infinity
-.It \\(If
-.Pq infinity, deprecated
-.It \\(na
-.Pq NaN , an extension
-.It \\(Na
-.Pq NaN, deprecated
-.It \\(+-
-.Pq plus-minus
-.It \\(Pm
-.Pq plus-minus, deprecated
-.It \\(**
-.Pq asterisk
-.El
-.\" PARAGRAPH
-.Pp
-Ligatures:
-.Bl -tag -width 12n -offset "XXXX" -compact
-.It \\(ss
-.Pq German eszett
-.It \\(AE
-.Pq upper-case AE
-.It \\(ae
-.Pq lower-case AE
-.It \\(OE
-.Pq upper-case OE
-.It \\(oe
-.Pq lower-case OE
-.It \\(ff
-.Pq ff ligature
-.It \\(fi
-.Pq fi ligature
-.It \\(fl
-.Pq fl ligature
-.It \\(Fi
-.Pq ffi ligature
-.It \\(Fl
-.Pq ffl ligature
-.El
-.\" PARAGRAPH
-.Pp
-Diacritics and letters:
-.Bl -tag -width 12n -offset "XXXX" -compact
-.It \\(ga
-.Pq grave accent
-.It \\(aa
-.Pq accute accent
-.It \\(a"
-.Pq umlaut accent
-.It \\(ad
-.Pq dieresis accent
-.It \\(a~
-.Pq tilde accent
-.It \\(a^
-.Pq circumflex accent
-.It \\(ac
-.Pq cedilla accent
-.It \\(ad
-.Pq dieresis accent
-.It \\(ah
-.Pq caron accent
-.It \\(ao
-.Pq ring accent
-.It \\(ho
-.Pq hook accent
-.It \\(ab
-.Pq breve accent
-.It \\(a-
-.Pq macron accent
-.It \\(-D
-.Pq upper-case eth
-.It \\(Sd
-.Pq lower-case eth
-.It \\(TP
-.Pq upper-case thorn
-.It \\(Tp
-.Pq lower-case thorn
-.It \\('A
-.Pq upper-case acute A
-.It \\('E
-.Pq upper-case acute E
-.It \\('I
-.Pq upper-case acute I
-.It \\('O
-.Pq upper-case acute O
-.It \\('U
-.Pq upper-case acute U
-.It \\('a
-.Pq lower-case acute a
-.It \\('e
-.Pq lower-case acute e
-.It \\('i
-.Pq lower-case acute i
-.It \\('o
-.Pq lower-case acute o
-.It \\('u
-.Pq lower-case acute u
-.It \\(`A
-.Pq upper-case grave A
-.It \\(`E
-.Pq upper-case grave E
-.It \\(`I
-.Pq upper-case grave I
-.It \\(`O
-.Pq upper-case grave O
-.It \\(`U
-.Pq upper-case grave U
-.It \\(`a
-.Pq lower-case grave a
-.It \\(`e
-.Pq lower-case grave e
-.It \\(`i
-.Pq lower-case grave i
-.It \\(`o
-.Pq lower-case grave o
-.It \\(`u
-.Pq lower-case grave u
-.It \\(~A
-.Pq upper-case tilde A
-.It \\(~N
-.Pq upper-case tilde N
-.It \\(~O
-.Pq upper-case tilde O
-.It \\(~a
-.Pq lower-case tilde a
-.It \\(~n
-.Pq lower-case tilde n
-.It \\(~o
-.Pq lower-case tilde o
-.It \\(:A
-.Pq upper-case dieresis A
-.It \\(:E
-.Pq upper-case dieresis E
-.It \\(:I
-.Pq upper-case dieresis I
-.It \\(:O
-.Pq upper-case dieresis O
-.It \\(:U
-.Pq upper-case dieresis U
-.It \\(:a
-.Pq lower-case dieresis a
-.It \\(:e
-.Pq lower-case dieresis e
-.It \\(:i
-.Pq lower-case dieresis i
-.It \\(:o
-.Pq lower-case dieresis o
-.It \\(:u
-.Pq lower-case dieresis u
-.It \\(:y
-.Pq lower-case dieresis y
-.It \\(^A
-.Pq upper-case circumflex A
-.It \\(^E
-.Pq upper-case circumflex E
-.It \\(^I
-.Pq upper-case circumflex I
-.It \\(^O
-.Pq upper-case circumflex O
-.It \\(^U
-.Pq upper-case circumflex U
-.It \\(^a
-.Pq lower-case circumflex a
-.It \\(^e
-.Pq lower-case circumflex e
-.It \\(^i
-.Pq lower-case circumflex i
-.It \\(^o
-.Pq lower-case circumflex o
-.It \\(^u
-.Pq lower-case circumflex u
-.It \\(,C
-.Pq upper-case cedilla C
-.It \\(,c
-.Pq lower-case cedilla c
-.It \\(/L
-.Pq upper-case stroke L
-.It \\(/l
-.Pq lower-case stroke l
-.It \\(/O
-.Pq upper-case stroke O
-.It \\(/o
-.Pq lower-case stroke o
-.It \\(oA
-.Pq upper-case ring A
-.It \\(oa
-.Pq lower-case ring a
-.El
-.\" PARAGRAPH
-.Pp
-Monetary:
-.Bl -tag -width 12n -offset "XXXX" -compact
-.It \\(Cs
-.Pq Scandinavian
-.It \\(Do
-.Pq dollar
-.It \\(Po
-.Pq pound
-.It \\(Ye
-.Pq yen
-.It \\(Fn
-.Pq florin
-.It \\(ct
-.Pq cent
-.El
-.\" PARAGRAPH
-.Pp
-Special symbols:
-.Bl -tag -width 12n -offset "XXXX" -compact
-.It \\(de
-.Pq degree
-.It \\(ps
-.Pq paragraph
-.It \\(sc
-.Pq section
-.It \\(dg
-.Pq dagger
-.It \\(dd
-.Pq double dagger
-.It \\(ci
-.Pq circle
-.It \\(ba
-.Pq bar
-.It \\(bb
-.Pq broken bar
-.It \\(Ba
-.Pq bar, deprecated
-.It \\(co
-.Pq copyright
-.It \\(rg
-.Pq registered
-.It \\(tm
-.Pq trademarked
-.It \\&
-.Pq non-breaking space
-.It \\e
-.Pq escape
-.It \\(Am
-.Pq ampersand, deprecated
-.El
-.\" SECTION
-.Sh ONTOLOGY
-Macros are classified in an ontology described by scope rules.
-.\" SUB-SECTION
-.Ss Scope
-.Bl -inset
-.\" LIST-ITEM
-.It Em Block
-macros enclose other block macros, in-line macros or text, and
-may span multiple lines.
-.Bl -inset -offset XXXX
-.\" LIST-ITEM
-.It Em Full-block
-macros always span multiple lines. They consist of zero or
-more
-.Qq heads ,
-subsequent macros or text on the same line following invocation; an
-optional
-.Qq body ,
-which spans subsequent lines of text or macros; and an optional
-.Qq tail ,
-macros or text on the same line following closure.
-.\" LIST-ITEM
-.It Em Partial-block
-macros may span multiple lines. They consists of a optional
-.Qq head ,
-text immediately following invocation; always a
-.Qq body ,
-text or macros following the head on the same and subsequent lines; and
-optionally a
-.Qq tail ,
-text immediately following closure.
-.\" LIST-ITEM
-.It Em In-line
-macros may only enclose text and span at most a single line.
-.El
-.El
-.\" SUB-SECTION
-.Ss Closure
-Closure of a macro's scope depends first on its classification, then
-on whether it's parsable. In this table,
-.Sq BFE
-refers to block full-explicit and so on.
-.\" PARAGRAPH
-.Pp
-.Bl -tag -width 12n -offset XXXX -compact
-.It BPE , BFE
-corresponding explicit closure macro
-.It BFI
-end-of-file or a corresponding implicit closure macro
-.It BPI
-end-of-line (body may be closed by >0 space-separated
-.Sx Reserved Characters ,
-although block scope will still be open)
-.It INL
-end-of-line
-.El
-.\" PARAGRAPH
+Text may also be sized with the
+.Sq \es
+escape, whose syntax is one of
+.Sq \es+-n
+for one-digit numerals;
+.Sq \es(+-nn
+or
+.Sq \es+-(nn
+for two-digit numerals; and
+.Sq \es[+-N] ,
+.Sq \es+-[N] ,
+.Sq \es'+-N' ,
+or
+.Sq \es+-'N'
+for arbitrary-digit numerals:
.Pp
-If a macro (block or in-line) is parsable, it may also be closed out by
-one of the following scenarios (unless specifically noted otherwise):
-.\" PARAGRAPH
+.D1 \es+1bigger\es-1
+.D1 \es[+10]much bigger\es[-10]
+.D1 \es+(10much bigger\es-(10
+.D1 \es+'100'much much bigger\es-'100'
.Pp
-.Bl -dash -offset XXXX -compact
-.It
-a sequence of >0 space-separated
-.Sx Reserved Characters ,
-.It
-another macro,
-.It
-end-of-line, or
-.It
-completion of a set number of arguments.
+Note these forms are
+.Em not
+recommended for
+.Nm ,
+which encourages semantic annotation.
+.Ss Predefined Strings
+Historically,
+.Xr groff 1
+also defined a set of package-specific
+.Dq predefined strings ,
+which, like
+.Sx Special Characters ,
+demark special output characters and strings by way of input codes.
+Predefined strings are escaped with the slash-asterisk,
+.Sq \e* :
+single-character
+.Sq \e*X ,
+two-character
+.Sq \e*(XX ,
+and N-character
+.Sq \e*[N] .
+See
+.Xr mandoc_char 7
+for a complete list. Examples include
+.Sq \e*(Am
+.Pq ampersand
+and
+.Sq \e*(Ba
+.Pq vertical bar .
+.Ss Whitespace
+In non-literal free-form lines, consecutive blocks of whitespace are
+pruned from input and added later in the output filter, if applicable:
+.Bd -literal -offset indent
+These spaces are pruned from input.
+\&.Bd \-literal
+These are not.
+\&.Ed
+.Ed
+.Pp
+In macro lines, whitespace delimits arguments and is discarded. If
+arguments are quoted, whitespace within the quotes is retained.
+.Pp
+Blank lines are only permitted within literal contexts, as are lines
+containing only whitespace. Tab characters are only acceptable when
+delimiting
+.Sq \&Bl \-column
+or when in a literal context.
+.Ss Quotation
+Macro arguments may be quoted with a double-quote to group
+space-delimited 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.
+.Pp
+This produces tokens
+.Sq a" ,
+.Sq b c ,
+.Sq de ,
+and
+.Sq fg" .
+Note that any quoted term, be it argument or macro, is indiscriminately
+considered literal text. Thus, the following produces
+.Sq \&Em a :
+.Bd -literal -offset indent
+\&.Em "Em a"
+.Ed
+.Pp
+In free-form mode, quotes are regarded as opaque text.
+.Ss Dates
+There are several macros in
+.Nm
+that require a date argument. The canonical form for dates is the
+American format:
+.Pp
+.D1 Cm Month Day , Year
+.Pp
+The
+.Cm Day
+value is an optionally zero-padded numeral. The
+.Cm Month
+value is the full month name. The
+.Cm Year
+value is the full four-digit year.
+.Pp
+Reduced form dates are broken-down canonical form dates:
+.Pp
+.D1 Cm Month , Year
+.D1 Cm Year
+.Pp
+Some examples of valid dates follow:
+.Pp
+.D1 "May, 2009" Pq reduced form
+.D1 "2009" Pq reduced form
+.D1 "May 20, 2009" Pq canonical form
+.Ss Scaling Widths
+Many macros support scaled widths for their arguments, such as
+stipulating a two-inch list indentation with the following:
+.Bd -literal -offset indent
+\&.Bl -tag -width 2i
+.Ed
+.Pp
+The syntax for scaled widths is
+.Sq Li [+-]?[0-9]*.[0-9]*[:unit:] ,
+where a decimal must be preceded or proceeded by at least one digit.
+Negative numbers, while accepted, are truncated to zero. The following
+scaling units are accepted:
+.Pp
+.Bl -tag -width Ds -offset indent -compact
+.It c
+centimetre
+.It i
+inch
+.It P
+pica (~1/6 inch)
+.It p
+point (~1/72 inch)
+.It f
+synonym for
+.Sq u
+.It v
+default vertical span
+.It m
+width of rendered
+.Sq m
+.Pq em
+character
+.It n
+width of rendered
+.Sq n
+.Pq en
+character
+.It u
+default horizontal span
+.It M
+mini-em (~1/100 em)
.El
-.\" PARAGRAPH
.Pp
-If >0 space-separated
-.Sx Reserved Characters
-are followed by non-reserved characters, the behaviour differs per
-macro. In general, scope of the macro is closed and re-opened:
-subsequent tokens are interpreted as if the scope had just been opened.
-In other circumstances, scope is simply closed out.
-.\" SECTION
-.Sh SYNTAX
-Macros are generally two and at times three characters in length. The
-syntax of macro invocation depends on its classification.
-.Qq \-arg
-refers to the macro arguments (which may contain zero or more values).
-In these illustrations,
-.Sq \&.Yo
-opens the scope of a macro, and if specified,
-.Sq \&.Yc
-closes it out (closure may be implicit at end-of-line or end-of-file).
-.\" PARAGRAPH
-.Pp
-Block full-explicit (may contain head, body, tail).
-.Bd -literal -offset XXXX
-\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB
-\(lBbody...\(rB
-\&.Yc \(lBtail...\(rB
+Using anything other than
+.Sq m ,
+.Sq n ,
+.Sq u ,
+or
+.Sq v
+is necessarily non-portable across output media. See
+.Sx COMPATIBILITY .
+.Sh MANUAL STRUCTURE
+A well-formed
+.Nm
+document consists of a document prologue followed by one or more
+sections.
+.Pp
+The prologue, which consists of (in order) the
+.Sx \&Dd ,
+.Sx \&Dt ,
+and
+.Sx \&Os
+macros, is required for every document.
+.Pp
+The first section (sections are denoted by
+.Sx \&Sh )
+must be the NAME section, consisting of at least one
+.Sx \&Nm
+followed by
+.Sx \&Nd .
+.Pp
+Following that, convention dictates specifying at least the SYNOPSIS and
+DESCRIPTION sections, although this varies between manual sections.
+.Pp
+The following is a well-formed skeleton
+.Nm
+file:
+.Bd -literal -offset indent
+\&.Dd $\&Mdocdate$
+\&.Dt mdoc 7
+\&.Os
+\&.
+\&.Sh NAME
+\&.Nm foo
+\&.Nd a description goes here
+\&.\e\*q The next is for sections 2 & 3 only.
+\&.\e\*q .Sh LIBRARY
+\&.
+\&.Sh SYNOPSIS
+\&.Nm foo
+\&.Op Fl options
+\&.Ar
+\&.
+\&.Sh DESCRIPTION
+The
+\&.Nm
+utility processes files ...
+\&.\e\*q .Sh IMPLEMENTATION NOTES
+\&.\e\*q The next is for sections 1 & 8 only.
+\&.\e\*q .Sh EXIT STATUS
+\&.\e\*q The next is for sections 2, 3, & 9 only.
+\&.\e\*q .Sh RETURN VALUES
+\&.\e\*q The next is for sections 1, 6, 7, & 8 only.
+\&.\e\*q .Sh ENVIRONMENT
+\&.\e\*q .Sh FILES
+\&.\e\*q .Sh EXAMPLES
+\&.\e\*q The next is for sections 1, 4, 6, 7, & 8 only.
+\&.\e\*q .Sh DIAGNOSTICS
+\&.\e\*q The next is for sections 2, 3, & 9 only.
+\&.\e\*q .Sh ERRORS
+\&.\e\*q .Sh SEE ALSO
+\&.\e\*q .Xr foobar 1
+\&.\e\*q .Sh STANDARDS
+\&.\e\*q .Sh HISTORY
+\&.\e\*q .Sh AUTHORS
+\&.\e\*q .Sh CAVEATS
+\&.\e\*q .Sh BUGS
+\&.\e\*q .Sh SECURITY CONSIDERATIONS
.Ed
-.\" PARAGRAPH
.Pp
-Block full-implicit (may contain zero or more heads, body, no tail).
-.Bd -literal -offset XXXX
-\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB
-\(lBbody...\(rB
-\&.Yc
+The sections in a
+.Nm
+document are conventionally ordered as they appear above. Sections
+should be composed as follows:
+.Bl -ohang -offset Ds
+.It Em NAME
+The name(s) and a short description of the documented material. The
+syntax for this as follows:
+.Bd -literal -offset indent
+\&.Nm name0
+\&.Nm name1
+\&.Nm name2
+\&.Nd a short description
.Ed
-.\" PARAGRAPH
.Pp
-Block partial-explicit (may contain head, multi-line body, tail).
-.Bd -literal -offset XXXX
-\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB
-\(lBbody...\(rB
-\&.Yc \(lBtail...\(rB
-
-\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB \
-\(lBbody...\(rB \&Yc \(lBtail...\(rB
+The
+.Sx \&Nm
+macro(s) must precede the
+.Sx \&Nd
+macro.
+.Pp
+See
+.Sx \&Nm
+and
+.Sx \&Nd .
+.It Em LIBRARY
+The name of the library containing the documented material, which is
+assumed to be a function in a section 2 or 3 manual. The syntax for
+this is as follows:
+.Bd -literal -offset indent
+\&.Lb libarm
.Ed
-.\" PARAGRAPH
-.Pp
-Block partial-implicit (no head, body, no tail). Note that the body
-section may be followed by zero or more
-.Sx Reserved Words .
-These are in the block scope, but not in the body scope.
-.Bd -literal -offset XXXX
-\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBreserved...\(rB
+.Pp
+See
+.Sx \&Lb .
+.It Em SYNOPSIS
+Documents the utility invocation syntax, function call syntax, or device
+configuration.
+.Pp
+For the first, utilities (sections 1, 6, and 8), this is
+generally structured as follows:
+.Bd -literal -offset indent
+\&.Nm foo
+\&.Op Fl v
+\&.Op Fl o Ar file
+\&.Op Ar
+\&.Nm bar
+\&.Op Fl v
+\&.Op Fl o Ar file
+\&.Op Ar
.Ed
-.\" PARAGRAPH
.Pp
-In-lines have \(>=0 scoped arguments.
-.Bd -literal -offset XXX
-\&.Yy \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB
-
-\&.Yy \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN
+For the second, function calls (sections 2, 3, 9):
+.Bd -literal -offset indent
+\&.Vt extern const char *global;
+\&.In header.h
+\&.Ft "char *"
+\&.Fn foo "const char *src"
+\&.Ft "char *"
+\&.Fn bar "const char *src"
.Ed
-.\"
-.Sh MACROS
-This section contains a complete list of all
-.Nm
-macros, arranged ontologically. A
-.Qq callable
-macro is may be invoked subsequent to the initial macro-line macro. A
-.Qq parsable
-macro may be followed by further (ostensibly callable) macros.
-.\" SUB-SECTION
+.Pp
+And for the third, configurations (section 4):
+.Bd -literal -offset indent
+\&.Cd \*qit* at isa? port 0x2e\*q
+\&.Cd \*qit* at isa? port 0x4e\*q
+.Ed
+.Pp
+Manuals not in these sections generally don't need a
+.Em SYNOPSIS .
+.Pp
+See
+.Sx \&Op ,
+.Sx \&Cd ,
+.Sx \&Fn ,
+.Sx \&Ft ,
+and
+.Sx \&Vt .
+.It Em DESCRIPTION
+This expands upon the brief, one-line description in
+.Em NAME .
+It usually contains a break-down of the options (if documenting a
+command), such as:
+.Bd -literal -offset indent
+The arguments are as follows:
+\&.Bl \-tag \-width Ds
+\&.It Fl v
+Print verbose information.
+\&.El
+.Ed
+.Pp
+Manuals not documenting a command won't include the above fragment.
+.It Em 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.
+.It Em EXIT STATUS
+Command exit status for section 1, 6, and 8 manuals. This section is
+the dual of
+.Em RETURN VALUES ,
+which is used for functions. Historically, this information was
+described in
+.Em DIAGNOSTICS ,
+a practise that is now discouraged.
+.Pp
+See
+.Sx \&Ex .
+.It Em RETURN VALUES
+This section is the dual of
+.Em EXIT STATUS ,
+which is used for commands. It documents the return values of functions
+in sections 2, 3, and 9.
+.Pp
+See
+.Sx \&Rv .
+.It Em ENVIRONMENT
+Documents any usages of environment variables, e.g.,
+.Xr environ 7 .
+.Pp
+See
+.Sx \&Ev .
+.It Em FILES
+Documents files used. It's helpful to document both the file and a
+short description of how the file is used (created, modified, etc.).
+.Pp
+See
+.Sx \&Pa .
+.It Em EXAMPLES
+Example usages. This often contains snippets of well-formed,
+well-tested invocations. Make doubly sure that your examples work
+properly!
+.It Em DIAGNOSTICS
+Documents error conditions. This is most useful in section 4 manuals.
+Historically, this section was used in place of
+.Em EXIT STATUS
+for manuals in sections 1, 6, and 8; however, this practise is
+discouraged.
+.Pp
+See
+.Sx \&Bl
+.Fl diag .
+.It Em ERRORS
+Documents error handling in sections 2, 3, and 9.
+.Pp
+See
+.Sx \&Er .
+.It Em 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.
+.Pp
+See
+.Sx \&Xr .
+.It Em STANDARDS
+References any standards implemented or used. If not adhering to any
+standards, the
+.Em HISTORY
+section should be used instead.
+.Pp
+See
+.Sx \&St .
+.It Em HISTORY
+The history of any manual without a
+.Em STANDARDS
+section should be described in this section.
+.It Em AUTHORS
+Credits to authors, if applicable, should appear in this section.
+Authors should generally be noted by both name and an e-mail address.
+.Pp
+See
+.Sx \&An .
+.It Em CAVEATS
+Explanations of common misuses and misunderstandings should be explained
+in this section.
+.It Em BUGS
+Extant bugs should be described in this section.
+.It Em SECURITY CONSIDERATIONS
+Documents any security precautions that operators should consider.
+.El
+.Sh MACRO SYNTAX
+Macros are one to three three characters in length and begin with a
+control character ,
+.Sq \&. ,
+at the beginning of the line. An arbitrary amount of whitespace may
+sit between the control character and the macro name. Thus, the
+following are equivalent:
+.Bd -literal -offset indent
+\&.Pp
+\&.\ \ \ \&Pp
+.Ed
+.Pp
+The syntax of a macro depends on its classification. In this section,
+.Sq \-arg
+refers to macro arguments, which may be followed by zero or more
+.Sq parm
+parameters;
+.Sq \&Yo
+opens the scope of a macro; and if specified,
+.Sq \&Yc
+closes it out.
+.Pp
+The
+.Em 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
+.Sq \&.Fl \&Sh
+produces
+.Sq Fl \&Sh .
+.Pp
+The
+.Em Parsable
+column indicates whether the macro may be followed by further
+(ostensibly callable) macros. If a macro is not parsable, subsequent
+macro invocations on the line will be interpreted as opaque text.
+.Pp
+The
+.Em Scope
+column, if applicable, describes closure rules.
+.Ss Block full-explicit
+Multi-line scope closed by an explicit closing macro. All macros
+contains bodies; only
+.Sx \&Bf
+contains a head.
+.Bd -literal -offset indent
+\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB
+\(lBbody...\(rB
+\&.Yc
+.Ed
+.Pp
+.Bl -column -compact -offset indent "MacroX" "CallableX" "ParsableX" "closed by XXX"
+.It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
+.It Sx \&Bd Ta \&No Ta \&No Ta closed by Sx \&Ed
+.It Sx \&Bf Ta \&No Ta \&No Ta closed by Sx \&Ef
+.It Sx \&Bk Ta \&No Ta \&No Ta closed by Sx \&Ek
+.It Sx \&Bl Ta \&No Ta \&No Ta closed by Sx \&El
+.It Sx \&Ed Ta \&No Ta \&No Ta opened by Sx \&Bd
+.It Sx \&Ef Ta \&No Ta \&No Ta opened by Sx \&Bf
+.It Sx \&Ek Ta \&No Ta \&No Ta opened by Sx \&Bk
+.It Sx \&El Ta \&No Ta \&No Ta opened by Sx \&Bl
+.El
.Ss Block full-implicit
-The head of these macros follows invocation; the body is the content of
-subsequent lines prior to closure. None of these macros have tails;
-some
+Multi-line scope closed by end-of-file or implicitly by another macro.
+All macros have bodies; some
+.Po
+.Sx \&It Fl bullet ,
+.Fl hyphen ,
+.Fl dash ,
+.Fl enum ,
+.Fl item
+.Pc
+don't have heads; only one
.Po
-.Sq \&It \-bullet ,
-.Sq \-hyphen ,
-.Sq \-dash ,
-.Sq \-enum ,
-.Sq \-item
+.Sx \&It Fl column
.Pc
-don't have heads.
+has multiple heads.
+.Bd -literal -offset indent
+\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB
+\(lBbody...\(rB
+.Ed
.Pp
-.Bl -column "MacroX" "CallableX" "ParsableX" "Closing" -compact -offset XXXX
-.It Em Macro Ta Em Callable Ta Em Parsable Ta Em Closing
-.It \&.Sh Ta \&No Ta \&No Ta \&.Sh
-.It \&.Ss Ta \&No Ta \&No Ta \&.Sh, \&.Ss
-.It \&.It Ta \&No Ta Yes Ta \&.It, \&.El
+.Bl -column -compact -offset indent "MacroX" "CallableX" "ParsableX" "closed by XXXXXXXXXXX"
+.It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
+.It Sx \&It Ta \&No Ta Yes Ta closed by Sx \&It , Sx \&El
+.It Sx \&Nd Ta \&No Ta \&No Ta closed by Sx \&Sh
+.It Sx \&Sh Ta \&No Ta \&No Ta closed by Sx \&Sh
+.It Sx \&Ss Ta \&No Ta \&No Ta closed by Sx \&Sh , Sx \&Ss
.El
-.\" SUB-SECTION
-.Ss Block full-explicit
-None of these macros are callable or parsed. The last column indicates
-the explicit scope rules. All contains bodies, some may contain heads
-.Pq So \&Bf Sc .
+.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
+.Po
+.Sx \&Fo ,
+.Sx \&Eo
+.Pc
+and/or tail
+.Pq Sx \&Ec .
+.Bd -literal -offset indent
+\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB
+\(lBbody...\(rB
+\&.Yc \(lBtail...\(rB
+
+\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \
+\(lBbody...\(rB \&Yc \(lBtail...\(rB
+.Ed
.Pp
-.Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXX" -compact -offset XXXX
+.Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXXX" -compact -offset indent
.It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
-.It \&.Bd Ta \&No Ta \&No Ta closed by \&.Ed
-.It \&.Ed Ta \&No Ta \&No Ta opened by \&.Bd
-.It \&.Bl Ta \&No Ta \&No Ta closed by \&.El
-.It \&.El Ta \&No Ta \&No Ta opened by \&.Bl
-.It \&.Bf Ta \&No Ta \&No Ta closed by \&.Ef
-.It \&.Ef Ta \&No Ta \&No Ta opened by \&.Bf
-.It \&.Bk Ta \&No Ta \&No Ta closed by \&.Ek
-.It \&.Ek Ta \&No Ta \&No Ta opened by \&.Bk
+.It Sx \&Ac Ta Yes Ta Yes Ta opened by Sx \&Ao
+.It Sx \&Ao Ta Yes Ta Yes Ta closed by Sx \&Ac
+.It Sx \&Bc Ta Yes Ta Yes Ta closed by Sx \&Bo
+.It Sx \&Bo Ta Yes Ta Yes Ta opened by Sx \&Bc
+.It Sx \&Brc Ta Yes Ta Yes Ta opened by Sx \&Bro
+.It Sx \&Bro Ta Yes Ta Yes Ta closed by Sx \&Brc
+.It Sx \&Dc Ta Yes Ta Yes Ta opened by Sx \&Do
+.It Sx \&Do Ta Yes Ta Yes Ta closed by Sx \&Dc
+.It Sx \&Ec Ta Yes Ta Yes Ta opened by Sx \&Eo
+.It Sx \&Eo Ta Yes Ta Yes Ta closed by Sx \&Ec
+.It Sx \&Fc Ta Yes Ta Yes Ta opened by Sx \&Fo
+.It Sx \&Fo Ta \&No Ta \&No Ta closed by Sx \&Fc
+.It Sx \&Oc Ta Yes Ta Yes Ta closed by Sx \&Oo
+.It Sx \&Oo Ta Yes Ta Yes Ta opened by Sx \&Oc
+.It Sx \&Pc Ta Yes Ta Yes Ta closed by Sx \&Po
+.It Sx \&Po Ta Yes Ta Yes Ta opened by Sx \&Pc
+.It Sx \&Qc Ta Yes Ta Yes Ta opened by Sx \&Oo
+.It Sx \&Qo Ta Yes Ta Yes Ta closed by Sx \&Oc
+.It Sx \&Re Ta \&No Ta \&No Ta opened by Sx \&Rs
+.It Sx \&Rs Ta \&No Ta \&No Ta closed by Sx \&Re
+.It Sx \&Sc Ta Yes Ta Yes Ta opened by Sx \&So
+.It Sx \&So Ta Yes Ta Yes Ta closed by Sx \&Sc
+.It Sx \&Xc Ta Yes Ta Yes Ta opened by Sx \&Xo
+.It Sx \&Xo Ta Yes Ta Yes Ta closed by Sx \&Xc
.El
-.\" SUB-SECTION
.Ss Block partial-implicit
-All of these are callable and parsed for further macros. Their scopes
-close at the invocation's end-of-line.
+Like block full-implicit, but with single-line scope closed by
+.Sx Reserved Characters
+or end of line.
+.Bd -literal -offset indent
+\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB
+.Ed
.Pp
-.Bl -column "MacroX" "CallableX" "ParsableX" -compact -offset XXXX
+.Bl -column "MacroX" "CallableX" "ParsableX" -compact -offset indent
.It Em Macro Ta Em Callable Ta Em Parsable
-.It \&.Aq Ta Yes Ta Yes
-.It \&.Op Ta Yes Ta Yes
-.It \&.Bq Ta Yes Ta Yes
-.It \&.Dq Ta Yes Ta Yes
-.It \&.Pq Ta Yes Ta Yes
-.It \&.Qq Ta Yes Ta Yes
-.It \&.Sq Ta Yes Ta Yes
-.It \&.Brq Ta Yes Ta Yes
-.It \&.D1 Ta \&No Ta \&Yes
-.It \&.Dl Ta \&No Ta Yes
-.It \&.Ql Ta Yes Ta Yes
+.It Sx \&Aq Ta Yes Ta Yes
+.It Sx \&Bq Ta Yes Ta Yes
+.It Sx \&Brq Ta Yes Ta Yes
+.It Sx \&D1 Ta \&No Ta \&Yes
+.It Sx \&Dl Ta \&No Ta Yes
+.It Sx \&Dq Ta Yes Ta Yes
+.It Sx \&Op Ta Yes Ta Yes
+.It Sx \&Pq Ta Yes Ta Yes
+.It Sx \&Ql Ta Yes Ta Yes
+.It Sx \&Qq Ta Yes Ta Yes
+.It Sx \&Sq Ta Yes Ta Yes
+.It Sx \&Vt Ta Yes Ta Yes
.El
-.\" SUB-SECTION
-.Ss Block partial-explicit
-Each of these contains at least a body and, in limited circumstances, a
-head
-.Pq So \&Fo Sc , So \&Eo Sc
-and/or tail
-.Pq So \&Ec Sc .
.Pp
-.Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXXX" -compact -offset XXXX
-.It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
-.It \&.Ao Ta Yes Ta Yes Ta closed by \&.Ac
-.It \&.Ac Ta Yes Ta Yes Ta opened by \&.Ao
-.It \&.Bc Ta Yes Ta Yes Ta closed by \&.Bo
-.It \&.Bo Ta Yes Ta Yes Ta opened by \&.Bc
-.It \&.Pc Ta Yes Ta Yes Ta closed by \&.Po
-.It \&.Po Ta Yes Ta Yes Ta opened by \&.Pc
-.It \&.Do Ta Yes Ta Yes Ta closed by \&.Dc
-.It \&.Dc Ta Yes Ta Yes Ta opened by \&.Do
-.It \&.Xo Ta Yes Ta Yes Ta closed by \&.Xc
-.It \&.Xc Ta Yes Ta Yes Ta opened by \&.Xo
-.It \&.Bro Ta Yes Ta Yes Ta closed by \&.Brc
-.It \&.Brc Ta Yes Ta Yes Ta opened by \&.Bro
-.It \&.Oc Ta Yes Ta Yes Ta closed by \&.Oo
-.It \&.Oo Ta Yes Ta Yes Ta opened by \&.Oc
-.It \&.So Ta Yes Ta Yes Ta closed by \&.Sc
-.It \&.Sc Ta Yes Ta Yes Ta opened by \&.So
-.It \&.Fc Ta Yes Ta Yes Ta opened by \&.Fo
-.It \&.Fo Ta \&No Ta \&No Ta closed by \&.Fc
-.It \&.Ec Ta Yes Ta Yes Ta opened by \&.Eo
-.It \&.Eo Ta Yes Ta Yes Ta closed by \&.Ec
-.It \&.Qc Ta Yes Ta Yes Ta opened by \&.Oo
-.It \&.Qo Ta Yes Ta Yes Ta closed by \&.Oc
-.It \&.Re Ta \&No Ta \&No Ta opened by \&.Rs
-.It \&.Rs Ta \&No Ta \&No Ta closed by \&.Re
-.El
-.\" SUB-SECTION
-.Ss In-line
-In-line macros have only text children. If a number (or inequality) of
+Note that the
+.Sx \&Vt
+macro is a
+.Sx Block partial-implicit
+only when invoked as the first macro
+in a SYNOPSIS section line, else it is
+.Sx In-line .
+.Ss In-line
+Closed by
+.Sx 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
-.Pq n ,
+.Pq n ,
then the macro accepts an arbitrary number of arguments.
+.Bd -literal -offset indent
+\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(lbres...\(rb
+
+\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB Yc...
+
+\&.Yo \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN
+.Ed
.Pp
-.Bl -column "MacroX" "CallableX" "ParsableX" "Arguments" -compact -offset XXXX
+.Bl -column "MacroX" "CallableX" "ParsableX" "Arguments" -compact -offset indent
.It Em Macro Ta Em Callable Ta Em Parsable Ta Em Arguments
-.It \&.Dd Ta \&No Ta \&No Ta >0
-.It \&.Dt Ta \&No Ta \&No Ta n
-.It \&.Os Ta \&No Ta \&No Ta n
-.It \&.Pp Ta \&No Ta \&No Ta 0
-.It \&.Ad Ta Yes Ta Yes Ta n
-.It \&.An Ta \&No Ta Yes Ta n
-.It \&.Ar Ta Yes Ta Yes Ta n
-.It \&.Cd Ta Yes Ta \&No Ta >0
-.It \&.Cm Ta Yes Ta Yes Ta n
-.It \&.Dv Ta Yes Ta Yes Ta >0
-.It \&.Er Ta Yes Ta Yes Ta >0
-.It \&.Ev Ta Yes Ta Yes Ta >0
-.It \&.Ex Ta \&No Ta \&No Ta 0
-.It \&.Fa Ta Yes Ta Yes Ta >0
-.It \&.Fd Ta \&No Ta \&No Ta >0
-.It \&.Fl Ta Yes Ta Yes Ta n
-.It \&.Fn Ta Yes Ta Yes Ta >0
-.It \&.Ft Ta \&No Ta Yes Ta n
-.It \&.Ic Ta Yes Ta Yes Ta >0
-.It \&.In Ta \&No Ta \&No Ta n
-.It \&.Li Ta Yes Ta Yes Ta >0
-.It \&.Nd Ta \&No Ta \&No Ta n
-.It \&.Nm Ta Yes Ta Yes Ta n
-.It \&.Ot Ta \&No Ta \&No Ta n
-.It \&.Pa Ta Yes Ta Yes Ta n
-.It \&.Rv Ta \&No Ta \&No Ta 0
-.It \&.St Ta \&No Ta Yes Ta 1
-.It \&.Va Ta Yes Ta Yes Ta >0
-.It \&.Vt Ta Yes Ta Yes Ta >0
-.It \&.Xr Ta Yes Ta Yes Ta >0, <3
-.It \&.%A Ta \&No Ta \&No Ta >0
-.It \&.%B Ta \&No Ta \&No Ta >0
-.It \&.%C Ta \&No Ta \&No Ta >0
-.It \&.%D Ta \&No Ta \&No Ta >0
-.It \&.%I Ta \&No Ta \&No Ta >0
-.It \&.%J Ta \&No Ta \&No Ta >0
-.It \&.%N Ta \&No Ta \&No Ta >0
-.It \&.%O Ta \&No Ta \&No Ta >0
-.It \&.%P Ta \&No Ta \&No Ta >0
-.It \&.%R Ta \&No Ta \&No Ta >0
-.It \&.%T Ta \&No Ta \&No Ta >0
-.It \&.%V Ta \&No Ta \&No Ta >0
-.It \&.At Ta Yes Ta Yes Ta 1
-.It \&.Bsx Ta Yes Ta Yes Ta n
-.It \&.Bx Ta Yes Ta Yes Ta n
-.It \&.Db Ta \&No Ta \&No Ta 1
-.It \&.Em Ta Yes Ta Yes Ta >0
-.It \&.Fx Ta Yes Ta Yes Ta n
-.It \&.Ms Ta \&No Ta Yes Ta >0
-.It \&.No Ta Yes Ta Yes Ta 0
-.It \&.Ns Ta Yes Ta Yes Ta 0
-.It \&.Nx Ta Yes Ta Yes Ta n
-.It \&.Ox Ta Yes Ta Yes Ta n
-.It \&.Pf Ta \&No Ta Yes Ta 1
-.It \&.Sm Ta \&No Ta \&No Ta 1
-.It \&.Sx Ta Yes Ta Yes Ta >0
-.It \&.Sy Ta Yes Ta Yes Ta >0
-.It \&.Tn Ta Yes Ta Yes Ta >0
-.It \&.Ux Ta Yes Ta Yes Ta n
-.It \&.Dx Ta Yes Ta Yes Ta n
-.It \&.Bt Ta \&No Ta \&No Ta 0
-.It \&.Hf Ta \&No Ta \&No Ta n
-.It \&.Fr Ta \&No Ta \&No Ta n
-.It \&.Ud Ta \&No Ta \&No Ta 0
-.It \&.Lb Ta \&No Ta \&No Ta 1
-.It \&.Ap Ta Yes Ta Yes Ta 0
-.It \&.Lp Ta \&No Ta \&No Ta 0
-.It \&.Lk Ta \&No Ta Yes Ta >0
-.It \&.Mt Ta \&No Ta Yes Ta >0
-.It \&.Es Ta \&No Ta \&No Ta 0
-.It \&.En Ta \&No Ta \&No Ta 0
+.It Sx \&%A Ta \&No Ta \&No Ta >0
+.It Sx \&%B Ta \&No Ta \&No Ta >0
+.It Sx \&%C Ta \&No Ta \&No Ta >0
+.It Sx \&%D Ta \&No Ta \&No Ta >0
+.It Sx \&%I Ta \&No Ta \&No Ta >0
+.It Sx \&%J Ta \&No Ta \&No Ta >0
+.It Sx \&%N Ta \&No Ta \&No Ta >0
+.It Sx \&%O Ta \&No Ta \&No Ta >0
+.It Sx \&%P Ta \&No Ta \&No Ta >0
+.It Sx \&%Q Ta \&No Ta \&No Ta >0
+.It Sx \&%R Ta \&No Ta \&No Ta >0
+.It Sx \&%T Ta \&No Ta \&No Ta >0
+.It Sx \&%U Ta \&No Ta \&No Ta >0
+.It Sx \&%V Ta \&No Ta \&No Ta >0
+.It Sx \&Ad Ta Yes Ta Yes Ta n
+.It Sx \&An Ta Yes Ta Yes Ta n
+.It Sx \&Ap Ta Yes Ta Yes Ta 0
+.It Sx \&Ar Ta Yes Ta Yes Ta n
+.It Sx \&At Ta Yes Ta Yes Ta 1
+.It Sx \&Bsx Ta Yes Ta Yes Ta n
+.It Sx \&Bt Ta \&No Ta \&No Ta 0
+.It Sx \&Bx Ta Yes Ta Yes Ta n
+.It Sx \&Cd Ta Yes Ta Yes Ta >0
+.It Sx \&Cm Ta Yes Ta Yes Ta n
+.It Sx \&Db Ta \&No Ta \&No Ta 1
+.It Sx \&Dd Ta \&No Ta \&No Ta >0
+.It Sx \&Dt Ta \&No Ta \&No Ta n
+.It Sx \&Dv Ta Yes Ta Yes Ta n
+.It Sx \&Dx Ta Yes Ta Yes Ta n
+.It Sx \&Em Ta Yes Ta Yes Ta >0
+.It Sx \&En Ta \&No Ta \&No Ta 0
+.It Sx \&Er Ta Yes Ta Yes Ta >0
+.It Sx \&Es Ta \&No Ta \&No Ta 0
+.It Sx \&Ev Ta Yes Ta Yes Ta n
+.It Sx \&Ex Ta \&No Ta \&No Ta n
+.It Sx \&Fa Ta Yes Ta Yes Ta n
+.It Sx \&Fd Ta \&No Ta \&No Ta >0
+.It Sx \&Fl Ta Yes Ta Yes Ta n
+.It Sx \&Fn Ta Yes Ta Yes Ta >0
+.It Sx \&Fr Ta \&No Ta \&No Ta n
+.It Sx \&Ft Ta Yes Ta Yes Ta n
+.It Sx \&Fx Ta Yes Ta Yes Ta n
+.It Sx \&Hf Ta \&No Ta \&No Ta n
+.It Sx \&Ic Ta Yes Ta Yes Ta >0
+.It Sx \&In Ta \&No Ta \&No Ta n
+.It Sx \&Lb Ta \&No Ta \&No Ta 1
+.It Sx \&Li Ta Yes Ta Yes Ta n
+.It Sx \&Lk Ta Yes Ta Yes Ta n
+.It Sx \&Lp Ta \&No Ta \&No Ta 0
+.It Sx \&Ms Ta Yes Ta Yes Ta >0
+.It Sx \&Mt Ta Yes Ta Yes Ta >0
+.It Sx \&Nm Ta Yes Ta Yes Ta n
+.It Sx \&No Ta Yes Ta Yes Ta 0
+.It Sx \&Ns Ta Yes Ta Yes Ta 0
+.It Sx \&Nx Ta Yes Ta Yes Ta n
+.It Sx \&Os Ta \&No Ta \&No Ta n
+.It Sx \&Ot Ta \&No Ta \&No Ta n
+.It Sx \&Ox Ta Yes Ta Yes Ta n
+.It Sx \&Pa Ta Yes Ta Yes Ta n
+.It Sx \&Pf Ta Yes Ta Yes Ta 1
+.It Sx \&Pp Ta \&No Ta \&No Ta 0
+.It Sx \&Rv Ta \&No Ta \&No Ta n
+.It Sx \&Sm Ta \&No Ta \&No Ta 1
+.It Sx \&St Ta \&No Ta Yes Ta 1
+.It Sx \&Sx Ta Yes Ta Yes Ta >0
+.It Sx \&Sy Ta Yes Ta Yes Ta >0
+.It Sx \&Tn Ta Yes Ta Yes Ta >0
+.It Sx \&Ud Ta \&No Ta \&No Ta 0
+.It Sx \&Ux Ta Yes Ta Yes Ta n
+.It Sx \&Va Ta Yes Ta Yes Ta n
+.It Sx \&Vt Ta Yes Ta Yes Ta >0
+.It Sx \&Xr Ta Yes Ta Yes Ta >0
+.It Sx \&br Ta \&No Ta \&No Ta 0
+.It Sx \&sp Ta \&No Ta \&No Ta 1
.El
+.Sh REFERENCE
+This section is a canonical reference of all macros, arranged
+alphabetically. For the scoping of individual macros, see
+.Sx MACRO SYNTAX .
+.Ss \&%A
+Author name of an
+.Sx \&Rs
+block. Multiple authors should each be accorded their own
+.Sx \%%A
+line. Author names should be ordered with full or abbreviated
+forename(s) first, then full surname.
+.Ss \&%B
+Book title of an
+.Sx \&Rs
+block. This macro may also be used in a non-bibliographic context when
+referring to book titles.
+.Ss \&%C
+Publication city or location of an
+.Sx \&Rs
+block.
.Pp
-The
-.Sq \&Ot ,
-.Sq \&Fr ,
-.Sq \&Es
-and
-.Sq \&En ,
-macros are obsolete.
-.\" SECTION
-.Sh COMPATIBILITY
-The mdoc language was traditionally a
-.Qq roff
-macro package; most existing manuals were written with mdoc syntax
-dictated by system-dependent roff installations. This section documents
-compatibility with these systems.
+.Em Remarks :
+this macro is not implemented in
+.Xr groff 1 .
+.Ss \&%D
+Publication date of an
+.Sx \&Rs
+block. This should follow the reduced or canonical form syntax
+described in
+.Sx Dates .
+.Ss \&%I
+Publisher or issuer name of an
+.Sx \&Rs
+block.
+.Ss \&%J
+Journal name of an
+.Sx \&Rs
+block.
+.Ss \&%N
+Issue number (usually for journals) of an
+.Sx \&Rs
+block.
+.Ss \&%O
+Optional information of an
+.Sx \&Rs
+block.
+.Ss \&%P
+Book or journal page number of an
+.Sx \&Rs
+block.
+.Ss \&%Q
+Institutional author (school, government, etc.) of an
+.Sx \&Rs
+block. Multiple institutional authors should each be accorded their own
+.Sx \&%Q
+line.
+.Ss \&%R
+Technical report name of an
+.Sx \&Rs
+block.
+.Ss \&%T
+Article title of an
+.Sx \&Rs
+block. This macro may also be used in a non-bibliographical context
+when referring to article titles.
+.Ss \&%U
+URI of reference document.
+.Ss \&%V
+Volume number of an
+.Sx \&Rs
+block.
+.Ss \&Ac
+Closes an
+.Sx \&Ao
+block. Does not have any tail arguments.
+.Ss \&Ad
+Address construct: usually in the context of an computational address in
+memory, not a physical (post) address.
.Pp
-.Bl -dash -compact
-.\" LIST-ITEM
-.It
-.Sq \&Fo
+Examples:
+.D1 \&.Ad [0,$]
+.D1 \&.Ad 0x00000000
+.Ss \&An
+Author name. This macro may alternatively accepts the following
+arguments, although these may not be specified along with a parameter:
+.Bl -tag -width 12n -offset indent
+.It Fl split
+Renders a line break before each author listing.
+.It Fl nosplit
+The opposite of
+.Fl split .
+.El
+.Pp
+In the AUTHORS section, the default is not to split the first author
+listing, but all subsequent author listings, whether or not they're
+interspersed by other macros or text, are split. Thus, specifying
+.Fl split
+will cause the first listing also to be split. If not in the AUTHORS
+section, the default is not to split.
+.Pp
+Examples:
+.D1 \&.An -nosplit
+.D1 \&.An J. D. Ullman .
+.Pp
+.Em Remarks :
+the effects of
+.Fl split
+or
+.Fl nosplit
+are re-set when entering the AUTHORS section, so if one specifies
+.Sx \&An Fl nosplit
+in the general document body, it must be re-specified in the AUTHORS
+section.
+.Ss \&Ao
+Begins a block enclosed by angled brackets. Does not have any head
+arguments.
+.Pp
+Examples:
+.D1 \&.Fl -key= \&Ns \&Ao \&Ar val \&Ac
+.Pp
+See also
+.Sx \&Aq .
+.Ss \&Ap
+Inserts an apostrophe without any surrounding white-space. This is
+generally used as a grammatic device when referring to the verb form of
+a function:
+.Bd -literal -offset indent
+\&.Fn execve Ap d
+.Ed
+.Ss \&Aq
+Encloses its arguments in angled brackets.
+.Pp
+Examples:
+.D1 \&.Fl -key= \&Ns \&Aq \&Ar val
+.Pp
+.Em Remarks :
+this macro is often abused for rendering URIs, which should instead use
+.Sx \&Lk
+or
+.Sx \&Mt ,
+or to note pre-processor
+.Dq Li #include
+statements, which should use
+.Sx \&In .
+.Pp
+See also
+.Sx \&Ao .
+.Ss \&Ar
+Command arguments. If an argument is not provided, the string
+.Dq file ...
+is used as a default.
+.Pp
+Examples:
+.D1 \&.Fl o \&Ns \&Ar file1
+.D1 \&.Ar
+.D1 \&.Ar arg1 , arg2 .
+.Ss \&At
+Formats an AT&T version. Accepts at most one parameter:
+.Bl -tag -width 12n -offset indent
+.It Cm v[1-7] | 32v
+A version of
+.At .
+.It Cm V[.[1-4]]?
+A system version of
+.At .
+.El
+.Pp
+Note that these parameters do not begin with a hyphen.
+.Pp
+Examples:
+.D1 \&.At
+.D1 \&.At V.1
+.Pp
+See also
+.Sx \&Bsx ,
+.Sx \&Bx ,
+.Sx \&Dx ,
+.Sx \&Fx ,
+.Sx \&Nx ,
+.Sx \&Ox ,
and
-.Sq \&St
-historically weren't always callable. Both are now correctly callable.
-.\" LIST-ITEM
-.It
-.Sq \&It \-nested
-is assumed for all lists: any list may be nested and
-.Sq \-enum
-lists will restart the sequence only for the sub-list.
-.\" LIST-ITEM
-.It
-.Sq \&It \-column
-syntax where column widths may be preceeded by other arguments (instead
-of proceeded) is not supported.
-.\" LIST-ITEM
+.Sx \&Ux .
+.Ss \&Bc
+Closes a
+.Sx \&Bo
+block. Does not have any tail arguments.
+.Ss \&Bd
+Begins a display block. A display is collection of macros or text which
+may be collectively offset or justified in a manner different from that
+of the enclosing context. By default, the block is preceded by a
+vertical space.
+.Pp
+Each display is associated with a type, which must be one of the
+following arguments:
+.Bl -tag -width 12n -offset indent
+.It Fl ragged
+Only left-justify the block.
+.It Fl unfilled
+Do not justify the block at all.
+.It Fl filled
+Left- and right-justify the block.
+.It Fl literal
+Alias for
+.Fl unfilled .
+.It Fl centered
+Centre-justify each line.
+.El
+.Pp
+The type must be provided first. Secondary arguments are as follows:
+.Bl -tag -width 12n -offset indent
+.It Fl offset Ar width
+Offset by the value of
+.Ar width ,
+which is interpreted as one of the following, specified in order:
+.Bl -item
.It
-The
-.Sq \&At
-macro only accepts a single parameter.
-.\" LIST-ITEM
+As one of the pre-defined strings
+.Ar indent ,
+the width of standard indentation;
+.Ar indent-two ,
+twice
+.Ar indent ;
+.Ar left ,
+which has no effect ;
+.Ar right ,
+which justifies to the right margin; and
+.Ar center ,
+which aligns around an imagined centre axis.
.It
-The system-name macros (
-.Ns Sq \&At ,
-.Sq \&Bsx ,
-.Sq \&Bx ,
-.Sq \&Fx ,
-.Sq \&Nx ,
-.Sq \&Ox ,
-and
-.Sq \&Ux )
-are callable.
-.\" LIST-ITEM
+As a precalculated width for a named macro. The most popular is the
+imaginary macro
+.Ar \&Ds ,
+which resolves to
+.Ar 6n .
.It
-Some manuals use
-.Sq \&Li
-incorrectly by following it with a reserved character and expecting the
-delimiter to render. This is not supported.
-.\" LIST-ITEM
+As a scaling unit following the syntax described in
+.Sx Scaling Widths .
.It
-.Sq \&Cd
-is callable.
+As the calculated string length of the opaque string.
.El
-.\" SECTION
-.Sh SEE ALSO
-.Xr mdoctree 1 ,
-.Xr mdoclint 1 ,
-.Xr mdocterm 1 ,
-.Xr mdoc 3
-.\" SECTION
-.Sh AUTHORS
+.Pp
+If unset, it will revert to the value of
+.Ar 8n
+as described in
+.Sx Scaling Widths .
+.It Fl compact
+Do not assert a vertical space before the block.
+.It Fl file Ar file
+Prepend the file
+.Ar file
+before any text or macros within the block.
+.El
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Bd \-unfilled \-offset two-indent \-compact
+ Hello world.
+\&.Ed
+.Ed
+.Pp
+See also
+.Sx \&D1
+and
+.Sx \&Dl .
+.Ss \&Bf
+.Ss \&Bk
+.Ss \&Bl
+.\" Begins a list composed of one or more list entries. A list entry is
+.\" specified by the
+.\" .Sx \&It
+.\" macro, which consists of a head and optional body. By default, a list
+.\" is preceded by a blank line. A list must specify one of the following
+.\" list types:
+.\" .Bl -tag -width 12n
+.\" .It Fl bullet
+.\" A list offset by a bullet. The head of list entries must be empty.
+.\" List entry bodies are justified after the bullet.
+.\" .It Fl column
+.\" A columnated list. The number of columns is specified as arguments to
+.\" the
+.\" .Sx \&Bl
+.\" macro (the deprecated form of following the invocation of
+.\" .Fl column
+.\" is also accepted). Arguments dictate the width of columns specified in
+.\" list entries. List entry bodies must be left empty. Columns specified
+.\" in the list entry head are justified to their position in the sequence
+.\" of columns.
+.\" .It Fl dash
+.\" A list offset by a dash (hyphen). The head of list entries must be
+.\" empty. List entry bodies are justified past the dash.
+.\" .It Fl diag
+.\" Like
+.\" .Fl inset
+.\" lists, but with additional formatting to the head.
+.\" .It Fl enum
+.\" A list offset by a number indicating list entry position. The head of
+.\" list entries must be empty. List entry bodies are justified past the
+.\" enumeration.
+.\" .It Fl hang
+.\" Like
+.\" .Fl tag ,
+.\" but instead of list bodies justifying to the head on the first line,
+.\" they trail the head text.
+.\" .It Fl hyphen
+.\" Synonym for
+.\" .Fl dash .
+.\" .It Fl inset
+.\" Like
+.\" .Fl tag ,
+.\" but list entry bodies aren't justified.
+.\" .It Fl item
+.\" An un-justified list. This produces blocks of text.
+.\" .It Fl ohang
+.\" List bodies are placed on the line following the head.
+.\" .It Fl tag
+.\" A list offset by list entry heads. List entry bodies are justified
+.\" after the head.
+.\" .El
+.\" .Pp
+.\" More...
+.\" .
+.Ss \&Bo
+Begins a block enclosed by square brackets. Does not have any head
+arguments.
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Bo 1 ,
+\&.Dv BUFSIZ \&Bc
+.Ed
+.Pp
+See also
+.Sx \&Bq .
+.Ss \&Bq
+Encloses its arguments in square brackets.
+.Pp
+Examples:
+.D1 \&.Bq 1 , \&Dv BUFSIZ
+.Pp
+.Em Remarks :
+this macro is sometimes abused to emulate optional arguments for
+commands; the correct macros to use for this purpose are
+.Sx \&Op ,
+.Sx \&Oo ,
+and
+.Sx \&Oc .
+.Pp
+See also
+.Sx \&Bo .
+.Ss \&Brc
+Closes a
+.Sx \&Bro
+block. Does not have any tail arguments.
+.Ss \&Bro
+Begins a block enclosed by curly braces. Does not have any head
+arguments.
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Bro 1 , ... ,
+\&.Va n \&Brc
+.Ed
+.Pp
+See also
+.Sx \&Brq .
+.Ss \&Brq
+Encloses its arguments in curly braces.
+.Pp
+Examples:
+.D1 \&.Brq 1 , ... , \&Va n
+.Pp
+See also
+.Sx \&Bro .
+.Ss \&Bsx
+Format the BSD/OS version provided as an argument, or a default value if
+no argument is provided.
+.Pp
+Examples:
+.D1 \&.Bsx 1.0
+.D1 \&.Bsx
+.Pp
+See also
+.Sx \&At ,
+.Sx \&Bx ,
+.Sx \&Dx ,
+.Sx \&Fx ,
+.Sx \&Nx ,
+.Sx \&Ox ,
+and
+.Sx \&Ux .
+.Ss \&Bt
+Prints
+.Dq is currently in beta test.
+.Ss \&Bx
+Format the BSD version provided as an argument, or a default value if no
+argument is provided.
+.Pp
+Examples:
+.D1 \&.Bx 4.4
+.D1 \&.Bx
+.Pp
+See also
+.Sx \&At ,
+.Sx \&Bsx ,
+.Sx \&Dx ,
+.Sx \&Fx ,
+.Sx \&Nx ,
+.Sx \&Ox ,
+and
+.Sx \&Ux .
+.Ss \&Cd
+Configuration declaration. This denotes strings accepted by
+.Xr config 8 .
+.Pp
+Examples:
+.D1 \&.Cd device le0 at scode?
+.Pp
+.Em Remarks :
+this macro is commonly abused by using quoted literals to retain
+white-space and align consecutive
+.Sx \&Cd
+declarations. This practise is discouraged.
+.Ss \&Cm
+Command modifiers. Useful when specifying configuration options or
+keys.
+.Pp
+Examples:
+.D1 \&.Cm ControlPath
+.D1 \&.Cm ControlMaster
+.Pp
+See also
+.Sx \&Fl .
+.Ss \&D1
+One-line indented display. This is formatted by the default rules and
+is useful for simple indented statements. It is followed by a newline.
+.Pp
+Examples:
+.D1 \&.D1 \&Fl abcdefgh
+.Pp
+See also
+.Sx \&Bd
+and
+.Sx \&Dl .
+.Ss \&Db
+.Ss \&Dc
+Closes a
+.Sx \&Do
+block. Does not have any tail arguments.
+.Ss \&Dd
+Document date. This is the mandatory first macro of any
+.Nm
+manual. Its calling syntax is as follows:
+.Pp
+.D1 \. Ns Sx \&Dd Cm date
+.Pp
The
+.Cm date
+field may be either
+.Ar $\&Mdocdate$ ,
+which signifies the current manual revision date dictated by
+.Xr cvs 1 ,
+or instead a valid canonical date as specified by
+.Sx Dates .
+If a date does not conform, the current date is used instead.
+.Pp
+Examples:
+.D1 \&.Dd $\&Mdocdate$
+.D1 \&.Dd $\&Mdocdate: July 21 2007$
+.D1 \&.Dd July 21, 2007
+.Pp
+See also
+.Sx \&Dt
+and
+.Sx \&Os .
+.Ss \&Dl
+One-line intended display. This is formatted as literal text and is
+useful for commands and invocations. It is followed by a newline.
+.Pp
+Examples:
+.D1 \&.Dl % mandoc mdoc.7 | less
+.Pp
+See also
+.Sx \&Bd
+and
+.Sx \&D1 .
+.Ss \&Do
+Begins a block enclosed by double quotes. Does not have any head
+arguments.
+.Pp
+Examples:
+.D1 \&.D1 \&Do April is the cruellest month \&Dc \e(em T.S. Eliot
+.Pp
+See also
+.Sx \&Dq .
+.Ss \&Dq
+Encloses its arguments in double quotes.
+.Pp
+Examples:
+.Bd -literal -offset indent -compact
+\&.Dq April is the cruellest month
+\e(em T.S. Eliot
+.Ed
+.Pp
+See also
+.Sx \&Do .
+.Ss \&Dt
+Document title. This is the mandatory second macro of any
+.Nm
+file. Its calling syntax is as follows:
+.Pp
+.D1 \. Ns Sx \&Dt Cm title section Op Cm volume | arch
+.Pp
+Its arguments are as follows:
+.Bl -tag -width Ds -offset Ds
+.It Cm title
+The document's title (name). This should be capitalised and is
+required.
+.It Cm section
+The manual section. This may be one of
+.Ar 1
+.Pq utilities ,
+.Ar 2
+.Pq system calls ,
+.Ar 3
+.Pq libraries ,
+.Ar 3p
+.Pq Perl libraries ,
+.Ar 4
+.Pq devices ,
+.Ar 5
+.Pq file formats ,
+.Ar 6
+.Pq games ,
+.Ar 7
+.Pq miscellaneous ,
+.Ar 8
+.Pq system utilities ,
+.Ar 9
+.Pq kernel functions ,
+.Ar X11
+.Pq X Window System ,
+.Ar X11R6
+.Pq X Window System ,
+.Ar unass
+.Pq unassociated ,
+.Ar local
+.Pq local system ,
+.Ar draft
+.Pq draft manual ,
+or
+.Ar paper
+.Pq paper .
+It is also required and should correspond to the manual's filename
+suffix.
+.It Cm volume
+This overrides the volume inferred from
+.Ar section .
+This field is optional, and if specified, must be one of
+.Ar USD
+.Pq users' supplementary documents ,
+.Ar PS1
+.Pq programmers' supplementary documents ,
+.Ar AMD
+.Pq administrators' supplementary documents ,
+.Ar SMM
+.Pq system managers' manuals ,
+.Ar URM
+.Pq users' reference manuals ,
+.Ar PRM
+.Pq programmers' reference manuals ,
+.Ar KM
+.Pq kernel manuals ,
+.Ar IND
+.Pq master index ,
+.Ar MMI
+.Pq master index ,
+.Ar LOCAL
+.Pq local manuals ,
+.Ar LOC
+.Pq local manuals ,
+or
+.Ar CON
+.Pq contributed manuals .
+.It Cm arch
+This specifies a specific relevant architecture. If
+.Cm volume
+is not provided, it may be used in its place, else it may be used
+subsequent that. It, too, is optional. It must be one of
+.Ar alpha ,
+.Ar amd64 ,
+.Ar amiga ,
+.Ar arc ,
+.Ar arm ,
+.Ar armish ,
+.Ar aviion ,
+.Ar hp300 ,
+.Ar hppa ,
+.Ar hppa64 ,
+.Ar i386 ,
+.Ar landisk ,
+.Ar loongson ,
+.Ar luna88k ,
+.Ar mac68k ,
+.Ar macppc ,
+.Ar mvme68k ,
+.Ar mvme88k ,
+.Ar mvmeppc ,
+.Ar pmax ,
+.Ar sgi ,
+.Ar socppc ,
+.Ar sparc ,
+.Ar sparc64 ,
+.Ar sun3 ,
+.Ar vax ,
+or
+.Ar zaurus .
+.El
+.Pp
+Examples:
+.D1 \&.Dt FOO 1
+.D1 \&.Dt FOO 4 KM
+.D1 \&.Dt FOO 9 i386
+.D1 \&.Dt FOO 9 KM i386
+.Pp
+See also
+.Sx \&Dd
+and
+.Sx \&Os .
+.Ss \&Dv
+Defined variables such as preprocessor constants.
+.Pp
+Examples:
+.D1 \&.Dv BUFSIZ
+.D1 \&.Dv STDOUT_FILENO
+.Pp
+See also
+.Sx \&Er .
+.Ss \&Dx
+Format the DragonFly BSD version provided as an argument, or a default
+value if no argument is provided.
+.Pp
+Examples:
+.D1 \&.Dx 2.4.1
+.D1 \&.Dx
+.Pp
+See also
+.Sx \&At ,
+.Sx \&Bsx ,
+.Sx \&Bx ,
+.Sx \&Fx ,
+.Sx \&Nx ,
+.Sx \&Ox ,
+and
+.Sx \&Ux .
+.Ss \&Ec
+.Ss \&Ed
+.Ss \&Ef
+.Ss \&Ek
+.Ss \&El
+.Ss \&Em
+Denotes text that should be emphasised. Note that this is a
+presentation term and should not be used for stylistically decorating
+technical terms.
+.Pp
+Examples:
+.D1 \&.Em Warnings!
+.D1 \&.Em Remarks :
+.Ss \&En
+.Ss \&Eo
+.Ss \&Er
+Display error constants.
+.Pp
+Examples:
+.D1 \&.Er EPERM
+.D1 \&.Er ENOENT
+.Pp
+See also
+.Sx \&Dv .
+.Ss \&Es
+.Ss \&Ev
+Environmental variables such as those specified in
+.Xr environ 7 .
+.Pp
+Examples:
+.D1 \&.Ev DISPLAY
+.D1 \&.Ev PATH
+.Ss \&Ex
+Inserts text regarding a utility's exit values. This macro must have
+first the
+.Fl std
+argument specified, then an optional
+.Ar utility .
+If
+.Ar utility
+is not provided, the document's name as stipulated in
+.Sx \&Nm
+is provided.
+.Ss \&Fa
+.Ss \&Fc
+.Ss \&Fd
+.Ss \&Fl
+Command-line flag. Used when listing arguments to command-line
+utilities. Prints a fixed-width hyphen
+.Sq \-
+directly followed by each argument. If no arguments are provided, a hyphen is
+printed followed by a space. If the argument is a macro, a hyphen is
+prefixed to the subsequent macro output.
+.Pp
+Examples:
+.D1 \&.Fl a b c
+.D1 \&.Fl \&Pf a b
+.D1 \&.Fl
+.D1 \&.Op \&Fl o \&Ns \&Ar file
+.Pp
+See also
+.Sx \&Cm .
+.Ss \&Fn
+.Ss \&Fo
+.Ss \&Fr
+.Ss \&Ft
+.Ss \&Fx
+Format the FreeBSD version provided as an argument, or a default value
+if no argument is provided.
+.Pp
+Examples:
+.D1 \&.Fx 7.1
+.D1 \&.Fx
+.Pp
+See also
+.Sx \&At ,
+.Sx \&Bsx ,
+.Sx \&Bx ,
+.Sx \&Dx ,
+.Sx \&Nx ,
+.Sx \&Ox ,
+and
+.Sx \&Ux .
+.Ss \&Hf
+.Ss \&Ic
+.Ss \&In
+.Ss \&It
+.Ss \&Lb
+.Ss \&Li
+.Ss \&Lk
+Format a hyperlink. The calling syntax is as follows:
+.Pp
+.D1 \. Ns Sx \&Lk Cm uri Op Cm name
+.Pp
+Examples:
+.D1 \&.Lk http://bsd.lv "The BSD.lv Project"
+.D1 \&.Lk http://bsd.lv
+.Pp
+See also
+.Sx \&Mt .
+.Ss \&Lp
+.Ss \&Ms
+.Ss \&Mt
+.Ss \&Nd
+.Ss \&Nm
+.Ss \&No
+.Ss \&Ns
+.Ss \&Nx
+Format the NetBSD version provided as an argument, or a default value if
+no argument is provided.
+.Pp
+Examples:
+.D1 \&.Nx 5.01
+.D1 \&.Nx
+.Pp
+See also
+.Sx \&At ,
+.Sx \&Bsx ,
+.Sx \&Bx ,
+.Sx \&Dx ,
+.Sx \&Fx ,
+.Sx \&Ox ,
+and
+.Sx \&Ux .
+.Ss \&Oc
+.Ss \&Oo
+.Ss \&Op
+.Ss \&Os
+Document operating system version. This is the mandatory third macro of
+any
.Nm
-utility was written by
-.An Kristaps Dzonsons Aq kristaps@openbsd.org .
-.\" SECTION
-.Sh CAVEATS
-There are several ambiguous parts of mdoc.
+file. Its calling syntax is as follows:
+.Pp
+.D1 \. Ns Sx \&Os Op Cm system
+.Pp
+The optional
+.Cm system
+parameter specifies the relevant operating system or environment. Left
+unspecified, it defaults to the local operating system version. This is
+the suggested form.
+.Pp
+Examples:
+.D1 \&.Os
+.D1 \&.Os KTH/CSC/TCS
+.D1 \&.Os BSD 4.3
+.Pp
+See also
+.Sx \&Dd
+and
+.Sx \&Dt .
+.Ss \&Ot
+Unknown usage.
+.Pp
+.Em Remarks :
+this macro has been deprecated.
+.Ss \&Ox
+Format the OpenBSD version provided as an argument, or a default value
+if no argument is provided.
+.Pp
+Examples:
+.D1 \&.Ox 4.5
+.D1 \&.Ox
+.Pp
+See also
+.Sx \&At ,
+.Sx \&Bsx ,
+.Sx \&Bx ,
+.Sx \&Dx ,
+.Sx \&Fx ,
+.Sx \&Nx ,
+and
+.Sx \&Ux .
+.Ss \&Pa
+.Ss \&Pc
+.Ss \&Pf
+.Ss \&Po
+.Ss \&Pp
+.Ss \&Pq
+.Ss \&Qc
+.Ss \&Ql
+.Ss \&Qo
+.Ss \&Qq
+.Ss \&Re
+Closes a
+.Sx \&Rs
+block. Does not have any tail arguments.
+.Ss \&Rs
+Begins a bibliographic
+.Pq Dq reference
+block. Does not have any head arguments. The block macro may only
+contain
+.Sx \&%A ,
+.Sx \&%B ,
+.Sx \&%C ,
+.Sx \&%D ,
+.Sx \&%I ,
+.Sx \&%J ,
+.Sx \&%N ,
+.Sx \&%O ,
+.Sx \&%P ,
+.Sx \&%Q ,
+.Sx \&%R ,
+.Sx \&%T ,
+and
+.Sx \&%V
+child macros (at least one must be specified).
+.Pp
+Examples:
+.Bd -literal -offset indent -compact
+\&.Rs
+\&.%A J. E. Hopcroft
+\&.%A J. D. Ullman
+\&.%B Introduction to Automata Theory, Languages, and Computation
+\&.%I Addison-Wesley
+\&.%C Reading, Massachusettes
+\&.%D 1979
+\&.Re
+.Ed
+.Pp
+If an
+.Sx \&Rs
+block is used within a SEE ALSO section, a vertical space is asserted
+before the rendered output, else the block continues on the current
+line.
+.Ss \&Rv
+.Ss \&Sc
+.Ss \&Sh
+.Ss \&Sm
+.Ss \&So
+.Ss \&Sq
+.Ss \&Ss
+.Ss \&St
+.Ss \&Sx
+.Ss \&Sy
+.Ss \&Tn
+.Ss \&Ud
+.Ss \&Ux
+Format the UNIX name. Accepts no argument.
+.Pp
+Examples:
+.D1 \&.Ux
+.Pp
+See also
+.Sx \&At ,
+.Sx \&Bsx ,
+.Sx \&Bx ,
+.Sx \&Dx ,
+.Sx \&Fx ,
+.Sx \&Nx ,
+and
+.Sx \&Ox .
+.Ss \&Va
+.Ss \&Vt
+A variable type. This is also used for indicating global variables in the
+SYNOPSIS section, in which case a variable name is also specified. Note that
+it accepts
+.Sx Block partial-implicit
+syntax when invoked as the first macro in the SYNOPSIS section, else it
+accepts ordinary
+.Sx In-line
+syntax.
+.Pp
+Note that this should not be confused with
+.Sx \&Ft ,
+which is used for function return types.
+.Pp
+Examples:
+.D1 \&.Vt unsigned char
+.D1 \&.Vt extern const char * const sys_signame[] ;
+.Pp
+See also
+.Sx \&Ft
+and
+.Sx \&Va .
+.Ss \&Xc
+Close a scope opened by
+.Sx \&Xo .
+.Ss \&Xo
+Open an extension scope. This macro originally existed to extend the
+9-argument limit of troff; since this limit has been lifted, the macro
+has been deprecated.
+.Ss \&Xr
+Link to another manual
+.Pq Qq cross-reference .
+Its calling syntax is
+.Pp
+.D1 \. Ns Sx \&Xr Cm name section
+.Pp
+The
+.Cm name
+and
+.Cm section
+are the name and section of the linked manual. If
+.Cm section
+is followed by non-punctuation, an
+.Sx \&Ns
+is inserted into the token stream. This behaviour is for compatibility
+with
+.Xr groff 1 .
+.Pp
+Examples:
+.D1 \&.Xr mandoc 1
+.D1 \&.Xr mandoc 1 ;
+.D1 \&.Xr mandoc 1 \&Ns s behaviour
+.Ss \&br
+.Ss \&sp
+.Sh COMPATIBILITY
+This section documents compatibility between mandoc and other other
+troff implementations, at this time limited to GNU troff
+.Pq Qq groff .
+The term
+.Qq historic groff
+refers to groff versions before the
+.Pa doc.tmac
+file re-write
+.Pq somewhere between 1.15 and 1.19 .
+.Pp
+Heirloom troff, the other significant troff implementation accepting
+\-mdoc, is similar to historic groff.
.Pp
.Bl -dash -compact
-.\" LIST-ITEM
.It
-.Sq \&Fa
-should be
-.Sq \&Va
-as function arguments are variables.
-.\" LIST-ITEM
+The comment syntax
+.Sq \e."
+is no longer accepted.
+.It
+In groff, the
+.Sx \&Pa
+macro does not format its arguments when used in the FILES section under
+certain list types. mandoc does.
.It
-.Sq \&Ft
-should be
-.Sq \&Vt
-as function return types are still types. Furthermore, the
-.Sq \&Ft
-should be removed and
-.Sq \&Fo ,
-which ostensibly follows it, should follow the same convention as
-.Sq \&Va .
-.\" LIST-ITEM
+Historic groff does not print a dash for empty
+.Sx \&Fl
+arguments. mandoc and newer groff implementations do.
.It
-.Sq \&Va
-should formalise that only one or two arguments are acceptable: a
-variable name and optional, preceeding type.
-.\" LIST-ITEM
+groff behaves irregularly when specifying
+.Sq \ef
+.Sx Text Decoration
+within line-macro scopes. mandoc follows a consistent system.
.It
-.Sq \&Fd
-is ambiguous. It's commonly used to indicate an include file in the
-synopsis section.
-.Sq \&In
-should be used, instead.
-.\" LIST-ITEM
+In mandoc, negative scaling units are truncated to zero; groff would
+move to prior lines. Furthermore, the
+.Sq f
+scaling unit, while accepted, is rendered as the default unit.
.It
-Only the
-.Sq \-literal
-argument to
-.Sq \&Bd
-makes sense. The remaining ones should be removed.
-.\" LIST-ITEM
+In quoted literals, groff allowed pair-wise double-quotes to produce a
+standalone double-quote in formatted output. This idiosyncratic
+behaviour is not applicable in mandoc.
.It
-The
-.Sq \&Xo
+Display types
+.Sx \&Bd
+.Fl center
and
-.Sq \&Xc
-macros should be deprecated.
-.\" LIST-ITEM
+.Fl right
+are aliases for
+.Fl left
+in manodc. Furthermore, the
+.Fl file Ar file
+argument is ignored. Lastly, since text is not right-justified in
+mandoc (or even groff),
+.Fl ragged
+and
+.Fl filled
+are aliases, as are
+.Fl literal
+and
+.Fl unfilled .
.It
-The
-.Sq \&Dt
-macro lacks clarity. It should be absolutely clear which title will
-render when formatting the manual page.
-.\" LIST-ITEM
+In mandoc, blocks of whitespace are stripped from both macro and
+free-form text lines (except when in literal mode); groff would retain
+whitespace in free-form text lines.
+.It
+Historic groff has many un-callable macros. Most of these (excluding
+some block-level macros) are now callable.
+.It
+The vertical bar
+.Sq \(ba
+made historic groff
+.Qq go orbital
+but has been a proper delimiter since then.
.It
-A
-.Sq \&Lx
-should be provided for Linux (\(`a la
-.Sq \&Ox ,
-.Sq \&Nx
-etc.).
+.Sx \&It Fl nested
+is assumed for all lists (it wasn't in historic groff): any list may be
+nested and
+.Fl enum
+lists will restart the sequence only for the sub-list.
+.It
+Some manuals use
+.Sx \&Li
+incorrectly by following it with a reserved character and expecting the
+delimiter to render. This is not supported in mandoc.
+.It
+In groff, the
+.Sx \&Fo
+macro only produces the first parameter. This is not the case in
+mandoc.
+.It
+In groff, the
+.Sx \&Cd ,
+.Sx \&Er ,
+and
+.Sx \&Ex
+macros were stipulated only to occur in certain manual sections. mandoc
+does not have these restrictions.
.El
+.Sh SEE ALSO
+.Xr mandoc 1 ,
+.Xr mandoc_char 7
+.Sh AUTHORS
+The
+.Nm
+reference was written by
+.An Kristaps Dzonsons Aq kristaps@bsd.lv .
+.\"
+.\" XXX: this really isn't the place for these caveats.
+.\" .
+.\" .
+.\" .Sh CAVEATS
+.\" There are many ambiguous parts of mdoc.
+.\" .
+.\" .Pp
+.\" .Bl -dash -compact
+.\" .It
+.\" .Sq \&Fa
+.\" should be
+.\" .Sq \&Va
+.\" as function arguments are variables.
+.\" .It
+.\" .Sq \&Ft
+.\" should be
+.\" .Sq \&Vt
+.\" as function return types are still types. Furthermore, the
+.\" .Sq \&Ft
+.\" should be removed and
+.\" .Sq \&Fo ,
+.\" which ostensibly follows it, should follow the same convention as
+.\" .Sq \&Va .
+.\" .It
+.\" .Sq \&Va
+.\" should formalise that only one or two arguments are acceptable: a
+.\" variable name and optional, preceding type.
+.\" .It
+.\" .Sq \&Fd
+.\" is ambiguous. It's commonly used to indicate an include file in the
+.\" synopsis section.
+.\" .Sq \&In
+.\" should be used, instead.
+.\" .It
+.\" Only the
+.\" .Sq \-literal
+.\" argument to
+.\" .Sq \&Bd
+.\" makes sense. The remaining ones should be removed.
+.\" .It
+.\" The
+.\" .Sq \&Xo
+.\" and
+.\" .Sq \&Xc
+.\" macros should be deprecated.
+.\" .It
+.\" The
+.\" .Sq \&Dt
+.\" macro lacks clarity. It should be absolutely clear which title will
+.\" render when formatting the manual page.
+.\" .It
+.\" A
+.\" .Sq \&Lx
+.\" should be provided for Linux (\(`a la
+.\" .Sq \&Ox ,
+.\" .Sq \&Nx
+.\" etc.).
+.\" .It
+.\" There's no way to refer to references in
+.\" .Sq \&Rs/Re
+.\" blocks.
+.\" .It
+.\" The \-split and \-nosplit dictates via
+.\" .Sq \&An
+.\" are re-set when entering and leaving the AUTHORS section.
+.\" .El
+.\" .
git.ckatri.com / mandoc.git / blobdiff