===================================================================
RCS file: /cvs/mandoc/mdoc.7,v
retrieving revision 1.56
retrieving revision 1.57
diff -u -p -r1.56 -r1.57
--- mandoc/mdoc.7	2009/08/18 14:27:16	1.56
+++ mandoc/mdoc.7	2009/08/20 12:08:40	1.57
@@ -1,4 +1,4 @@
-.\"	$Id: mdoc.7,v 1.56 2009/08/18 14:27:16 kristaps Exp $
+.\"	$Id: mdoc.7,v 1.57 2009/08/20 12:08:40 kristaps Exp $
 .\"
 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
 .\"
@@ -14,215 +14,222 @@
 .\" 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 18 2009 $
+.Dd $Mdocdate: August 20 2009 $
 .Dt MDOC 7
 .Os
 .
 .
 .Sh NAME
-. Nm mdoc
-. Nd mdoc language reference
+.Nm mdoc
+.Nd mdoc language reference
 .
 .
 .Sh DESCRIPTION
 The
-. Nm mdoc
+.Nm mdoc
 language is used to format
-. Bx
-. Ux
+.Bx
+.Ux
 manuals.  In this reference document, we describe its syntax, structure,
 and usage.  Our reference implementation is
-. Xr mandoc 1 .
+.Xr mandoc 1 .
 The
-. Sx COMPATIBILITY
+.Sx COMPATIBILITY
 section describes compatibility with
-. Xr groff 1 .
-. Pp
+.Xr groff 1 .
+.
+.Pp
 An
-. Nm
+.Nm
 document follows simple rules:  lines beginning with the control
 character
-. Sq \.
+.Sq \.
 are parsed for macros.  Other lines are interpreted within the scope of
 prior macros:
-. Bd -literal -offset indent
+.Bd -literal -offset indent
 \&.Sh Macro lines change control state.
 Other lines are interpreted within the current state.
-. Ed
+.Ed
 .
 .
 .Sh LANGUAGE SYNTAX
-. Nm
+.Nm
 documents may contain only graphable 7-bit ASCII characters, the space
 character, and, in certain circumstances, the tab character.  All
 manuals must have
-. Ux
+.Ux
 line terminators.
 .
 .
-. Ss Comments
+.Ss Comments
 Text following a
-.  Sq \e" ,
+.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" ,
+.Sq \&.\e" ,
 is also ignored.
 .
 .
-. Ss Reserved Characters
+.Ss Reserved Characters
 Within a macro line, the following characters are reserved:
-.  Bl -tag -width Ds -offset indent -compact
-.   It \&.
-.    Pq period
-.   It \&,
-.    Pq comma
-.   It \&:
-.    Pq colon
-.   It \&;
-.    Pq semicolon
-.   It \&(
-.    Pq left-parenthesis
-.   It \&)
-.    Pq right-parenthesis
-.   It \&[
-.    Pq left-bracket
-.   It \&]
-.    Pq right-bracket
-.   It \&?
-.    Pq question
-.   It \&!
-.    Pq exclamation
-.   It \&|
-.    Pq vertical bar
-.  El
-.  Pp
+.Bl -tag -width Ds -offset indent -compact
+.It \&.
+.Pq period
+.It \&,
+.Pq comma
+.It \&:
+.Pq colon
+.It \&;
+.Pq semicolon
+.It \&(
+.Pq left-parenthesis
+.It \&)
+.Pq right-parenthesis
+.It \&[
+.Pq left-bracket
+.It \&]
+.Pq right-bracket
+.It \&?
+.Pq question
+.It \&!
+.Pq exclamation
+.It \&|
+.Pq vertical bar
+.El
+.
+.Pp
 Use of reserved characters is described in
-.  Sx MACRO SYNTAX .
+.Sx MACRO SYNTAX .
 For general use in macro lines, these characters must either be escaped
 with a non-breaking space
-.  Pq Sq \e&
+.Pq Sq \e&
 or, if applicable, an appropriate escape sequence used.
 .
 .
