===================================================================
RCS file: /cvs/mandoc/mdoc.7,v
retrieving revision 1.73
retrieving revision 1.110
diff -u -p -r1.73 -r1.110
--- mandoc/mdoc.7	2009/11/02 11:39:40	1.73
+++ mandoc/mdoc.7	2010/05/26 10:39:35	1.110
@@ -1,6 +1,6 @@
-.\"	$Id: mdoc.7,v 1.73 2009/11/02 11:39:40 kristaps Exp $
+.\"	$Id: mdoc.7,v 1.110 2010/05/26 10:39:35 kristaps Exp $
 .\"
-.\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
+.\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@bsd.lv>
 .\"
 .\" Permission to use, copy, modify, and distribute this software for any
 .\" purpose with or without fee is hereby granted, provided that the above
@@ -14,16 +14,12 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: November 2 2009 $
+.Dd $Mdocdate: May 26 2010 $
 .Dt MDOC 7
 .Os
-.
-.
 .Sh NAME
 .Nm mdoc
 .Nd mdoc language reference
-.
-.
 .Sh DESCRIPTION
 The
 .Nm mdoc
@@ -31,13 +27,9 @@ language is used to format
 .Bx
 .Ux
 manuals.  In this reference document, we describe its syntax, structure,
-and usage.  Our reference implementation is
-.Xr mandoc 1 .
-The
+and usage.  Our reference implementation is mandoc; the
 .Sx COMPATIBILITY
-section describes compatibility with
-.Xr groff 1 .
-.
+section describes compatibility with other troff \-mdoc implementations.
 .Pp
 An
 .Nm
@@ -50,8 +42,6 @@ prior macros:
 \&.Sh Macro lines change control state.
 Other lines are interpreted within the current state.
 .Ed
-.
-.
 .Sh LANGUAGE SYNTAX
 .Nm
 documents may contain only graphable 7-bit ASCII characters, the space
@@ -59,8 +49,6 @@ character, and, in certain circumstances, the tab char
 manuals must have
 .Ux
 line terminators.
-.
-.
 .Ss Comments
 Text following a
 .Sq \e" ,
@@ -69,8 +57,6 @@ line.  A macro line with only a control character and 
 .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:
 .Pp
@@ -98,7 +84,6 @@ Within a macro line, the following characters are rese
 .It \&|
 .Pq vertical bar
 .El
-.
 .Pp
 Use of reserved characters is described in
 .Sx MACRO SYNTAX .
@@ -106,8 +91,6 @@ For general use in macro lines, these characters must 
 with a non-breaking space
 .Pq Sq \e&
 or, if applicable, an appropriate escape sequence used.
-.
-.
 .Ss Special Characters
 Special characters may occur in both macro and free-form lines.
 Sequences begin with the escape character
@@ -118,31 +101,71 @@ for two-character sequences; an open-bracket
 .Sq \&[
 for n-character sequences (terminated at a close-bracket
 .Sq \&] ) ;
-or a single one-character sequence.  See
+or a single one-character sequence.
+See
 .Xr mandoc_char 7
