-.\" $Id: mdoc.7,v 1.2 2009/03/13 09:08:59 kristaps Exp $
+.\" $Id: mdoc.7,v 1.30 2009/06/17 14:08:47 kristaps Exp $
.\"
.\" 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.
+.\" 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 13 2009 $
-.Dt mdoc 7
+.Dd $Mdocdate: June 17 2009 $
+.Dt MDOC 7
.Os
.\" SECTION
.Sh NAME
.Nm mdoc
-.Nd mdoc macro reference
+.Nd mdoc language reference
.\" SECTION
.Sh DESCRIPTION
The
language is used to format
.Bx
.Ux
-manuals. An
+manuals. In this reference document, we describe the syntax, ontology
+and structure of the
+.Nm
+language. Our reference implementation is
+.Xr mandoc 1 .
+The
+.Sx COMPATIBILITY
+section describes compatibility with
+.Xr groff 1 .
+.\" PARAGRAPH
+.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. Macros are either two or three characters in length.
+prior macros:
+.Bd -literal -offset XXX
+\&.Sh Macro lines change control state.
+Other lines are interpreted within the current state.
+.Ed
.\" SECTION
-.Sh CHARACTER ENCODING
+.Sh INPUT ENCODING
.Nm
-documents may contain only printable alphanumeric characters, the space
+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.
+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
+.Ss Comments
+Anything following a
+.Sq \e"
+delimiter is considered a comment (unless the
+.Sq \e
+itself has been escaped) and is ignored to the end of line.
+Furthermore, a macro line with only a control character
+.Sq \. ,
+optionally followed by whitespace, is ignored.
.\" SUB-SECTION
.Ss Reserved Characters
Within a macro line, the following characters are reserved:
-.Bl -tag -width 12n -offset XXXX -compact
+.Bl -tag -width Ds -offset XXXX -compact
.It \&.
.Pq period
.It \&,
.It \&?
.Pq question
.It \&!
-.Pq exclmamation
+.Pq exclamation
+.It \&|
+.Pq vertical bar
.El
+.\" PARAGRAPH
.Pp
-Use of these characters must either be escaped with a non-breaking space
+Use of reserved characters is described in
+.Sx Closure .
+For general non-reserved use, characters must either be escaped with a
+non-breaking space
.Pq Sq \e&
-or, if applicable, an appropriate escape-sequence used. Use of reserved
-characters is described later in this document.
+or, if applicable, an appropriate escape-sequence used.
.\" SUB-SECTION
.Ss Special Characters
Special character sequences begin with the escape character
-.Sq \\
-and followed by either an open-parenthesis
+.Sq \e
+followed by either an open-parenthesis
.Sq \&(
for two-character sequences; an open-bracket
.Sq \&[
or a single one-character sequence.
.Pp
Characters may alternatively be escaped by a slash-asterisk,
-.Sq \\* ,
-with the same combinations as described above. This form, however, is
-deprecated. The following is a table of all available escapes, arranged
-by classification.
-.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
-.El
-.\" PARAGRAPH
-.Pp
-Enclosures:
-.Bl -tag -width 12n -offset "XXXX" -compact
-.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
-.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
-.El
-.\" PARAGRAPH
-.Pp
-Mathematical:
-.Bl -tag -width 12n -offset "XXXX" -compact
-.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
-Diacritics:
-.Bl -tag -width 12n -offset "XXXX" -compact
-.It \\(ga
-.Pq accent grave
-.It \\(aa
-.Pq accent accute
-.El
-.\" PARAGRAPH
-.Pp
-Special symbols:
-.Bl -tag -width 12n -offset "XXXX" -compact
-.It \\(bu
-.Pq bullet
-.It \\(ba
-.Pq bar
-.It \\(Ba
-.Pq bar, deprecated
-.It \\(co
-.Pq copyright
-.It \\&
-.Pq non-breaking space
-.It \\e
-.Pq escape
-.It \\(Am
-.Pq ampersand, deprecated
-.El
+.Sq \e* ,
+with the same combinations as described above. This form is deprecated.
.\" SECTION
-.Sh ONTOLOGY
-Macros are classified in an ontology described by scope rules.
+.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.
-.Qq Implicit
-block scope is closed by a subsequent invocation of the same macro,
-one of a set of corresponding closure macros or end-of-file.
-.Qq Explicit
-block scope is closed by a corresponding closure macro.
+may span multiple lines.
.Bl -inset -offset XXXX
.\" LIST-ITEM
.It Em Full-block
-macros always span multiple lines. They consist optionally of one or
+macros always span multiple lines. They consist of zero or
more
.Qq heads ,
-subsequent macros or text on the same line following invocation; a
+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 optionally of a
+macros may span multiple lines. They consists of a optional
.Qq head ,
text immediately following invocation; always a
.Qq body ,
optionally a
.Qq tail ,
text immediately following closure.
-.El
.\" LIST-ITEM
.It Em In-line
-macros may only enclose text and span at most a single line. If
-a macro is parsable, its scope may be closed by subsequent macros or
-delimiting punctuation. In-line macros follow different conventions for
-closure; see
-.Sx MACROS
-for per-macro details.
+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
-.\" .\" SUB-SECTION
-.\" .Ss Examples
-.\" The following examples illustrate each macro classification.
-.\" .\" PARAGRAPH
-.\" .Pp
-.\" Implicit full-block. Has head, body and no tail. Scope closed by
-.\" second
-.\" .Sq \&Sh
-.\" invocation.
-.\" .Bd -literal -offset XXXX
-.\" \&.Sh SECTION 1
-.\" body...
-.\" \&.Sh SECTION 2
-.\" .Ed
-.\" .\" PARAGRAPH
-.\" .Pp
-.\" Nested implicit full-block, where the subsection
-.\" .Sq \&Ss
-.\" is within the scope of the parent section
-.\" .Sq \&Sh
-.\" and closed along with its parent by the subsequent
-.\" .Sq \&Sh .
-.\" .Bd -literal -offset XXXX
-.\" \&.Sh SECTION 1
-.\" \&.Ss Subsection 1
-.\" body...
-.\" \&.Sh SECTION 2
-.\" .Ed
-.\" .\" PARAGRAPH
-.\" .Pp
-.\" Explicit full-block. Has a head, a body and no tail. Scope closed by
-.\" .Sq \&Ef
-.\" invocation.
-.\" .Bd -literal -offset XXXX
-.\" \&.Bf symbolic
-.\" body...
-.\" \&.Ef
-.\" .Ed
-.\" .\" PARAGRAPH
-.\" .Pp
-.\" Nested explicit/implicit scope.
-.\" .Sq \&It
-.\" macro is an implicit block whose scope is closed by the explicit
-.\" .Sq \&El
-.\" closure.
-.\" .Bd -literal -offset XXXX
-.\" \&.Bl \-bullet
-.\" \&.It head
-.\" body...
-.\" \&.El
-.\" .Ed
-.\" .\" PARAGRAPH
-.\" .Pp
-.\" Explicit partial-block. Has head, body and tail. Scope closed by
-.\" .Sq \&Ec
-.\" invocation.
-.\" .Bd -literal -offset XXX
-.\" \&.Eo head body... \&Ec tail
-.\" .Ed
-.\" .\" PARAGRAPH
-.\" .Pp
-.\" Implicit partial-block. Has only body. Scope is closed by end-of-line.
-.\" .Bd -literal -offset XXX
-.\" \&.Sq body...
-.\" .Ed
-.\" .\" PARAGRAPH
-.\" .Pp
-.\" Explicit partial-block with only body and scope closed by
-.\" .Sq \&Ac
-.\" invocation.
-.\" .Bd -literal -offset XXXX
-.\" \&.Ao body... \&Ac
-.\" .Ed
-.\" .\" PARAGRAPH
-.\" .Pp
-.\" Implicit partial-block enclosing explicit partial-block.
-.\" .Bd -literal -offset XXX
-.\" \&.Sq body... \&Ao body... \&Ac
-.\" .Ed
-.\" .\" PARAGRAPH
-.\" .Pp
-.\" Inline macros, several in sequence. Scope is closed for
-.\" .Sq \&Fl
-.\" by the punctuation delimiter and
-.\" .Sq \&Ar
-.\" by the end-of-line.
-.\" .Bd -literal -offset XXXX
-.\" \&.Fl text0 text1 ; Ar text0 text1
-.\" .Ed
+.\" 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
-The syntax of macro invocation depends on classification.
+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,
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):
+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
+\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB
+\(lBbody...\(rB
+\&.Yc \(lBtail...\(rB
.Ed
+.\" PARAGRAPH
.Pp
-Block full-implicit (may contain zero or more heads, body, no tail):
+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
+\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB
+\(lBbody...\(rB
\&.Yc
.Ed
+.\" PARAGRAPH
.Pp
-Block partial-explicit (may contain head, multi-line body, tail):
+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
+\(lBbody...\(rB
+\&.Yc \(lBtail...\(rB
\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB \
-\(lBbody...\(rB \&Yc \(lBtail...\(rB
+\(lBbody...\(rB \&Yc \(lBtail...\(rB
.Ed
+.\" PARAGRAPH
.Pp
-Block partial-implicit (no head, body, no tail):
+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
+\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBreserved...\(rB
.Ed
+.\" PARAGRAPH
.Pp
-In-line (may be closed by end-of-line, reserved character, subsequent
-macro invocation or finite number of arguments):
+In-lines have \(>=0 scoped arguments.
.Bd -literal -offset XXX
-\&.Yy \(lB\-arg \(lBval...\(rB\(rB args...
-
-\&.Yy \(lB\-arg \(lBval...\(rB\(rB args... ;
-
-\&.Yy \(lB\-arg \(lBval...\(rB\(rB args... Xx
+\&.Yy \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB
\&.Yy \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN
.Ed
.Nm
macros, arranged ontologically. A
.Qq callable
-macro is may be invoked subsequent to the initial macro-line macro. A
+macro is invoked subsequent to the initial macro-line macro. A
.Qq parsable
macro may be followed by further (ostensibly callable) macros.
.\" SUB-SECTION
subsequent lines prior to closure. None of these macros have tails;
some
.Po
-.Sq \&It \-bullet ,
+.Sq \&.It \-bullet ,
.Sq \-hyphen ,
.Sq \-dash ,
.Sq \-enum ,
.Pc
don't have heads.
.Pp
-.Bl -column "MacroX" "CallableX" "ParsableX" "Closing" -compact -offset XXXX
+.Bl -column -compact -offset XXXX "MacroX" "CallableX" "ParsableX" "Closing"
.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
the explicit scope rules. All contains bodies, some may contain heads
.Pq So \&Bf Sc .
.Pp
-.Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXX" -compact -offset XXXX
+.Bl -column -compact -offset XXXX "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 \&.Ed Ta \&No Ta \&No Ta opened by \&.Bd
.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
+.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
+.Pq So \&.Fo Sc , So \&.Eo Sc
and/or tail
-.Pq So \&Ec Sc .
+.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
.El
.\" SUB-SECTION
.Ss In-line
-In-line macros have only text children.
+In-line macros have only text children. If a number (or inequality) of
+arguments is
+.Pq n ,
+then the macro accepts an arbitrary number of arguments.
.Pp
.Bl -column "MacroX" "CallableX" "ParsableX" "Arguments" -compact -offset XXXX
.It Em Macro Ta Em Callable Ta Em Parsable Ta Em Arguments
-.It \&.Dd Ta \&No Ta \&No Ta \&
-.It \&.Dt Ta \&No Ta \&No Ta \&
-.It \&.Os Ta \&No Ta \&No Ta \&
+.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 \&
-.It \&.An Ta \&No Ta Yes Ta \&
-.It \&.Ar Ta Yes Ta Yes Ta \&
-.It \&.Cd Ta Yes Ta \&No Ta \&
-.It \&.Cm Ta Yes Ta Yes Ta \&
-.It \&.Dv Ta Yes Ta Yes Ta \&
-.It \&.Er Ta Yes Ta Yes Ta \&
-.It \&.Ev Ta Yes Ta Yes Ta \&
-.It \&.Ex Ta \&No Ta \&No Ta \&
-.It \&.Fa Ta Yes Ta Yes Ta \&
-.It \&.Fd Ta \&No Ta \&No Ta \&
-.It \&.Fl Ta Yes Ta Yes Ta \&
-.It \&.Fn Ta Yes Ta Yes Ta \&
-.It \&.Ft Ta \&No Ta Yes Ta \&
-.It \&.Ic Ta Yes Ta Yes Ta \&
-.It \&.In Ta \&No Ta \&No Ta \&
-.It \&.Li Ta Yes Ta Yes Ta \&
-.It \&.Nd Ta \&No Ta \&No Ta \&
-.It \&.Nm Ta Yes Ta Yes Ta \&
-.It \&.Ot Ta \&No Ta \&No Ta \&
-.It \&.Pa Ta Yes Ta Yes Ta \&
-.It \&.Rv Ta \&No Ta \&No Ta \&
-.It \&.St Ta \&No Ta Yes Ta \&
-.It \&.Va Ta Yes Ta Yes Ta \&
-.It \&.Vt Ta Yes Ta Yes Ta \&
-.It \&.Xr Ta Yes Ta Yes Ta \&
-.It \&.%A Ta \&No Ta \&No Ta \&
-.It \&.%B Ta \&No Ta \&No Ta \&
-.It \&.%C Ta \&No Ta \&No Ta \&
-.It \&.%D Ta \&No Ta \&No Ta \&
-.It \&.%I Ta \&No Ta \&No Ta \&
-.It \&.%J Ta \&No Ta \&No Ta \&
-.It \&.%N Ta \&No Ta \&No Ta \&
-.It \&.%O Ta \&No Ta \&No Ta \&
-.It \&.%P Ta \&No Ta \&No Ta \&
-.It \&.%R Ta \&No Ta \&No Ta \&
-.It \&.%T Ta \&No Ta \&No Ta \&
-.It \&.%V Ta \&No Ta \&No Ta \&
-.It \&.At Ta Yes Ta Yes Ta \&
-.It \&.Bsx Ta Yes Ta Yes Ta \&
-.It \&.Bx Ta Yes Ta Yes Ta \&
-.It \&.Db Ta \&No Ta \&No Ta \&
-.It \&.Em Ta Yes Ta Yes Ta \&
-.It \&.Fx Ta Yes Ta Yes Ta \&
-.It \&.Ms Ta \&No Ta Yes Ta \&
-.It \&.No Ta Yes Ta Yes Ta \&
-.It \&.Ns Ta Yes Ta Yes Ta \&
-.It \&.Nx Ta Yes Ta Yes Ta \&
-.It \&.Ox Ta Yes Ta Yes Ta \&
-.It \&.Pf Ta \&No Ta Yes Ta \&
-.It \&.Sm Ta \&No Ta \&No Ta \&
-.It \&.Sx Ta Yes Ta Yes Ta \&
-.It \&.Sy Ta Yes Ta Yes Ta \&
-.It \&.Tn Ta Yes Ta Yes Ta \&
-.It \&.Ux Ta Yes Ta Yes Ta \&
-.It \&.Bt Ta \&No Ta \&No Ta \&
-.It \&.Hf Ta \&No Ta \&No Ta \&
-.It \&.Fr Ta \&No Ta \&No Ta \&
-.It \&.Ud Ta \&No Ta \&No Ta \&
-.It \&.Lb Ta \&No Ta \&No Ta \&
-.It \&.Ap Ta Yes Ta Yes Ta \&
-.It \&.Lp Ta \&No Ta \&No Ta \&
-.It \&.Lk Ta \&No Ta Yes Ta \&
-.It \&.Mt Ta \&No Ta Yes Ta \&
+.It \&.Ad Ta Yes Ta Yes Ta n
+.It \&.An Ta Yes 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 Yes 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 >0
+.It \&.Fx Ta Yes Ta Yes Ta n
+.It \&.Ms Ta Yes 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 Yes Ta Yes Ta n
+.It \&.Mt Ta Yes 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
+.Sh COMPATIBILITY
+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
+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.
+.\" LIST-ITEM
+.It
+The vertical bar
+.Sq \(Ba
+made historic groff
+.Qq go orbital
+but is a proper delimiter in this implementation.
+.\" LIST-ITEM
+.It
+.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 preceded by other arguments (instead
+of proceeded) is not supported.
+.\" LIST-ITEM
+.It
+The
+.Sq \&.At
+macro only accepts a single parameter.
+.\" LIST-ITEM
+.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
+.It
+If an special-character control character
+.Sq \e
+is escaped, it will
+obviously not render the sequence. Even newer versions of groff seem to
+dither on this.
.El
.\" SECTION
.Sh SEE ALSO
-.Xr mdoctree 1 ,
-.Xr mdoclint 1 ,
-.Xr mdocterm 1 ,
-.Xr mdoc 3
+.Xr mandoc 1 ,
+.Xr mandoc_char 7
.\" SECTION
.Sh AUTHORS
The
.Nm
utility was written by
.An Kristaps Dzonsons Aq kristaps@kth.se .
+.\" SECTION
+.Sh CAVEATS
+There are many ambiguous parts of mdoc.
+.Pp
+.Bl -dash -compact
+.\" LIST-ITEM
+.It
+.Sq \&.Fa
+should be
+.Sq \&.Va
+as function arguments are variables.
+.\" LIST-ITEM
+.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
+.It
+.Sq \&.Va
+should formalise that only one or two arguments are acceptable: a
+variable name and optional, preceding type.
+.\" LIST-ITEM
+.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
+.It
+Only the
+.Sq \-literal
+argument to
+.Sq \&.Bd
+makes sense. The remaining ones should be removed.
+.\" LIST-ITEM
+.It
+The
+.Sq \&.Xo
+and
+.Sq \&.Xc
+macros should be deprecated.
+.\" LIST-ITEM
+.It
+The
+.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
+etc.).
+.\" LIST-ITEM
+.It
+There's no way to refer to references in
+.Sq \&.Rs/.Re
+blocks.
+.El
git.ckatri.com / mandoc.git / blobdiff