===================================================================
RCS file: /cvs/mandoc/mdoc.7,v
retrieving revision 1.56
retrieving revision 1.63
diff -u -p -r1.56 -r1.63
--- mandoc/mdoc.7	2009/08/18 14:27:16	1.56
+++ mandoc/mdoc.7	2009/10/19 07:34:43	1.63
@@ -1,4 +1,4 @@
-.\"	$Id: mdoc.7,v 1.56 2009/08/18 14:27:16 kristaps Exp $
+.\"	$Id: mdoc.7,v 1.63 2009/10/19 07:34:43 kristaps Exp $
 .\"
 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
 .\"
@@ -14,215 +14,314 @@
 .\" 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: October 19 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" ,
-is also ignored.
+.Sq \&.\e" ,
+is also ignored.  Macro lines with only a control charater and optionally
+whitespace are stripped from input.
 .
 .
-. 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
+.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.
 .
+.Ss Dates
+TODO.
 .
+.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
+.Pp
+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
 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
+\&.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
+.
+.Pp
 Subsequent SYNOPSIS and DESCRIPTION sections are strongly encouraged,
 but non-compulsory.
 .
@@ -230,397 +329,659 @@ 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 Sx \&Ao
+.It Sx \&Ao  Ta    Yes      Ta    Yes      Ta    closed by Sx \&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 Sx \&Re  Ta    \&No     Ta    \&No     Ta    opened by Sx \&Rs
+.It Sx \&Rs  Ta    \&No     Ta    \&No     Ta    closed by Sx \&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 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 \&%R  Ta    \&No     Ta    \&No     Ta    >0
+.It Sx \&%T  Ta    \&No     Ta    \&No     Ta    >0
+.It Sx \&%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 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
+.Sq \%%A
+line.
+.Pp
+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
+.Em Compatibility remark :
+this macro is not implemented in
+.Xr groff 1 .
+.Ss \&%D
+Publication date of an
+.Sx \&Rs
+block.  This should follow the canonical syntax for 
+.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
+.Sq \&%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 \&%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
+Example:
+.Bd -literal -offset indent
+\&.Ad [0,$]
+\&.Ad 0x00000000
+.Ed
+.Ss \&An
+.Ss \&Ao
+Begins a block enclosed by angled brackets.  Does not have any head
+arguments.
+.Pp
+Example:
+.Bd -literal -offset indent
+\&.Fl -key= Ns Ao Ar val Ac
+.Ed
+.Pp
+Note that, although this is overwhelmingly used to note URIs, the
+.Sx \&Lk
+and
+.Sx \&Mt
+macros are better suited for this purpose.
+.Ss \&Ap
+.Ss \&Aq
+.Ss \&Ar
+.Ss \&At
+.Ss \&Bc
+.Ss \&Bd
+.Ss \&Bf
+.Ss \&Bk
+.Ss \&Bl
+.Ss \&Bo
+.Ss \&Bq
+.Ss \&Brc
+.Ss \&Bro
+.Ss \&Brq
+.Ss \&Bsx
+.Ss \&Bt
+.Ss \&Bx
+.Ss \&Cd
+.Ss \&Cm
+.Ss \&D1
+.Ss \&Db
+.Ss \&Dc
+.Ss \&Dd
+.Ss \&Dl
+.Ss \&Do
+.Ss \&Dq
+.Ss \&Dt
+.Ss \&Dv
+.Ss \&Dx
+.Ss \&Ec
+.Ss \&Ed
+.Ss \&Ef
+.Ss \&Ek
+.Ss \&El
+.Ss \&Em
+.Ss \&En
+.Ss \&Eo
+.Ss \&Er
+.Ss \&Es
+.Ss \&Ev
+.Ss \&Ex
+.Ss \&Fa
+.Ss \&Fc
+.Ss \&Fd
+.Ss \&Fl
+.Ss \&Fn
+.Ss \&Fo
+.Ss \&Fr
+.Ss \&Ft
+.Ss \&Fx
+.Ss \&Hf
+.Ss \&Ic
+.Ss \&In
+.Ss \&It
+.Ss \&Lb
+.Ss \&Li
+.Ss \&Lk
+.Ss \&Lp
+.Ss \&Ms
+.Ss \&Mt
+.Ss \&Nd
+.Ss \&Nm
+.Ss \&No
+.Ss \&Ns
+.Ss \&Nx
+.Ss \&Oc
+.Ss \&Oo
+.Ss \&Op
+.Ss \&Os
+.Ss \&Ot
+.Ss \&Ox
+.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 and 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
+Example:
+.Bd -literal -offset indent
+\&.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
+.Ss \&Va
+.Ss \&Vt
+.Ss \&Xc
+.Ss \&Xo
+.Ss \&Xr
+.Ss \&br
+.Ss \&sp
+.
+.
 .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
+Negative scaling units are now truncated to zero instead of creating
+interesting conditions, such as with
+.Sq \&sp -1i .
+Furthermore, the
+.Sq f
+scaling unit, while accepted, is rendered as the default unit.
+.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
 .