-for a complete list.  Examples include
+for a complete list.
+Examples include
 .Sq \e(em
 .Pq em-dash
 and
 .Sq \ee
 .Pq back-slash .
-.
-.
 .Ss Text Decoration
 Terms may be text-decorated using the
 .Sq \ef
-escape followed by an indicator: B (bold), I, (italic), or P and R
-(Roman, or reset).  This form is not recommended for 
+escape followed by an indicator: B (bold), I, (italic), R (Roman), or P
+(revert to previous mode):
+.Pp
+.D1 \efBbold\efR \efIitalic\efP
+.Pp
+A numerical representation 3, 2, or 1 (bold, italic, and Roman,
+respectively) may be used instead.
+A text decoration is valid within
+the current font scope only:  if a macro opens a font scope alongside
+its own scope, such as
+.Sx \&Bf
+.Cm \&Sy ,
+in-scope invocations of
+.Sq \ef
+are only valid within the font scope of the macro.
+If
+.Sq \ef
+is specified outside of any font scope, such as in unenclosed, free-form
+text, it will affect the remainder of the document.
+.Pp
+Text may also be sized with the
+.Sq \es
+escape, whose syntax is one of
+.Sq \es+-n
+for one-digit numerals;
+.Sq \es(+-nn
+or
+.Sq \es+-(nn
+for two-digit numerals; and
+.Sq \es[+-N] ,
+.Sq \es+-[N] ,
+.Sq \es'+-N' ,
+or
+.Sq \es+-'N'
+for arbitrary-digit numerals:
+.Pp
+.D1 \es+1bigger\es-1
+.D1 \es[+10]much bigger\es[-10]
+.D1 \es+(10much bigger\es-(10
+.D1 \es+'100'much much bigger\es-'100'
+.Pp
+Note these forms are
+.Em not
+recommended for
 .Nm ,
-which encourages semantic, not presentation, annotation.
-.
-.
+which encourages semantic annotation.
 .Ss Predefined Strings
-Historically, 
+Historically,
 .Xr groff 1
-also defined a set of package-specific 
+also defined a set of package-specific
 .Dq predefined strings ,
-which, like 
+which, like
 .Sx Special Characters ,
 demark special output characters and strings by way of input codes.
 Predefined strings are escaped with the slash-asterisk,
@@ -155,43 +178,28 @@ and N-character
 .Sq \e*[N] .
 See
 .Xr mandoc_char 7
-for a complete list.  Examples include
+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
-.
+Whitespace consists of the space character.
+In free-form lines, whitespace is preserved within a line; un-escaped
+trailing spaces are stripped from input (unless in a literal context).
+Blank free-form lines, which may include whitespace, are only permitted
+within literal contexts.
 .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.
-.
-.
+In macro lines, whitespace delimits arguments and is discarded.
+If arguments are quoted, whitespace within the quotes is retained.
 .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.
-.
+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" ,
@@ -200,28 +208,29 @@ This produces tokens
 and
 .Sq fg" .
 Note that any quoted term, be it argument or macro, is indiscriminately
-considered literal text.  Thus, the following produces
+considered literal text.
+Thus, the following produces
 .Sq \&Em a :
 .Bd -literal -offset indent
 \&.Em "Em a"
 .Ed
-.
 .Pp
 In free-form mode, quotes are regarded as opaque text.
-.
 .Ss Dates
 There are several macros in
 .Nm
-that require a date argument.  The canonical form for dates is the
-American format:
+that require a date argument.
+The canonical form for dates is the American format:
 .Pp
 .D1 Cm Month Day , Year
 .Pp
 The
 .Cm Day
-value is an optionally zero-padded numeral.  The
+value is an optionally zero-padded numeral.
+The
 .Cm Month
-value is the full month name.  The
+value is the full month name.
+The
 .Cm Year
 value is the full four-digit year.
 .Pp
@@ -235,20 +244,18 @@ Some examples of valid dates follow:
 .D1 "May, 2009" Pq reduced form
 .D1 "2009" Pq reduced form
 .D1 "May 20, 2009" Pq canonical form
-.
 .Ss Scaling Widths
 Many macros support scaled widths for their arguments, such as
 stipulating a two-inch list indentation with the following:
 .Bd -literal -offset indent
 \&.Bl -tag -width 2i
 .Ed
-.
 .Pp
 The syntax for scaled widths is
 .Sq Li [+-]?[0-9]*.[0-9]*[:unit:] ,
 where a decimal must be preceded or proceeded by at least one digit.
-Negative numbers, while accepted, are truncated to zero.  The following
-scaling units are accepted:
+Negative numbers, while accepted, are truncated to zero.
+The following scaling units are accepted:
 .Pp
 .Bl -tag -width Ds -offset indent -compact
 .It c
@@ -286,10 +293,26 @@ Using anything other than
 .Sq u ,
 or
 .Sq v
-is necessarily non-portable across output media.  See
+is necessarily non-portable across output media.
+See
 .Sx COMPATIBILITY .
-.
-.
+.Ss Sentence Spacing
+When composing a manual, make sure that your sentences end at the end of
+a line.
+By doing so, front-ends will be able to apply the proper amount of
+spacing after the end of sentence (unescaped) period, exclamation mark,
+or question mark followed by zero or more non-sentence closing
+delimiters (
+.Ns Sq \&) ,
+.Sq \&] ,
+.Sq \&' ,
+.Sq \&" ) .
+.Pp
+The proper spacing is also intelligently preserved if a sentence ends at
+the boundary of a macro line, e.g.,
+.Pp
+.D1 \&Xr mandoc 1 \.
+.D1 \&Fl T \&Ns \&Cm ascii \.
 .Sh MANUAL STRUCTURE
 A well-formed
 .Nm
@@ -303,7 +326,7 @@ and
 .Sx \&Os
 macros, is required for every document.
 .Pp
-The first section (sections are denoted by 
+The first section (sections are denoted by
 .Sx \&Sh )
 must be the NAME section, consisting of at least one
 .Sx \&Nm
@@ -324,7 +347,7 @@ file:
 \&.Sh NAME
 \&.Nm foo
 \&.Nd a description goes here
-\&.\e\*q The next is for sections 2 & 3 only.
+\&.\e\*q The next is for sections 2, 3, & 9 only.
 \&.\e\*q .Sh LIBRARY
 \&.
 \&.Sh SYNOPSIS
@@ -337,13 +360,13 @@ 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 The next is for sections 1 & 8 only.
+\&.\e\*q .Sh EXIT STATUS
 \&.\e\*q .Sh EXAMPLES
 \&.\e\*q The next is for sections 1, 4, 6, 7, & 8 only.
 \&.\e\*q .Sh DIAGNOSTICS
@@ -361,12 +384,12 @@ utility processes files ...
 .Pp
 The sections in a
 .Nm
-document are conventionally ordered as they appear above.  Sections
-should be composed as follows:
+document are conventionally ordered as they appear above.
+Sections should be composed as follows:
 .Bl -ohang -offset Ds
 .It Em NAME
-The name(s) and a short description of the documented material.  The
-syntax for this as follows:
+The name(s) and a short description of the documented material.
+The syntax for this as follows:
 .Bd -literal -offset indent
 \&.Nm name0
 \&.Nm name1
@@ -379,22 +402,24 @@ The
 macro(s) must precede the
 .Sx \&Nd
 macro.
-.
+.Pp
+See
+.Sx \&Nm
+and
+.Sx \&Nd .
 .It Em LIBRARY
 The name of the library containing the documented material, which is
-assumed to be a function in a section 2 or 3 manual.  The syntax for
-this is as follows:
+assumed to be a function in a section 2, 3, or 9 manual.
+The syntax for this is as follows:
 .Bd -literal -offset indent
 \&.Lb libarm
 .Ed
 .Pp
 See
-.Sx \&Lb
-for details.
-.
+.Sx \&Lb .
 .It Em SYNOPSIS
 Documents the utility invocation syntax, function call syntax, or device
-configuration. 
+configuration.
 .Pp
 For the first, utilities (sections 1, 6, and 8), this is
 generally structured as follows:
@@ -425,11 +450,18 @@ And for the third, configurations (section 4):
 \&.Cd \*qit* at isa? port 0x4e\*q
 .Ed
 .Pp
-Manuals not in these sections generally don't need a 
+Manuals not in these sections generally don't need a
 .Em SYNOPSIS .
-.
+.Pp
+See
+.Sx \&Op ,
+.Sx \&Cd ,
+.Sx \&Fn ,
+.Sx \&Ft ,
+and
+.Sx \&Vt .
 .It Em DESCRIPTION
-This expands upon the brief, one-line description in 
+This expands upon the brief, one-line description in
 .Em NAME .
 It usually contains a break-down of the options (if documenting a
 command), such as:
@@ -440,125 +472,113 @@ The arguments are as follows:
 Print verbose information.
 \&.El
 .Ed
+.Pp
 Manuals not documenting a command won't include the above fragment.
-.
 .It Em IMPLEMENTATION NOTES
-Implementation-specific notes should be kept here.  This is useful when
-implementing standard functions that may have side effects or notable
-algorithmic implications.
-.
-.It Em EXIT STATUS
-Command exit status for section 1, 6, and 8 manuals.  This section is
-the dual of
-.Em RETURN VALUES ,
-which is used for functions.  Historically, this information was
-described in
-.Em DIAGNOSTICS ,
-a practise that is now discouraged.
-.Pp
-See
-.Sx \&Ex .
-.
+Implementation-specific notes should be kept here.
+This is useful when implementing standard functions that may have side
+effects or notable algorithmic implications.
 .It Em RETURN VALUES
 This section is the dual of
 .Em EXIT STATUS ,
-which is used for commands.  It documents the return values of functions
-in sections 2, 3, and 9.
+which is used for commands.
+It documents the return values of functions in sections 2, 3, and 9.
 .Pp
 See
 .Sx \&Rv .
-.
 .It Em ENVIRONMENT
 Documents any usages of environment variables, e.g.,
 .Xr environ 7 .
 .Pp
 See
 .Sx \&Ev .
-.
 .It Em FILES
-Documents files used.  It's helpful to document both the file and a
-short description of how the file is used (created, modified, etc.).
+Documents files used.
+It's helpful to document both the file and a short description of how
+the file is used (created, modified, etc.).
 .Pp
 See
 .Sx \&Pa .
-.
+.It Em EXIT STATUS
+Command exit status for section 1, 6, and 8 manuals.
+This section is the dual of
+.Em RETURN VALUES ,
+which is used for functions.
+Historically, this information was described in
+.Em DIAGNOSTICS ,
+a practise that is now discouraged.
+.Pp
+See
+.Sx \&Ex .
 .It Em EXAMPLES
-Example usages.  This often contains snippets of well-formed,
-well-tested invocations.  Make doubly sure that your examples work
-properly!
-.
+Example usages.
+This often contains snippets of well-formed, well-tested invocations.
+Make doubly sure that your examples work properly!
 .It Em DIAGNOSTICS
-Documents error conditions.  This is most useful in section 4 manuals.
+Documents error conditions.
+This is most useful in section 4 manuals.
 Historically, this section was used in place of
 .Em EXIT STATUS
 for manuals in sections 1, 6, and 8; however, this practise is
 discouraged.
 .Pp
 See
-.Sx \&Bl No \-diag .
-.
+.Sx \&Bl
+.Fl diag .
 .It Em ERRORS
 Documents error handling in sections 2, 3, and 9.
 .Pp
 See
 .Sx \&Er .
-.
 .It Em SEE ALSO
-References other manuals with related topics.  This section should exist
-for most manuals.  Cross-references should conventionally be ordered
-first by section, then alphabetically.
+References other manuals with related topics.
+This section should exist for most manuals.
+Cross-references should conventionally be ordered first by section, then
+alphabetically.
 .Pp
 See
 .Sx \&Xr .
-.
 .It Em STANDARDS
-References any standards implemented or used.  If not adhering to any
-standards, the
+References any standards implemented or used.
+If not adhering to any standards, the
 .Em HISTORY
 section should be used instead.
 .Pp
 See
 .Sx \&St .
-.
 .It Em HISTORY
 The history of any manual without a
 .Em STANDARDS
 section should be described in this section.
-.
 .It Em AUTHORS
 Credits to authors, if applicable, should appear in this section.
 Authors should generally be noted by both name and an e-mail address.
 .Pp
 See
 .Sx \&An .
-.
 .It Em CAVEATS
 Explanations of common misuses and misunderstandings should be explained
 in this section.
-.
 .It Em BUGS
 Extant bugs should be described in this section.
-.
 .It Em SECURITY CONSIDERATIONS
 Documents any security precautions that operators should consider.
-.
 .El
-.
-.
 .Sh MACRO SYNTAX
 Macros are one to three three characters in length and begin with a
 control character ,
 .Sq \&. ,
-at the beginning of the line.  An arbitrary amount of whitespace may
-sit between the control character and the macro name.  Thus, the
-following are equivalent:
+at the beginning of the line.
+An arbitrary amount of whitespace may sit between the control character
+and the macro name.
+Thus, the following are equivalent:
 .Bd -literal -offset indent
 \&.Pp
 \&.\ \ \ \&Pp
 .Ed
-.
 .Pp
-The syntax of a macro depends on its classification.  In this section,
+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
@@ -567,33 +587,30 @@ parameters;
 opens the scope of a macro; and if specified,
 .Sq \&Yc
 closes it out.
-.
 .Pp
 The
 .Em Callable
 column indicates that the macro may be called subsequent to the initial
-line-macro.  If a macro is not callable, then its invocation after the
-initial line macro is interpreted as opaque text, such that
+line-macro.
+If a macro is not callable, then its invocation after the initial line
+macro is interpreted as opaque text, such that
 .Sq \&.Fl \&Sh
 produces
 .Sq Fl \&Sh .
-.
 .Pp
 The
 .Em Parsable
 column indicates whether the macro may be followed by further
-(ostensibly callable) macros.  If a macro is not parsable, subsequent
-macro invocations on the line will be interpreted as opaque text.
-.
+(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
+Multi-line scope closed by an explicit closing macro.
+All macros contains bodies; only
 .Sx \&Bf
 contains a head.
 .Bd -literal -offset indent
@@ -601,7 +618,6 @@ contains a head.
 \(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
@@ -614,8 +630,6 @@ contains a head.
 .It Sx \&Ek  Ta    \&No     Ta    \&No     Ta    opened by Sx \&Bk
 .It Sx \&El  Ta    \&No     Ta    \&No     Ta    opened by Sx \&Bl
 .El
-.
-.
 .Ss Block full-implicit
 Multi-line scope closed by end-of-file or implicitly by another macro.
 All macros have bodies; some
@@ -629,13 +643,12 @@ All macros have bodies; some
 don't have heads; only one
 .Po
 .Sx \&It Fl column
-.Pc 
+.Pc
 has multiple heads.
 .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
@@ -644,11 +657,9 @@ has multiple heads.
 .It Sx \&Sh  Ta    \&No     Ta    \&No     Ta    closed by Sx \&Sh
 .It Sx \&Ss  Ta    \&No     Ta    \&No     Ta    closed by Sx \&Sh , Sx \&Ss
 .El
-.
-.
 .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
+Like block full-explicit, but also with single-line scope.
+Each has at least a body and, in limited circumstances, a head
 .Po
 .Sx \&Fo ,
 .Sx \&Eo
@@ -663,7 +674,6 @@ and/or tail
 \&.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
@@ -692,8 +702,6 @@ and/or tail
 .It Sx \&Xc  Ta    Yes      Ta    Yes      Ta    opened by Sx \&Xo
 .It Sx \&Xo  Ta    Yes      Ta    Yes      Ta    closed by Sx \&Xc
 .El
-.
-.
 .Ss Block partial-implicit
 Like block full-implicit, but with single-line scope closed by
 .Sx Reserved Characters
@@ -701,7 +709,6 @@ or end of line.
 .Bd -literal -offset indent
 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB
 .Ed
-.
 .Pp
 .Bl -column "MacroX" "CallableX" "ParsableX" -compact -offset indent
 .It Em Macro Ta Em Callable Ta Em Parsable
@@ -716,15 +723,24 @@ or end of line.
 .It Sx \&Ql  Ta    Yes      Ta    Yes
 .It Sx \&Qq  Ta    Yes      Ta    Yes
 .It Sx \&Sq  Ta    Yes      Ta    Yes
+.It Sx \&Vt  Ta    Yes      Ta    Yes
 .El
-.
-.
+.Pp
+Note that the
+.Sx \&Vt
+macro is a
+.Sx Block partial-implicit
+only when invoked as the first macro
+in a
+.Em SYNOPSIS
+section line, else it is
+.Sx In-line .
 .Ss In-line
 Closed by
 .Sx Reserved Characters ,
-end of line, fixed argument lengths, and/or subsequent macros.  In-line
-macros have only text children.  If a number (or inequality) of
-arguments is
+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 ,
 then the macro accepts an arbitrary number of arguments.
 .Bd -literal -offset indent
@@ -734,7 +750,6 @@ then the macro accepts an arbitrary number of argument
 
 \&.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
@@ -797,7 +812,7 @@ then the macro accepts an arbitrary number of argument
 .It Sx \&Ot  Ta    \&No     Ta    \&No     Ta    n
 .It Sx \&Ox  Ta    Yes      Ta    Yes      Ta    n
 .It Sx \&Pa  Ta    Yes      Ta    Yes      Ta    n
-.It Sx \&Pf  Ta    \&No     Ta    Yes      Ta    1
+.It Sx \&Pf  Ta    Yes      Ta    Yes      Ta    1
 .It Sx \&Pp  Ta    \&No     Ta    \&No     Ta    0
 .It Sx \&Rv  Ta    \&No     Ta    \&No     Ta    n
 .It Sx \&Sm  Ta    \&No     Ta    \&No     Ta    1
@@ -809,17 +824,15 @@ then the macro accepts an arbitrary number of argument
 .It Sx \&Ux  Ta    Yes      Ta    Yes      Ta    n
 .It Sx \&Va  Ta    Yes      Ta    Yes      Ta    n
 .It Sx \&Vt  Ta    Yes      Ta    Yes      Ta    >0
-.It Sx \&Xr  Ta    Yes      Ta    Yes      Ta    >0, <3
+.It Sx \&Xr  Ta    Yes      Ta    Yes      Ta    >0
 .It Sx \&br  Ta    \&No     Ta    \&No     Ta    0
 .It Sx \&sp  Ta    \&No     Ta    \&No     Ta    1
-.El   
-.
-.
+.El
 .Sh REFERENCE
 This section is a canonical reference of all macros, arranged
-alphabetically.  For the scoping of individual macros, see
+alphabetically.
+For the scoping of individual macros, see
 .Sx MACRO SYNTAX .
-.
 .Ss \&%A
 Author name of an
 .Sx \&Rs
@@ -827,13 +840,11 @@ block.  Multiple authors should each be accorded their
 .Sx \%%A
 line.  Author names should be ordered with full or abbreviated
 forename(s) first, then full surname.
-.
 .Ss \&%B
 Book title of an
 .Sx \&Rs
 block.  This macro may also be used in a non-bibliographic context when
 referring to book titles.
-.
 .Ss \&%C
 Publication city or location of an
 .Sx \&Rs
@@ -842,83 +853,68 @@ block.
 .Em Remarks :
 this macro is not implemented in
 .Xr groff 1 .
-.
 .Ss \&%D
 Publication date of an
 .Sx \&Rs
 block.  This should follow the reduced or canonical form syntax
 described in
 .Sx Dates .
-.
 .Ss \&%I
 Publisher or issuer name of an
 .Sx \&Rs
 block.
-.
 .Ss \&%J
 Journal name of an
 .Sx \&Rs
 block.
-.
 .Ss \&%N
 Issue number (usually for journals) of an
 .Sx \&Rs
 block.
-.
 .Ss \&%O
 Optional information of an
 .Sx \&Rs
 block.
-.
 .Ss \&%P
 Book or journal page number of an
 .Sx \&Rs
 block.
-.
 .Ss \&%Q
 Institutional author (school, government, etc.) of an
 .Sx \&Rs
 block.  Multiple institutional authors should each be accorded their own
 .Sx \&%Q
 line.
-.
 .Ss \&%R
 Technical report name of an
 .Sx \&Rs
 block.
-.
 .Ss \&%T
 Article title of an
 .Sx \&Rs
 block.  This macro may also be used in a non-bibliographical context
 when referring to article titles.
-.
 .Ss \&%U
 URI of reference document.
-.
 .Ss \&%V
 Volume number of an
 .Sx \&Rs
 block.
-.
 .Ss \&Ac
 Closes an
 .Sx \&Ao
 block.  Does not have any tail arguments.
-.
 .Ss \&Ad
 Address construct: usually in the context of an computational address in
 memory, not a physical (post) address.
 .Pp
 Examples:
-.Bd -literal -offset indent
-\&.Ad [0,$]
-\&.Ad 0x00000000
-.Ed
-.
+.D1 \&.Ad [0,$]
+.D1 \&.Ad 0x00000000
 .Ss \&An
-Author name.  This macro may alternatively accepts the following
-arguments, although these may not be specified along with a parameter:
+Author name.
+This macro may alternatively accepts the following arguments, although
+these may not be specified along with a parameter:
 .Bl -tag -width 12n -offset indent
 .It Fl split
 Renders a line break before each author listing.
@@ -929,17 +925,15 @@ The opposite of
 .Pp
 In the AUTHORS section, the default is not to split the first author
 listing, but all subsequent author listings, whether or not they're
-interspersed by other macros or text, are split.  Thus, specifying
+interspersed by other macros or text, are split.
+Thus, specifying
 .Fl split
-will cause the first listing also to be split.  If not in the AUTHORS
-section, the default is not to split.
+will cause the first listing also to be split.
+If not in the AUTHORS section, the default is not to split.
 .Pp
 Examples:
-.Bd -literal -offset indent
-\&.An -nosplit
-\&.An J. E. Hopcraft ,
-\&.An J. D. Ullman .
-.Ed
+.D1 \&.An -nosplit
+.D1 \&.An J. D. Ullman .
 .Pp
 .Em Remarks :
 the effects of
@@ -950,34 +944,27 @@ are re-set when entering the AUTHORS section, so if on
 .Sx \&An Fl nosplit
 in the general document body, it must be re-specified in the AUTHORS
 section.
-.
 .Ss \&Ao
-Begins a block enclosed by angled brackets.  Does not have any head
-arguments.
+Begins a block enclosed by angled brackets.
+Does not have any head arguments.
 .Pp
 Examples:
-.Bd -literal -offset indent
-\&.Fl -key= Ns Ao Ar val Ac
-.Ed
+.D1 \&.Fl -key= \&Ns \&Ao \&Ar val \&Ac
 .Pp
 See also
 .Sx \&Aq .
-.
 .Ss \&Ap
-Inserts an apostrophe without any surrounding white-space.  This is
-generally used as a grammatic device when referring to the verb form of
-a function:
+Inserts an apostrophe without any surrounding white-space.
+This is generally used as a grammatic device when referring to the verb
+form of a function:
 .Bd -literal -offset indent
 \&.Fn execve Ap d
 .Ed
-.
 .Ss \&Aq
-Encloses its arguments in angled brackets.  
+Encloses its arguments in angled brackets.
 .Pp
 Examples:
-.Bd -literal -offset indent
-\&.Fl -key= Ns Aq Ar val
-.Ed
+.D1 \&.Fl -key= \&Ns \&Aq \&Ar val
 .Pp
 .Em Remarks :
 this macro is often abused for rendering URIs, which should instead use
@@ -991,21 +978,19 @@ statements, which should use
 .Pp
 See also
 .Sx \&Ao .
-.
 .Ss \&Ar
-Command arguments.  If an argument is not provided, the string
+Command arguments.
+If an argument is not provided, the string
 .Dq file ...
 is used as a default.
 .Pp
 Examples:
-.Bd -literal -offset indent
-\&.Fl o Ns Ar file1
-\&.Ar
-\&.Ar arg1 , arg2 .
-.Ed
-.
+.D1 \&.Fl o \&Ns \&Ar file1
+.D1 \&.Ar
+.D1 \&.Ar arg1 , arg2 .
 .Ss \&At
-Formats an AT&T version.  Accepts at most one parameter:
+Formats an AT&T version.
+Accepts at most one parameter:
 .Bl -tag -width 12n -offset indent
 .It Cm v[1-7] | 32v
 A version of
@@ -1018,10 +1003,8 @@ A system version of
 Note that these parameters do not begin with a hyphen.
 .Pp
 Examples:
-.Bd -literal -offset indent
-\&.At 
-\&.At V.1
-.Ed
+.D1 \&.At
+.D1 \&.At V.1
 .Pp
 See also
 .Sx \&Bsx ,
@@ -1032,17 +1015,16 @@ See also
 .Sx \&Ox ,
 and
 .Sx \&Ux .
-.
 .Ss \&Bc
 Closes a
 .Sx \&Bo
 block.  Does not have any tail arguments.
-.
 .Ss \&Bd
-Begins a display block.  A display is collection of macros or text which
-may be collectively offset or justified in a manner different from that
-of the enclosing context.  By default, the block is preceded by a
-vertical space.
+Begins a display block.
+A display is collection of macros or text which may be collectively
+offset or justified in a manner different from that
+of the enclosing context.
+By default, the block is preceded by a vertical space.
 .Pp
 Each display is associated with a type, which must be one of the
 following arguments:
@@ -1060,7 +1042,8 @@ Alias for
 Centre-justify each line.
 .El
 .Pp
-The type must be provided first.  Secondary arguments are as follows:
+The type must be provided first.
+Secondary arguments are as follows:
 .Bl -tag -width 12n -offset indent
 .It Fl offset Ar width
 Offset by the value of
@@ -1081,8 +1064,8 @@ which justifies to the right margin; and
 .Ar center ,
 which aligns around an imagined centre axis.
 .It
-As a precalculated width for a named macro.  The most popular is the
-imaginary macro
+As a precalculated width for a named macro.
+The most popular is the imaginary macro
 .Ar \&Ds ,
 which resolves to
 .Ar 6n .
@@ -1116,31 +1099,133 @@ See also
 .Sx \&D1
 and
 .Sx \&Dl .
-.
 .Ss \&Bf
 .Ss \&Bk
 .Ss \&Bl
-.
+Begins a list composed of one or more list entries.
+A list is associated with a type, which is a required argument.
+Other arguments are
+.Fl width ,
+defined per-type as accepting a literal or
+.Sx Scaling Widths
+value;
+.Fl offset ,
+also accepting a literal or
+.Sx Scaling Widths
+value setting the list's global offset; and
+.Fl compact ,
+suppressing the default vertical space printed before each list entry.
+A list entry is specified by the
+.Sx \&It
+macro, which consists of a head and optional body (depending on the list
+type).
+A list must specify one of the following list types:
+.Bl -tag -width 12n -offset indent
+.It Fl bullet
+A list offset by a bullet.
+The head of list entries must be empty.
+List entry bodies are positioned after the bullet.
+The
+.Fl width
+argument varies the width of list bodies' left-margins.
+.It Fl column
+A columnated list.
+The
+.Fl width
+argument has no effect.
+The number of columns is specified as parameters to the
+.Sx \&Bl
+macro.
+These dictate the width of columns either as
+.Sx Scaling Widths
+or literal text.
+List entry bodies must be left empty.
+Column bodies have the following syntax:
+.Pp
+.D1 .It col1 <TAB> ... coln
+.D1 .It col1 Ta ... coln
+.D1 .It col1 <TAB> col2 Ta coln
+.Pp
+where columns may be separated by tabs, the literal string
+.Qq Ta ,
+or a mixture of both.
+These are equivalent except that quoted sections propogate over tabs,
+for example,
+.Pp
+.D1 .It \(dqcol1 ; <TAB> col2 ;\(dq ;
+.Pp
+will preserve the semicolon whitespace except for the last.
+.It Fl dash
+A list offset by a dash (hyphen).
+The head of list entries must be empty.
+List entry bodies are positioned past the dash.
+The
+.Fl width
+argument varies the width of list bodies' left-margins.
+.It Fl diag
+Like
+.Fl inset ,
+but with additional formatting to the head.
+The
+.Fl width
+argument varies the width of list bodies' left-margins.
+.It Fl enum
+An enumerated list offset by the enumeration from 1.
+The head of list entries must be empty.
+List entry bodies are positioned after the enumeration.
+The
+.Fl width
+argument varies the width of list bodies' left-margins.
+.It Fl hang
+Like
+.Fl tag ,
+but instead of list bodies positioned after the head, they trail the
+head text.
+The
+.Fl width
+argument varies the width of list bodies' left-margins.
+.It Fl hyphen
+Synonym for
+.Fl dash .
+.It Fl inset
+List bodies follow the list head.
+The
+.Fl width
+argument is ignored.
+.It Fl item
+This produces blocks of text.
+The head of list entries must be empty.
+The
+.Fl width
+argument is ignored.
+.It Fl ohang
+List bodies are positioned on the line following the head.
+The
+.Fl width
+argument is ignored.
+.It Fl tag
+A list offset by list entry heads.  List entry bodies are positioned
+after the head as specified by the
+.Fl width
+argument.
+.El
 .Ss \&Bo
-Begins a block enclosed by square brackets.  Does not have any head
-arguments.
+Begins a block enclosed by square brackets.
+Does not have any head arguments.
 .Pp
 Examples:
 .Bd -literal -offset indent
 \&.Bo 1 ,
-\&.Dv BUFSIZ Bc
+\&.Dv BUFSIZ \&Bc
 .Ed
 .Pp
 See also
 .Sx \&Bq .
-.
 .Ss \&Bq
-Encloses its arguments in square brackets.  
+Encloses its arguments in square brackets.
 .Pp
 Examples:
-.Bd -literal -offset indent
-\&.Bq 1 , Dv BUFSIZ
-.Ed
+.D1 \&.Bq 1 , \&Dv BUFSIZ
 .Pp
 .Em Remarks :
 this macro is sometimes abused to emulate optional arguments for
@@ -1152,45 +1237,37 @@ and
 .Pp
 See also
 .Sx \&Bo .
-.
 .Ss \&Brc
 Closes a
 .Sx \&Bro
 block.  Does not have any tail arguments.
-.
 .Ss \&Bro
-Begins a block enclosed by curly braces.  Does not have any head
-arguments.
+Begins a block enclosed by curly braces.
+Does not have any head arguments.
 .Pp
 Examples:
 .Bd -literal -offset indent
 \&.Bro 1 , ... ,
-\&.Va n Brc
+\&.Va n \&Brc
 .Ed
 .Pp
 See also
 .Sx \&Brq .
-.
 .Ss \&Brq
 Encloses its arguments in curly braces.
 .Pp
 Examples:
-.Bd -literal -offset indent
-\&.Brq 1 , ... , Va n
-.Ed
+.D1 \&.Brq 1 , ... , \&Va n
 .Pp
 See also
 .Sx \&Bro .
-.
 .Ss \&Bsx
 Format the BSD/OS version provided as an argument, or a default value if
 no argument is provided.
 .Pp
 Examples:
-.Bd -literal -offset indent
-\&.Bsx 1.0
-\&.Bsx
-.Ed
+.D1 \&.Bsx 1.0
+.D1 \&.Bsx
 .Pp
 See also
 .Sx \&At ,
@@ -1201,20 +1278,16 @@ See also
 .Sx \&Ox ,
 and
 .Sx \&Ux .
-.
 .Ss \&Bt
 Prints
 .Dq is currently in beta test.
-.
 .Ss \&Bx
 Format the BSD version provided as an argument, or a default value if no
 argument is provided.
 .Pp
 Examples:
-.Bd -literal -offset indent
-\&.Bx 4.4
-\&.Bx
-.Ed
+.D1 \&.Bx 4.4
+.D1 \&.Bx
 .Pp
 See also
 .Sx \&At ,
@@ -1225,64 +1298,58 @@ See also
 .Sx \&Ox ,
 and
 .Sx \&Ux .
-.
 .Ss \&Cd
-Configuration declaration (suggested for use only in section four
-manuals).  This denotes strings accepted by
+Configuration declaration.
+This denotes strings accepted by
 .Xr config 8 .
 .Pp
 Examples:
-.Bd -literal -offset indent
-\&.Cd device le0 at scode?
-.Ed
+.D1 \&.Cd device le0 at scode?
 .Pp
 .Em Remarks :
 this macro is commonly abused by using quoted literals to retain
 white-space and align consecutive
 .Sx \&Cd
-declarations.  This practise is discouraged.
-.
+declarations.
+This practise is discouraged.
 .Ss \&Cm
-Command modifiers.  Useful when specifying configuration options or
-keys.
+Command modifiers.
+Useful when specifying configuration options or keys.
 .Pp
 Examples:
-.Bd -literal -offset indent
-\&.Cm ControlPath
-\&.Cm ControlMaster
-.Ed
+.D1 \&.Cm ControlPath
+.D1 \&.Cm ControlMaster
 .Pp
 See also
 .Sx \&Fl .
-.
 .Ss \&D1
-One-line indented display.  This is formatted by the default rules and
-is useful for simple indented statements.  It is followed by a newline.
+One-line indented display.
+This is formatted by the default rules and is useful for simple indented
+statements.
+It is followed by a newline.
 .Pp
 Examples:
-.Bd -literal -offset indent
-\&.D1 Fl abcdefgh
-.Ed
+.D1 \&.D1 \&Fl abcdefgh
 .Pp
 See also
 .Sx \&Bd
 and
 .Sx \&Dl .
-.
 .Ss \&Db
 .Ss \&Dc
 Closes a
 .Sx \&Do
 block.  Does not have any tail arguments.
-.
 .Ss \&Dd
-Document date.  This is the mandatory first macro of any
+Document date.
+This is the mandatory first macro of any
 .Nm
-manual.  Its calling syntax is as follows:
+manual.
+Its calling syntax is as follows:
 .Pp
 .D1 \. Ns Sx \&Dd Cm date
 .Pp
-The 
+The
 .Cm date
 field may be either
 .Ar $\&Mdocdate$ ,
@@ -1293,69 +1360,64 @@ or instead a valid canonical date as specified by
 If a date does not conform, the current date is used instead.
 .Pp
 Examples:
-.Bd -literal -offset indent
-\&.Dd $\&Mdocdate$
-\&.Dd $\&Mdocdate: July 21 2007$
-\&.Dd July 21, 2007
-.Ed
+.D1 \&.Dd $\&Mdocdate$
+.D1 \&.Dd $\&Mdocdate: July 21 2007$
+.D1 \&.Dd July 21, 2007
 .Pp
 See also
 .Sx \&Dt
 and
 .Sx \&Os .
-.
 .Ss \&Dl
-One-line intended display.  This is formatted as literal text and is
-useful for commands and invocations.  It is followed by a newline.
+One-line intended display.
+This is formatted as literal text and is useful for commands and
+invocations.
+It is followed by a newline.
 .Pp
 Examples:
-.Bd -literal -offset indent
-\&.Dl % mandoc mdoc.7 | less
-.Ed
+.D1 \&.Dl % mandoc mdoc.7 | less
 .Pp
 See also
 .Sx \&Bd
 and
 .Sx \&D1 .
-.
 .Ss \&Do
 Begins a block enclosed by double quotes.  Does not have any head
 arguments.
 .Pp
 Examples:
-.Bd -literal -offset indent
-\&.D1 Do April is the cruellest month Dc \e(em T.S. Eliot
-.Ed
+.D1 \&.D1 \&Do April is the cruellest month \&Dc \e(em T.S. Eliot
 .Pp
 See also
 .Sx \&Dq .
-.
 .Ss \&Dq
-Encloses its arguments in double quotes.  
+Encloses its arguments in double quotes.
 .Pp
 Examples:
-.Bd -literal -offset indent
+.Bd -literal -offset indent -compact
 \&.Dq April is the cruellest month
 \e(em T.S. Eliot
 .Ed
 .Pp
 See also
 .Sx \&Do .
-.
 .Ss \&Dt
-Document title.  This is the mandatory second macro of any
+Document title.
+This is the mandatory second macro of any
 .Nm
-file.  Its calling syntax is as follows:
+file.
+Its calling syntax is as follows:
 .Pp
 .D1 \. Ns Sx \&Dt Cm title section Op Cm volume | arch
 .Pp
 Its arguments are as follows:
 .Bl -tag -width Ds -offset Ds
 .It Cm title
-The document's title (name).  This should be capitalised and is
-required.
+The document's title (name).
+This should be capitalised and is required.
 .It Cm section
-The manual section.  This may be one of
+The manual section.
+This may be one of
 .Ar 1
 .Pq utilities ,
 .Ar 2
@@ -1421,10 +1483,13 @@ or
 .Ar CON
 .Pq contributed manuals .
 .It Cm arch
-This specifies a specific relevant architecture.  If
+This specifies a specific relevant architecture.
+If
 .Cm volume
 is not provided, it may be used in its place, else it may be used
-subsequent that.  It, too, is optional.  It must be one of
+subsequent that.
+It, too, is optional.
+It must be one of
 .Ar alpha ,
 .Ar amd64 ,
 .Ar amiga ,
@@ -1437,6 +1502,7 @@ subsequent that.  It, too, is optional.  It must be on
 .Ar hppa64 ,
 .Ar i386 ,
 .Ar landisk ,
+.Ar loongson ,
 .Ar luna88k ,
 .Ar mac68k ,
 .Ar macppc ,
@@ -1455,39 +1521,31 @@ or
 .El
 .Pp
 Examples:
-.Bd -literal -offset indent
-\&.Dt FOO 1
-\&.Dt FOO 4 KM
-\&.Dt FOO 9 i386
-\&.Dt FOO 9 KM i386
-.Ed
+.D1 \&.Dt FOO 1
+.D1 \&.Dt FOO 4 KM
+.D1 \&.Dt FOO 9 i386
+.D1 \&.Dt FOO 9 KM i386
 .Pp
 See also
 .Sx \&Dd
 and
 .Sx \&Os .
-.
 .Ss \&Dv
 Defined variables such as preprocessor constants.
 .Pp
 Examples:
-.Bd -literal -offset indent
-\&.Dv BUFSIZ
-\&.Dv STDOUT_FILENO
-.Ed
+.D1 \&.Dv BUFSIZ
+.D1 \&.Dv STDOUT_FILENO
 .Pp
 See also
 .Sx \&Er .
-.
 .Ss \&Dx
 Format the DragonFly BSD version provided as an argument, or a default
 value if no argument is provided.
 .Pp
 Examples:
-.Bd -literal -offset indent
-\&.Dx 2.4.1
-\&.Dx
-.Ed
+.D1 \&.Dx 2.4.1
+.D1 \&.Dx
 .Pp
 See also
 .Sx \&At ,
@@ -1498,52 +1556,41 @@ See also
 .Sx \&Ox ,
 and
 .Sx \&Ux .
-.
 .Ss \&Ec
 .Ss \&Ed
 .Ss \&Ef
 .Ss \&Ek
 .Ss \&El
 .Ss \&Em
-Denotes text that should be emphasised.  Note that this is a
-presentation term and should not be used for stylistically decorating
-technical terms.
+Denotes text that should be emphasised.
+Note that this is a presentation term and should not be used for
+stylistically decorating technical terms.
 .Pp
 Examples:
-.Bd -literal -offset indent
-\&.Ed Warnings!
-\&.Ed Remarks :
-.Ed
-.
+.D1 \&.Em Warnings!
+.D1 \&.Em Remarks :
 .Ss \&En
 .Ss \&Eo
 .Ss \&Er
-Error constants (suggested for use only in section two manuals).
+Display error constants.
 .Pp
 Examples:
-.Bd -literal -offset indent
-\&.Er EPERM
-\&.Er ENOENT
-.Ed
+.D1 \&.Er EPERM
+.D1 \&.Er ENOENT
 .Pp
 See also
 .Sx \&Dv .
-.
 .Ss \&Es
-.
 .Ss \&Ev
 Environmental variables such as those specified in
 .Xr environ 7 .
 .Pp
 Examples:
-.Bd -literal -offset indent
-\&.Ev DISPLAY
-\&.Ev PATH
-.Ed
-.
+.D1 \&.Ev DISPLAY
+.D1 \&.Ev PATH
 .Ss \&Ex
-Inserts text regarding a utility's exit values.  This macro must have
-first the
+Inserts text regarding a utility's exit values.
+This macro must have first the
 .Fl std
 argument specified, then an optional
 .Ar utility .
@@ -1556,6 +1603,23 @@ is provided.
 .Ss \&Fc
 .Ss \&Fd
 .Ss \&Fl
+Command-line flag.
+Used when listing arguments to command-line utilities.
+Prints a fixed-width hyphen
+.Sq \-
+directly followed by each argument.
+If no arguments are provided, a hyphen is printed followed by a space.
+If the argument is a macro, a hyphen is prefixed to the subsequent macro
+output.
+.Pp
+Examples:
+.D1 \&.Fl a b c
+.D1 \&.Fl \&Pf a b
+.D1 \&.Fl
+.D1 \&.Op \&Fl o \&Ns \&Ar file
+.Pp
+See also
+.Sx \&Cm .
 .Ss \&Fn
 .Ss \&Fo
 .Ss \&Fr
@@ -1565,10 +1629,8 @@ Format the FreeBSD version provided as an argument, or
 if no argument is provided.
 .Pp
 Examples:
-.Bd -literal -offset indent
-\&.Fx 7.1
-\&.Fx
-.Ed
+.D1 \&.Fx 7.1
+.D1 \&.Fx
 .Pp
 See also
 .Sx \&At ,
@@ -1579,27 +1641,46 @@ See also
 .Sx \&Ox ,
 and
 .Sx \&Ux .
-.
 .Ss \&Hf
 .Ss \&Ic
 .Ss \&In
 .Ss \&It
 .Ss \&Lb
+Specify a library.
+The calling syntax is as follows:
+.Pp
+.D1 \. Ns Sx \&Lb Cm library
+.Pp
+The
+.Cm library
+parameter may be a system library, such as
+.Cm libz
+or
+.Cm libpam ,
+in which case a small library description is printed next to the linker
+invocation; or a custom library, in which case the library name is
+printed in quotes.
+This is most commonly used in the
+.Em SYNOPSIS
+section as described in
+.Sx MANUAL STRUCTURE .
+.Pp
+Examples:
+.D1 \&.Lb libz
+.D1 \&.Lb mdoc
 .Ss \&Li
 .Ss \&Lk
-Format a hyperlink.  The calling syntax is as follows:
+Format a hyperlink.
+The calling syntax is as follows:
 .Pp
 .D1 \. Ns Sx \&Lk Cm uri Op Cm name
 .Pp
 Examples:
-.Bd -literal -offset indent
-\&.Lk http://bsd.lv "The BSD.lv Project"
-\&.Lk http://bsd.lv
-.Ed
+.D1 \&.Lk http://bsd.lv "The BSD.lv Project"
+.D1 \&.Lk http://bsd.lv
 .Pp
 See also
 .Sx \&Mt .
-.
 .Ss \&Lp
 .Ss \&Ms
 .Ss \&Mt
@@ -1612,10 +1693,8 @@ Format the NetBSD version provided as an argument, or 
 no argument is provided.
 .Pp
 Examples:
-.Bd -literal -offset indent
-\&.Nx 5.01
-\&.Nx
-.Ed
+.D1 \&.Nx 5.01
+.D1 \&.Nx
 .Pp
 See also
 .Sx \&At ,
@@ -1626,12 +1705,12 @@ See also
 .Sx \&Ox ,
 and
 .Sx \&Ux .
-.
 .Ss \&Oc
 .Ss \&Oo
 .Ss \&Op
 .Ss \&Os
-Document operating system version.  This is the mandatory third macro of
+Document operating system version.
+This is the mandatory third macro of
 any
 .Nm
 file.  Its calling syntax is as follows:
@@ -1640,37 +1719,31 @@ file.  Its calling syntax is as follows:
 .Pp
 The optional
 .Cm system
-parameter specifies the relevant operating system or environment.  Left
-unspecified, it defaults to the local operating system version.  This is
-the suggested form.
+parameter specifies the relevant operating system or environment.
+Left unspecified, it defaults to the local operating system version.
+This is the suggested form.
 .Pp
 Examples:
-.Bd -literal -offset indent
-\&.Os
-\&.Os KTH/CSC/TCS
-\&.Os BSD 4.3
-.Ed
+.D1 \&.Os
+.D1 \&.Os KTH/CSC/TCS
+.D1 \&.Os BSD 4.3
 .Pp
 See also
 .Sx \&Dd
 and
 .Sx \&Dt .
-.
 .Ss \&Ot
 Unknown usage.
 .Pp
 .Em Remarks :
 this macro has been deprecated.
-.
 .Ss \&Ox
 Format the OpenBSD version provided as an argument, or a default value
 if no argument is provided.
 .Pp
 Examples:
-.Bd -literal -offset indent
-\&.Ox 4.5
-\&.Ox
-.Ed
+.D1 \&.Ox 4.5
+.D1 \&.Ox
 .Pp
 See also
 .Sx \&At ,
@@ -1681,7 +1754,6 @@ See also
 .Sx \&Nx ,
 and
 .Sx \&Ux .
-.
 .Ss \&Pa
 .Ss \&Pc
 .Ss \&Pf
@@ -1692,17 +1764,17 @@ and
 .Ss \&Ql
 .Ss \&Qo
 .Ss \&Qq
-.
 .Ss \&Re
 Closes a
 .Sx \&Rs
-block.  Does not have any tail arguments.
-.
+block.
+Does not have any tail arguments.
 .Ss \&Rs
 Begins a bibliographic
 .Pq Dq reference
-block.  Does not have any head arguments.  The block macro may only
-contain
+block.
+Does not have any head arguments.
+The block macro may only contain
 .Sx \&%A ,
 .Sx \&%B ,
 .Sx \&%C ,
@@ -1720,7 +1792,7 @@ and
 child macros (at least one must be specified).
 .Pp
 Examples:
-.Bd -literal -offset indent
+.Bd -literal -offset indent -compact
 \&.Rs
 \&.%A J. E. Hopcroft
 \&.%A J. D. Ullman
@@ -1736,7 +1808,6 @@ If an
 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
@@ -1749,13 +1820,14 @@ line.
 .Ss \&Sy
 .Ss \&Tn
 .Ss \&Ud
+Prints out
+.Dq currently under development.
 .Ss \&Ux
-Format the UNIX name.  Accepts no argument.
+Format the UNIX name.
+Accepts no argument.
 .Pp
 Examples:
-.Bd -literal -offset indent
-\&.Ux
-.Ed
+.D1 \&.Ux
 .Pp
 See also
 .Sx \&At ,
@@ -1766,50 +1838,121 @@ See also
 .Sx \&Nx ,
 and
 .Sx \&Ox .
-.
 .Ss \&Va
 .Ss \&Vt
+A variable type.
+This is also used for indicating global variables in the SYNOPSIS
+section, in which case a variable name is also specified.
+Note that it accepts
+.Sx Block partial-implicit
+syntax when invoked as the first macro in the SYNOPSIS section, else it
+accepts ordinary
+.Sx In-line
+syntax.
+.Pp
+Note that this should not be confused with
+.Sx \&Ft ,
+which is used for function return types.
+.Pp
+Examples:
+.D1 \&.Vt unsigned char
+.D1 \&.Vt extern const char * const sys_signame[] ;
+.Pp
+See also
+.Sx \&Ft
+and
+.Sx \&Va .
 .Ss \&Xc
+Close a scope opened by
+.Sx \&Xo .
 .Ss \&Xo
+Open an extension scope.
+This macro originally existed to extend the 9-argument limit of troff;
+since this limit has been lifted, the macro has been deprecated.
 .Ss \&Xr
+Link to another manual
+.Pq Qq cross-reference .
+Its calling syntax is
+.Pp
+.D1 \. Ns Sx \&Xr Cm name section
+.Pp
+The
+.Cm name
+and
+.Cm section
+are the name and section of the linked manual.
+If
+.Cm section
+is followed by non-punctuation, an
+.Sx \&Ns
+is inserted into the token stream.
+This behaviour is for compatibility with
+.Xr groff 1 .
+.Pp
+Examples:
+.D1 \&.Xr mandoc 1
+.D1 \&.Xr mandoc 1 ;
+.D1 \&.Xr mandoc 1 \&Ns s behaviour
 .Ss \&br
 .Ss \&sp
-.
-.
 .Sh COMPATIBILITY
-This section documents compatibility with other roff implementations, at
-this time limited to
-.Xr groff 1 .
+This section documents compatibility between mandoc and other other
+troff implementations, at this time limited to GNU troff
+.Pq Qq groff .
 The term
 .Qq historic groff
-refers to those versions before the
+refers to groff versions before the
 .Pa doc.tmac
 file re-write
 .Pq somewhere between 1.15 and 1.19 .
-.
 .Pp
+Heirloom troff, the other significant troff implementation accepting
+\-mdoc, is similar to historic groff.
+.Pp
 .Bl -dash -compact
 .It
-Negative scaling units are now truncated to zero instead of creating
-interesting conditions, such as with
-.Sq \&sp -1i .
+The comment syntax
+.Sq \e."
+is no longer accepted.
+.It
+In groff, the
+.Sx \&Pa
+macro does not format its arguments when used in the FILES section under
+certain list types.
+mandoc does.
+.It
+Historic groff does not print a dash for empty
+.Sx \&Fl
+arguments.
+mandoc and newer groff implementations do.
+.It
+groff behaves irregularly when specifying
+.Sq \ef
+.Sx Text Decoration
+within line-macro scopes.
+mandoc follows a consistent system.
+.It
+In mandoc, negative scaling units are truncated to zero; groff would
+move to prior lines.
 Furthermore, the
 .Sq f
 scaling unit, while accepted, is rendered as the default unit.
 .It
 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.
+standalone double-quote in formatted output.
+This idiosyncratic behaviour is not applicable in mandoc.
 .It
 Display types
-.Sx \&Bd Fl center
+.Sx \&Bd
+.Fl center
 and
 .Fl right
 are aliases for
-.Fl left .
-The
+.Fl left
+in manodc.  Furthermore, the
 .Fl file Ar file
-argument is ignored.  Since text is not right-justified,
+argument is ignored.
+Lastly, since text is not right-justified in mandoc (or even groff),
 .Fl ragged
 and
 .Fl filled
@@ -1818,19 +1961,14 @@ are aliases, as are
 and
 .Fl unfilled .
 .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.
+Historic groff has many un-callable macros.
+Most of these (excluding some block-level macros) are now callable.
 .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.
+but has been a proper delimiter since then.
 .It
 .Sx \&It Fl nested
 is assumed for all lists (it wasn't in historic groff): any list may be
@@ -1841,24 +1979,37 @@ lists will restart the sequence only for the sub-list.
 Some manuals use
 .Sx \&Li
 incorrectly by following it with a reserved character and expecting the
-delimiter to render.  This is not supported.
+delimiter to render.
+This is not supported in mandoc.
 .It
 In groff, the
 .Sx \&Fo
-macro only produces the first parameter.  This is no longer the case.
+macro only produces the first parameter.
+This is not the case in mandoc.
+.It
+In groff, the
+.Sx \&Cd ,
+.Sx \&Er ,
+.Sx \&Ex ,
+and
+.Sx \&Rv
+macros were stipulated only to occur in certain manual sections.
+mandoc does not have these restrictions.
+.It
+Newer groff and mandoc print
+.Qq AT&T UNIX
+prior to unknown arguments of
+.Sx \&At ;
+older groff did nothing.
 .El
-.
-.
 .Sh SEE ALSO
 .Xr mandoc 1 ,
 .Xr mandoc_char 7
-.
-.
 .Sh AUTHORS
 The
 .Nm
 reference was written by
-.An Kristaps Dzonsons Aq kristaps@kth.se .
+.An Kristaps Dzonsons Aq kristaps@bsd.lv .
 .\"
 .\" XXX: this really isn't the place for these caveats.
 .\" .