-.\" $Id: mdoc.7,v 1.17 2009/03/26 23:01:26 kristaps Exp $
+.\" $Id: mdoc.7,v 1.59 2009/08/20 13:32:09 kristaps Exp $
.\"
-.\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@openbsd.org>
+.\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
.\"
.\" 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 26 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: August 20 2009 $
+.Dt MDOC 7
.Os
-.\" SECTION
+.
+.
.Sh NAME
.Nm mdoc
.Nd mdoc language reference
-.\" SECTION
+.
+.
.Sh DESCRIPTION
The
.Nm mdoc
-language is used to format
-.Bx
+language is used to format
+.Bx
.Ux
-manuals. In this reference document, we describe the syntax, ontology
-and structure of the
-.Nm
-language.
-.\" PARAGRAPH
+manuals. In this reference document, we describe its syntax, structure,
+and usage. Our reference implementation is
+.Xr mandoc 1 .
+The
+.Sx COMPATIBILITY
+section describes compatibility with
+.Xr groff 1 .
+.
.Pp
An
.Nm
document follows simple rules: lines beginning with the control
-character
+character
.Sq \.
are parsed for macros. Other lines are interpreted within the scope of
prior macros:
-.Bd -literal -offset XXX
+.Bd -literal -offset indent
\&.Sh Macro lines change control state.
Other lines are interpreted within the current state.
.Ed
-.\" SECTION
-.Sh INPUT ENCODING
+.
+.
+.Sh LANGUAGE SYNTAX
.Nm
documents may contain only graphable 7-bit ASCII 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
+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
+.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
+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
+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.
-.Pp
-Characters may alternatively be escaped by a slash-asterisk,
-.Sq \e* ,
-with the same combinations as described above. This form is deprecated.
-.Pp
-The following is a table of all available escapes.
-.Pp
-Grammatic:
-.Bl -tag -width 12n -offset "XXXX" -compact
-.It \e(em
+or a single one-character sequence. See
+.Xr mandoc_char 7
+for a complete list. Examples include
+.Sq \e(em
.Pq em-dash
-.It \e(en
-.Pq en-dash
-.It \e-
-.Pq hyphen
-.It \e\e
-.Pq back-slash
-.It \e'
-.Pq apostrophe
-.It \e`
-.Pq back-tick
-.It \e
-.Pq space
-.It \e.
-.Pq period
-.It \e(r!
-.Pq upside-down exclamation
-.It \e(r?
-.Pq upside-down question
-.El
-.\" PARAGRAPH
-.Pp
-Enclosures:
-.Bl -tag -width 12n -offset "XXXX" -compact
-.It \e(lh
-.Pq left hand
-.It \e(rh
-.Pq right hand
-.It \e(Fo
-.Pq left guillemet
-.It \e(Fc
-.Pq right guillemet
-.It \e(fo
-.Pq left guilsing
-.It \e(fc
-.Pq right guilsing
-.It \e(rC
-.Pq right brace
-.It \e(lC
-.Pq left brace
-.It \e(ra
-.Pq right angle
-.It \e(la
-.Pq left angle
-.It \e(rB
-.Pq right bracket
-.It \e(lB
-.Pq left bracket
-.It \eq
-.Pq double-quote
-.It \e(lq
-.Pq left double-quote
-.It \e(Lq
-.Pq left double-quote, deprecated
-.It \e(rq
-.Pq right double-quote
-.It \e(Rq
-.Pq right double-quote, deprecated
-.It \e(oq
-.Pq left single-quote
-.It \e(aq
-.Pq right single-quote
-.It \e(Bq
-.Pq right low double-quote
-.It \e(bq
-.Pq right low single-quote
-.El
-.\" PARAGRAPH
-.Pp
-Indicatives:
-.Bl -tag -width 12n -offset "XXXX" -compact
-.It \e(<-
-.Pq left arrow
-.It \e(->
-.Pq right arrow
-.It \e(ua
-.Pq up arrow
-.It \e(da
-.Pq down arrow
-.It \e(<>
-.Pq left-right arrow
-.It \e(lA
-.Pq left double-arrow
-.It \e(rA
-.Pq right double-arrow
-.It \e(uA
-.Pq up double-arrow
-.It \e(dA
-.Pq down double-arrow
-.It \e(hA
-.Pq left-right double-arrow
-.El
-.\" PARAGRAPH
-.Pp
-Mathematical:
-.Bl -tag -width 12n -offset "XXXX" -compact
-.It \e(es
-.Pq empty set
-.It \e(ca
-.Pq intersection
-.It \e(cu
-.Pq union
-.It \e(gr
-.Pq gradient
-.It \e(pd
-.Pq partial differential
-.It \e(ap
-.Pq similarity
-.It \e(=)
-.Pq proper superset
-.It \e((=
-.Pq proper subset
-.It \e(eq
-.Pq equals
-.It \e(di
-.Pq division
-.It \e(mu
-.Pq multiplication
-.It \e(pl
-.Pq addition
-.It \e(nm
-.Pq not element
-.It \e(mo
-.Pq element
-.It \e(Im
-.Pq imaginary
-.It \e(Re
-.Pq real
-.It \e(Ah
-.Pq aleph
-.It \e(te
-.Pq existential quantifier
-.It \e(fa
-.Pq universal quantifier
-.It \e(AN
-.Pq logical AND
-.It \e(OR
-.Pq logical OR
-.It \e(no
-.Pq logical NOT
-.It \e(st
-.Pq such that
-.It \e(tf
-.Pq therefore
-.It \e(~~
-.Pq approximate
-.It \e(~=
-.Pq approximately equals
-.It \e(=~
-.Pq congruent
-.It \e(Gt
-.Pq greater-than, deprecated
-.It \e(Lt
-.Pq less-than, deprecated
-.It \e(<=
-.Pq less-than-equal
-.It \e(Le
-.Pq less-than-equal, deprecated
-.It \e(>=
-.Pq greater-than-equal
-.It \e(Ge
-.Pq greater-than-equal
-.It \e(==
-.Pq equal
-.It \e(!=
-.Pq not equal
-.It \e(Ne
-.Pq not equal, deprecated
-.It \e(if
-.Pq infinity
-.It \e(If
-.Pq infinity, deprecated
-.It \e(na
-.Pq NaN , an extension
-.It \e(Na
-.Pq NaN, deprecated
-.It \e(+-
-.Pq plus-minus
-.It \e(Pm
-.Pq plus-minus, deprecated
-.It \e(**
-.Pq asterisk
-.El
-.\" PARAGRAPH
-.Pp
-Ligatures:
-.Bl -tag -width 12n -offset "XXXX" -compact
-.It \e(ss
-.Pq German eszett
-.It \e(AE
-.Pq upper-case AE
-.It \e(ae
-.Pq lower-case AE
-.It \e(OE
-.Pq upper-case OE
-.It \e(oe
-.Pq lower-case OE
-.It \e(ff
-.Pq ff ligature
-.It \e(fi
-.Pq fi ligature
-.It \e(fl
-.Pq fl ligature
-.It \e(Fi
-.Pq ffi ligature
-.It \e(Fl
-.Pq ffl ligature
-.El
-.\" PARAGRAPH
-.Pp
-Diacritics and letters:
-.Bl -tag -width 12n -offset "XXXX" -compact
-.It \e(ga
-.Pq grave accent
-.It \e(aa
-.Pq accute accent
-.It \e(a"
-.Pq umlaut accent
-.It \e(ad
-.Pq dieresis accent
-.It \e(a~
-.Pq tilde accent
-.It \e(a^
-.Pq circumflex accent
-.It \e(ac
-.Pq cedilla accent
-.It \e(ad
-.Pq dieresis accent
-.It \e(ah
-.Pq caron accent
-.It \e(ao
-.Pq ring accent
-.It \e(ho
-.Pq hook accent
-.It \e(ab
-.Pq breve accent
-.It \e(a-
-.Pq macron accent
-.It \e(-D
-.Pq upper-case eth
-.It \e(Sd
-.Pq lower-case eth
-.It \e(TP
-.Pq upper-case thorn
-.It \e(Tp
-.Pq lower-case thorn
-.It \e('A
-.Pq upper-case acute A
-.It \e('E
-.Pq upper-case acute E
-.It \e('I
-.Pq upper-case acute I
-.It \e('O
-.Pq upper-case acute O
-.It \e('U
-.Pq upper-case acute U
-.It \e('a
-.Pq lower-case acute a
-.It \e('e
-.Pq lower-case acute e
-.It \e('i
-.Pq lower-case acute i
-.It \e('o
-.Pq lower-case acute o
-.It \e('u
-.Pq lower-case acute u
-.It \e(`A
-.Pq upper-case grave A
-.It \e(`E
-.Pq upper-case grave E
-.It \e(`I
-.Pq upper-case grave I
-.It \e(`O
-.Pq upper-case grave O
-.It \e(`U
-.Pq upper-case grave U
-.It \e(`a
-.Pq lower-case grave a
-.It \e(`e
-.Pq lower-case grave e
-.It \e(`i
-.Pq lower-case grave i
-.It \e(`o
-.Pq lower-case grave o
-.It \e(`u
-.Pq lower-case grave u
-.It \e(~A
-.Pq upper-case tilde A
-.It \e(~N
-.Pq upper-case tilde N
-.It \e(~O
-.Pq upper-case tilde O
-.It \e(~a
-.Pq lower-case tilde a
-.It \e(~n
-.Pq lower-case tilde n
-.It \e(~o
-.Pq lower-case tilde o
-.It \e(:A
-.Pq upper-case dieresis A
-.It \e(:E
-.Pq upper-case dieresis E
-.It \e(:I
-.Pq upper-case dieresis I
-.It \e(:O
-.Pq upper-case dieresis O
-.It \e(:U
-.Pq upper-case dieresis U
-.It \e(:a
-.Pq lower-case dieresis a
-.It \e(:e
-.Pq lower-case dieresis e
-.It \e(:i
-.Pq lower-case dieresis i
-.It \e(:o
-.Pq lower-case dieresis o
-.It \e(:u
-.Pq lower-case dieresis u
-.It \e(:y
-.Pq lower-case dieresis y
-.It \e(^A
-.Pq upper-case circumflex A
-.It \e(^E
-.Pq upper-case circumflex E
-.It \e(^I
-.Pq upper-case circumflex I
-.It \e(^O
-.Pq upper-case circumflex O
-.It \e(^U
-.Pq upper-case circumflex U
-.It \e(^a
-.Pq lower-case circumflex a
-.It \e(^e
-.Pq lower-case circumflex e
-.It \e(^i
-.Pq lower-case circumflex i
-.It \e(^o
-.Pq lower-case circumflex o
-.It \e(^u
-.Pq lower-case circumflex u
-.It \e(,C
-.Pq upper-case cedilla C
-.It \e(,c
-.Pq lower-case cedilla c
-.It \e(/L
-.Pq upper-case stroke L
-.It \e(/l
-.Pq lower-case stroke l
-.It \e(/O
-.Pq upper-case stroke O
-.It \e(/o
-.Pq lower-case stroke o
-.It \e(oA
-.Pq upper-case ring A
-.It \e(oa
-.Pq lower-case ring a
-.El
-.\" PARAGRAPH
-.Pp
-Monetary:
-.Bl -tag -width 12n -offset "XXXX" -compact
-.It \e(Cs
-.Pq Scandinavian
-.It \e(Do
-.Pq dollar
-.It \e(Po
-.Pq pound
-.It \e(Ye
-.Pq yen
-.It \e(Fn
-.Pq florin
-.It \e(ct
-.Pq cent
-.El
-.\" PARAGRAPH
-.Pp
-Special symbols:
-.Bl -tag -width 12n -offset "XXXX" -compact
-.It \e(de
-.Pq degree
-.It \e(ps
-.Pq paragraph
-.It \e(sc
-.Pq section
-.It \e(dg
-.Pq dagger
-.It \e(dd
-.Pq double dagger
-.It \e(ci
-.Pq circle
-.It \e(ba
-.Pq bar
-.It \e(bb
-.Pq broken bar
-.It \e(Ba
-.Pq bar, deprecated
-.It \e(co
-.Pq copyright
-.It \e(rg
-.Pq registered
-.It \e(tm
-.Pq trademarked
-.It \e&
-.Pq non-breaking space
-.It \ee
-.Pq escape
-.It \e(Am
-.Pq ampersand, deprecated
-.El
-.\" SECTION
-.Sh STRUCTURE
-Macros are classified in an ontology described by their scope rules.
-Some macros are allowed to deviate from their classifications to
-preserve backward-compatibility with old macro combinations still found
-in the manual corpus. These are specifically noted on a per-macro
-basis.
-.\" 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
-.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
-.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.
-.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 two or 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
+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), or P and R
+(Roman, or reset). This form is not recommended for
+.Nm ,
+which encourages semantic, not presentation, 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
-.\" 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
+.
+.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
-.\" 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
+In free-form mode, quotes are regarded as opaque text.
+.
+.
+.Sh MANUAL STRUCTURE
+Each
+.Nm
+document must begin with a document prologue, containing, in order,
+.Sq \&Dd ,
+.Sq \&Dt ,
+and
+.Sq \&Os ,
+then the NAME section containing at least one
+.Sq \&Nm
+followed by
+.Sq \&Nd :
+.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
+Subsequent SYNOPSIS and DESCRIPTION sections are strongly encouraged,
+but non-compulsory.
+.
+.
+.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,
+.Sq \&.Pp
+and
+.Sq \&.\ \ \ \&Pp
+are equivalent. Macro names are two or three characters in length.
+.
+.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
-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
-.Ed
-.\" PARAGRAPH
+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
-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
+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
+.Pq Sq \&Bf
+contains a head.
+.Bd -literal -offset indent
+\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB
+\(lBbody...\(rB
+\&.Yc
.Ed
-.\"
-.Sh MACROS
-This section contains a complete list of all
-.Nm
-macros, arranged ontologically. A
-.Qq callable
-macro is invoked subsequent to the initial macro-line macro. A
-.Qq parsable
-macro may be followed by further (ostensibly callable) macros.
-.\" SUB-SECTION
+.
+.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 \&Bd Ta \&No Ta \&No Ta closed by \&Ed
+.It \&Bf Ta \&No Ta \&No Ta closed by \&Ef
+.It \&Bk Ta \&No Ta \&No Ta closed by \&Ek
+.It \&Bl Ta \&No Ta \&No Ta closed by \&El
+.It \&Ed Ta \&No Ta \&No Ta opened by \&Bd
+.It \&Ef Ta \&No Ta \&No Ta opened by \&Bf
+.It \&Ek Ta \&No Ta \&No Ta opened by \&Bk
+.It \&El Ta \&No Ta \&No Ta opened by \&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
-.Sq \&.It \-bullet ,
-.Sq \-hyphen ,
+.Sq \&It \-bullet ,
+.Sq \-hyphen ,
.Sq \-dash ,
.Sq \-enum ,
-.Sq \-item
+.Sq \-item
.Pc
-don't have heads.
+don't have heads, while
+.Sq \&It \-column
+may have 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 \&It Ta \&No Ta Yes Ta closed by \&It, \&El
+.It \&Nd Ta \&No Ta \&No Ta closed by \&Sh
+.It \&Sh Ta \&No Ta \&No Ta closed by \&Sh
+.It \&Ss Ta \&No Ta \&No Ta closed by \&Sh, \&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
+.Pq So \&Fo Sc , So \&Eo Sc
+and/or tail
+.Pq So \&Ec Sc .
+.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 \&Ac Ta Yes Ta Yes Ta opened by \&Ao
+.It \&Ao Ta Yes Ta Yes Ta closed by \&Ac
+.It \&Bc Ta Yes Ta Yes Ta closed by \&Bo
+.It \&Bo Ta Yes Ta Yes Ta opened by \&Bc
+.It \&Brc Ta Yes Ta Yes Ta opened by \&Bro
+.It \&Bro Ta Yes Ta Yes Ta closed by \&Brc
+.It \&Dc Ta Yes Ta Yes Ta opened by \&Do
+.It \&Do Ta Yes Ta Yes Ta closed by \&Dc
+.It \&Ec Ta Yes Ta Yes Ta opened by \&Eo
+.It \&Eo Ta Yes Ta Yes Ta closed by \&Ec
+.It \&Fc Ta Yes Ta Yes Ta opened by \&Fo
+.It \&Fo Ta \&No Ta \&No Ta closed by \&Fc
+.It \&Oc Ta Yes Ta Yes Ta closed by \&Oo
+.It \&Oo Ta Yes Ta Yes Ta opened by \&Oc
+.It \&Pc Ta Yes Ta Yes Ta closed by \&Po
+.It \&Po Ta Yes Ta Yes Ta opened by \&Pc
+.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
+.It \&Sc Ta Yes Ta Yes Ta opened by \&So
+.It \&So Ta Yes Ta Yes Ta closed by \&Sc
+.It \&Xc Ta Yes Ta Yes Ta opened by \&Xo
+.It \&Xo Ta Yes Ta Yes Ta closed by \&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.
-.Pp
-.Bl -column "MacroX" "CallableX" "ParsableX" -compact -offset XXXX
-.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
-.El
-.\" PARAGRAPH
-.Pp
-The
-.Sq \&.Op
-may be broken by
-.Sq \&.Oc
-as in the following example:
-.Bd -literal -offset XXXX
-\&.Oo
-\&.Op Fl a Oc
+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
-In the above example, the scope of
-.Sq \&.Op
-is technically broken by
-.Sq \&.Oc ,
-however, due to the overwhelming existence of this sequence, it's
-allowed.
-.\" 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
+.Bl -column "MacroX" "CallableX" "ParsableX" -compact -offset indent
+.It Em Macro Ta Em Callable Ta Em Parsable
+.It \&Aq Ta Yes Ta Yes
+.It \&Bq Ta Yes Ta Yes
+.It \&Brq Ta Yes Ta Yes
+.It \&D1 Ta \&No Ta \&Yes
+.It \&Dl Ta \&No Ta Yes
+.It \&Dq Ta Yes Ta Yes
+.It \&Op Ta Yes Ta Yes
+.It \&Pq Ta Yes Ta Yes
+.It \&Ql Ta Yes Ta Yes
+.It \&Qq Ta Yes Ta Yes
+.It \&Sq Ta Yes Ta Yes
.El
-.\" SUB-SECTION
-.Ss In-line
-In-line macros have only text children. If a number (or inequality) of
+.
+.
+.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 n
-.It \&.Er Ta Yes Ta Yes Ta >0
-.It \&.Ev Ta Yes Ta Yes Ta n
-.It \&.Ex Ta \&No Ta \&No Ta 0
-.It \&.Fa Ta Yes Ta Yes Ta n
-.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 n
-.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 n
-.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 n
-.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
-.El
-.Pp
-The
-.Sq \&.Ot ,
-.Sq \&.Fr ,
-.Sq \&.Es
-and
-.Sq \&.En ,
-macros are obsolete.
-.\" SECTION
+.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 \&Ad Ta Yes Ta Yes Ta n
+.It \&An Ta Yes Ta Yes Ta n
+.It \&Ap Ta Yes Ta Yes Ta 0
+.It \&Ar Ta Yes Ta Yes Ta n
+.It \&At Ta Yes Ta Yes Ta 1
+.It \&Bsx Ta Yes Ta Yes Ta n
+.It \&Bt Ta \&No Ta \&No Ta 0
+.It \&Bx Ta Yes Ta Yes Ta n
+.It \&Cd Ta Yes Ta Yes Ta >0
+.It \&Cm Ta Yes Ta Yes Ta n
+.It \&Db Ta \&No Ta \&No Ta 1
+.It \&Dd Ta \&No Ta \&No Ta >0
+.It \&Dt Ta \&No Ta \&No Ta n
+.It \&Dv Ta Yes Ta Yes Ta n
+.It \&Dx Ta Yes Ta Yes Ta n
+.It \&Em Ta Yes Ta Yes Ta >0
+.It \&En Ta \&No Ta \&No Ta 0
+.It \&Er Ta Yes Ta Yes Ta >0
+.It \&Es Ta \&No Ta \&No Ta 0
+.It \&Ev Ta Yes Ta Yes Ta n
+.It \&Ex Ta \&No Ta \&No Ta n
+.It \&Fa Ta Yes Ta Yes Ta n
+.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 \&Fr Ta \&No Ta \&No Ta n
+.It \&Ft Ta Yes Ta Yes Ta n
+.It \&Fx Ta Yes Ta Yes Ta n
+.It \&Hf Ta \&No Ta \&No Ta n
+.It \&Ic Ta Yes Ta Yes Ta >0
+.It \&In Ta \&No Ta \&No Ta n
+.It \&Lb Ta \&No Ta \&No Ta 1
+.It \&Li Ta Yes Ta Yes Ta n
+.It \&Lk Ta Yes Ta Yes Ta n
+.It \&Lp Ta \&No Ta \&No Ta 0
+.It \&Ms Ta Yes Ta Yes Ta >0
+.It \&Mt Ta Yes Ta Yes Ta >0
+.It \&Nm Ta Yes Ta Yes Ta n
+.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 \&Os Ta \&No Ta \&No Ta n
+.It \&Ot Ta \&No Ta \&No Ta n
+.It \&Ox Ta Yes Ta Yes Ta n
+.It \&Pa Ta Yes Ta Yes Ta n
+.It \&Pf Ta \&No Ta Yes Ta 1
+.It \&Pp Ta \&No Ta \&No Ta 0
+.It \&Rv Ta \&No Ta \&No Ta n
+.It \&Sm Ta \&No Ta \&No Ta 1
+.It \&St Ta \&No Ta Yes 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 \&Ud Ta \&No Ta \&No Ta 0
+.It \&Ux Ta Yes Ta Yes Ta n
+.It \&Va Ta Yes Ta Yes Ta n
+.It \&Vt Ta Yes Ta Yes Ta >0
+.It \&Xr Ta Yes Ta Yes Ta >0, <3
+.It \&br Ta \&No Ta \&No Ta 0
+.It \&sp Ta \&No Ta \&No Ta 1
+.El
+.
+.
.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.
+This section documents compatibility with other roff implementations, at
+this time limited to
+.Xr groff 1 .
+The term
+.Qq historic groff
+refers to those versions before the
+.Pa doc.tmac
+file re-write
+.Pq somewhere between 1.15 and 1.19 .
+.
.Pp
.Bl -dash -compact
-.\" LIST-ITEM
.It
-.Sq \&.Fo
-and
-.Sq \&.St
-historically weren't always callable. Both are now correctly callable.
-.\" LIST-ITEM
+The
+.Sq \-split
+or
+.Sq \-nosplit
+argument to
+.Sq \&An
+applies to the whole document, not just to the current section as it
+does in groff.
+.It
+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.
+.It
+The
+.Sq \&sp
+macro does not accept negative numbers.
+.It
+Blocks of whitespace are stripped from both macro and free-form text
+lines (except when in literal mode), while 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, conforming to the
+non-historic groff version.
+.It
+The vertical bar
+.Sq \(ba
+made historic groff
+.Qq go orbital
+but is a proper delimiter in this implementation.
.It
-.Sq \&.It \-nested
-is assumed for all lists: any list may be nested and
+.Sq \&It \-nested
+is assumed for all lists (it wasn't in historic groff): 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
+.Sq \&It \-column
+syntax where column widths may be preceded by other arguments (instead
of proceeded) is not supported.
-.\" LIST-ITEM
.It
-The
-.Sq \&.At
+The
+.Sq \&At
macro only accepts a single parameter.
-.\" LIST-ITEM
-.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
.It
Some manuals use
-.Sq \&.Li
+.Sq \&Li
incorrectly by following it with a reserved character and expecting the
delimiter to render. This is not supported.
-.\" LIST-ITEM
.It
-.Sq \&.Cd
-is callable.
+In groff, the
+.Sq \&Fo
+macro only produces the first parameter. This is no longer the case.
.El
-.\" SECTION
+.
+.
.Sh SEE ALSO
-.Xr mandoc 1
-.\" SECTION
+.Xr mandoc 1 ,
+.Xr mandoc_char 7
+.
+.
.Sh AUTHORS
The
.Nm
-utility was written by
-.An Kristaps Dzonsons Aq kristaps@openbsd.org .
-.\" SECTION
+reference was written by
+.An Kristaps Dzonsons Aq kristaps@kth.se .
+.
+.
.Sh CAVEATS
-There are several ambiguous parts of mdoc.
+There are many ambiguous parts of mdoc.
+.
.Pp
.Bl -dash -compact
-.\" LIST-ITEM
.It
-.Sq \&.Fa
-should be
-.Sq \&.Va
+.Sq \&Fa
+should be
+.Sq \&Va
as function arguments are variables.
-.\" LIST-ITEM
.It
-.Sq \&.Ft
+.Sq \&Ft
should be
-.Sq \&.Vt
+.Sq \&Vt
as function return types are still types. Furthermore, the
-.Sq \&.Ft
+.Sq \&Ft
should be removed and
-.Sq \&.Fo ,
+.Sq \&Fo ,
which ostensibly follows it, should follow the same convention as
-.Sq \&.Va .
-.\" LIST-ITEM
+.Sq \&Va .
.It
-.Sq \&.Va
+.Sq \&Va
should formalise that only one or two arguments are acceptable: a
-variable name and optional, preceeding type.
-.\" LIST-ITEM
+variable name and optional, preceding type.
.It
-.Sq \&.Fd
+.Sq \&Fd
is ambiguous. It's commonly used to indicate an include file in the
-synopsis section.
-.Sq \&.In
+synopsis section.
+.Sq \&In
should be used, instead.
-.\" LIST-ITEM
.It
Only the
.Sq \-literal
argument to
-.Sq \&.Bd
+.Sq \&Bd
makes sense. The remaining ones should be removed.
-.\" LIST-ITEM
.It
-The
-.Sq \&.Xo
+The
+.Sq \&Xo
and
-.Sq \&.Xc
+.Sq \&Xc
macros should be deprecated.
-.\" LIST-ITEM
.It
The
-.Sq \&.Dt
+.Sq \&Dt
macro lacks clarity. It should be absolutely clear which title will
render when formatting the manual page.
-.\" LIST-ITEM
.It
A
-.Sq \&.Lx
-should be provided for Linux (\(`a la
-.Sq \&.Ox ,
-.Sq \&.Nx
+.Sq \&Lx
+should be provided for Linux (\(`a la
+.Sq \&Ox ,
+.Sq \&Nx
etc.).
-.\" LIST-ITEM
.It
There's no way to refer to references in
-.Sq \&.Rs/.Re
+.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