-. Ss Special Characters
+.Ss Special Characters
 Special characters may occur in both macro and free-form lines.
 Sequences begin with the escape character
-.  Sq \e
+.Sq \e
 followed by either an open-parenthesis
-.  Sq \&(
+.Sq \&(
 for two-character sequences; an open-bracket
-.  Sq \&[
+.Sq \&[
 for n-character sequences (terminated at a close-bracket
-.  Sq \&] ) ;
+.Sq \&] ) ;
 or a single one-character sequence.  See
-.  Xr mandoc_char 7
+.Xr mandoc_char 7
 for a complete list.  Examples include
-.  Sq \e(em
-.  Pq em-dash
+.Sq \e(em
+.Pq em-dash
 and
-.  Sq \ee
-.  Pq back-slash .
+.Sq \ee
+.Pq back-slash .
 .
 .
-. Ss Text Decoration
+.Ss Text Decoration
 Terms may be text-decorated using the
-.  Sq \ef
+.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 ,
+.Nm ,
 which encourages semantic, not presentation, annotation.
 .
 .
-. Ss Predefined Strings
+.Ss Predefined Strings
 Historically, 
-.  Xr groff 1
+.Xr groff 1
 also defined a set of package-specific 
-.  Dq predefined strings ,
+.Dq predefined strings ,
 which, like 
-.  Sx Special Characters ,
+.Sx Special Characters ,
 demark special output characters and strings by way of input codes.
 Predefined strings are escaped with the slash-asterisk,
-.  Sq \e* :
+.Sq \e* :
 single-character
-.  Sq \e*X ,
+.Sq \e*X ,
 two-character
-.  Sq \e*(XX ,
+.Sq \e*(XX ,
 and N-character
-.  Sq \e*[N] .
+.Sq \e*[N] .
 See
-.  Xr mandoc_char 7
+.Xr mandoc_char 7
 for a complete list.  Examples include
-.  Sq \e*(Am
-.  Pq ampersand
+.Sq \e*(Am
+.Pq ampersand
 and
-.  Sq \e*(Ba
-.  Pq vertical bar .
+.Sq \e*(Ba
+.Pq vertical bar .
 .
 .
-. Ss Whitespace
+.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
+.Bd -literal -offset indent
 These     spaces   are    pruned       from    input.
 \&.Bd \-literal
 These         are              not.
 \&.Ed
-.  Ed
-.  Pp
+.Ed
+.
+.Pp
 In macro lines, whitespace delimits arguments and is discarded.  If
 arguments are quoted, whitespace within the quotes is retained.
-.  Pp
+.
+.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
+.Sq \&Bl \-column
 or when in a literal context.
 .
 .
-. Ss Quotation
+.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
+.
+.Pp
 This produces tokens
-.  Sq a" ,
-.  Sq b c ,
-.  Sq de ,
+.Sq a" ,
+.Sq b c ,
+.Sq de ,
 and
-.  Sq fg" .
+.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
+.Sq \&Em a :
+.Bd -literal -offset indent
 \&.Em "Em a"
-.  Ed
-.  Pp
+.Ed
+.
+.Pp
 In free-form mode, quotes are regarded as opaque text.
 .
 .
 .Sh MANUAL STRUCTURE
 Each
-. Nm
+.Nm
 document must begin with a document prologue, containing, in order,
-. Sq \&Dd ,
-. Sq \&Dt ,
+.Sq \&Dd ,
+.Sq \&Dt ,
 and
-. Sq \&Os ,
+.Sq \&Os ,
 then the NAME section containing at least one
-. Sq \&Nm
+.Sq \&Nm
 followed by
-. Sq \&Nd :
-. Bd -literal -offset indent
+.Sq \&Nd :
+.Bd -literal -offset indent
 \&.Dd $\&Mdocdate$
 \&.Dt mdoc 7
 \&.Os
 \&.Sh NAME
 \&.Nm mdoc
 \&.Nd mdoc language reference
-. Ed
-. Pp
+.Ed
+.
+.Pp
 Subsequent SYNOPSIS and DESCRIPTION sections are strongly encouraged,
 but non-compulsory.
 .
@@ -230,397 +237,408 @@ but non-compulsory.
 .Sh MACRO SYNTAX
 Macros are one to three three characters in length and begin with a
 control character ,
-. Sq \&. ,
+.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
+.Sq \&.Pp
 and
-. Sq \&.\ \ \ \&Pp
+.Sq \&.\ \ \ \&Pp
 are equivalent.  Macro names are two or three characters in length.
-. Pp
+.
+.Pp
 The syntax of a macro depends on its classification.  In this section,
-. Sq \-arg
+.Sq \-arg
 refers to macro arguments, which may be followed by zero or more
-. Sq parm
+.Sq parm
 parameters;
-. Sq \&Yo
+.Sq \&Yo
 opens the scope of a macro; and if specified,
-. Sq \&Yc
+.Sq \&Yc
 closes it out.
-. Pp
+.
+.Pp
 The
-. Em Callable
+.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
+.Sq \&.Fl Sh
 produces
-. Sq Fl Sh .
-. Pp
+.Sq Fl Sh .
+.
+.Pp
 The
-. Em Parsable
+.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
+.
+.Pp
 The
-. Em Scope
+.Em Scope
 column, if applicable, describes closure rules.
 .
 .
-. Ss Block full-explicit
+.Ss Block full-explicit
 Multi-line scope closed by an explicit closing macro.  All macros
 contains bodies; only
-.  Pq Sq \&Bf
+.Pq Sq \&Bf
 contains a head.
-.  Bd -literal -offset indent
+.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 \&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
+.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 \&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
+.
+.Ss Block full-implicit
 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 \-dash ,
-.   Sq \-enum ,
-.   Sq \-item
-.  Pc
+.Po
+.Sq \&It \-bullet ,
+.Sq \-hyphen ,
+.Sq \-dash ,
+.Sq \-enum ,
+.Sq \-item
+.Pc
 don't have heads, while
-.  Sq \&It \-column
+.Sq \&It \-column
 may have multiple heads.
-.  Bd -literal -offset indent
+.Bd -literal -offset indent
 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB
 \(lBbody...\(rB
-.  Ed
-.  Pp
-.  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
+.Ed
 .
+.Pp
+.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
 .
-. Ss Block partial-explicit
+.
+.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
+.Pq So \&Fo Sc , So \&Eo Sc
 and/or tail
-.  Pq So \&Ec Sc .
-.  Bd -literal -offset indent
+.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 XXXX" -compact -offset indent
-.   It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
-.   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
+.Ed
 .
+.Pp
+.Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXXX" -compact -offset indent
+.It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
+.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
 .
-. Ss Block partial-implicit
+.
+.Ss Block partial-implicit
 Like block full-implicit, but with single-line scope closed by
-.  Sx Reserved Characters
+.Sx Reserved Characters
 or end of line.
-.  Bd -literal -offset indent
+.Bd -literal -offset indent
 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB
-.  Ed
-.  Pp
-.  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
+.Ed
 .
+.Pp
+.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
 .
-. Ss In-line
+.
+.Ss In-line
 Closed by
-.  Sx Reserved Characters ,
+.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
+.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 indent
-.   It Em Macro Ta Em Callable Ta Em Parsable Ta Em Arguments
-.   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    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 \&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    0
-.   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   
+.Ed
 .
+.Pp
+.Bl -column "MacroX" "CallableX" "ParsableX" "Arguments" -compact -offset indent
+.It Em Macro Ta Em Callable Ta Em Parsable Ta Em Arguments
+.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    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 \&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    0
+.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
 This section documents compatibility with other roff implementations, at
 this time limited to
-. Xr groff 1 .
+.Xr groff 1 .
 The term
-. Qq historic groff
+.Qq historic groff
 refers to those versions before the
-. Pa doc.tmac
+.Pa doc.tmac
 file re-write
-. Pq somewhere between 1.15 and 1.19 .
-. Pp
-. Bl -dash -compact
-.  It
+.Pq somewhere between 1.15 and 1.19 .
+.
+.Pp
+.Bl -dash -compact
+.It
 The
-.   Sq \-split
+.Sq \-split
 or
-.   Sq \-nosplit
+.Sq \-nosplit
 argument to 
-.   Sq \&An
+.Sq \&An
 applies to the whole document, not just to the current section as it
 does in groff.
-.  It
+.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
+.It
 The
-.   Sq \&sp
+.Sq \&sp
 macro does not accept negative numbers.
-.  It
+.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
+.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
+.It
 The vertical bar
-.   Sq \(ba
+.Sq \(ba
 made historic groff
-.   Qq go orbital
+.Qq go orbital
 but is a proper delimiter in this implementation.
-.  It
-.   Sq \&It \-nested
+.It
+.Sq \&It \-nested
 is assumed for all lists (it wasn't in historic groff): any list may be
 nested and
-.   Sq \-enum
+.Sq \-enum
 lists will restart the sequence only for the sub-list.
-.  It
-.   Sq \&It \-column
+.It
+.Sq \&It \-column
 syntax where column widths may be preceded by other arguments (instead
 of proceeded) is not supported.
-.  It
+.It
 The
-.   Sq \&At
+.Sq \&At
 macro only accepts a single parameter.
-.  It
+.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.
-.  It
+.It
 In groff, the
-.   Sq \&Fo
+.Sq \&Fo
 macro only produces the first parameter.  This is no longer the case.
-. El
+.El
 .
 .
 .Sh SEE ALSO
-. Xr mandoc 1 ,
-. Xr mandoc_char 7
+.Xr mandoc 1 ,
+.Xr mandoc_char 7
 .
 .
 .Sh AUTHORS
 The
-. Nm
+.Nm
 reference was written by
-. An Kristaps Dzonsons Aq kristaps@kth.se .
+.An Kristaps Dzonsons Aq kristaps@kth.se .
 .
 .
 .Sh CAVEATS
 There are many ambiguous parts of mdoc.
-. Pp
-. Bl -dash -compact
-.  It
-.   Sq \&Fa
+.
+.Pp
+.Bl -dash -compact
+.It
+.Sq \&Fa
 should be
-.   Sq \&Va
+.Sq \&Va
 as function arguments are variables.
-.  It
-.   Sq \&Ft
+.It
+.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 .
-.  It
-.   Sq \&Va
+.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
+.It
+.Sq \&Fd
 is ambiguous.  It's commonly used to indicate an include file in the
 synopsis section.
-.   Sq \&In
+.Sq \&In
 should be used, instead.
-.  It
+.It
 Only the
-.   Sq \-literal
+.Sq \-literal
 argument to
-.   Sq \&Bd
+.Sq \&Bd
 makes sense.  The remaining ones should be removed.
-.  It
+.It
 The
-.   Sq \&Xo
+.Sq \&Xo
 and
-.   Sq \&Xc
+.Sq \&Xc
 macros should be deprecated.
-.  It
+.It
 The
-.   Sq \&Dt
+.Sq \&Dt
 macro lacks clarity.  It should be absolutely clear which title will
 render when formatting the manual page.
-.  It
+.It
 A
-.   Sq \&Lx
+.Sq \&Lx
 should be provided for Linux (\(`a la
-.   Sq \&Ox ,
-.   Sq \&Nx
+.Sq \&Ox ,
+.Sq \&Nx
 etc.).
-.  It
+.It
 There's no way to refer to references in
-.   Sq \&Rs/Re
+.Sq \&Rs/Re
 blocks.
-.  It
+.It
 The \-split and \-nosplit dictates via
-.   Sq \&An
+.Sq \&An
 are re-set when entering and leaving the AUTHORS section.
-. El
+.El
 .