===================================================================
RCS file: /cvs/mandoc/mdoc.7,v
retrieving revision 1.139
retrieving revision 1.148
diff -u -p -r1.139 -r1.148
--- mandoc/mdoc.7	2010/07/19 15:43:10	1.139
+++ mandoc/mdoc.7	2010/08/07 10:31:32	1.148
@@ -1,4 +1,4 @@
-.\"	$Id: mdoc.7,v 1.139 2010/07/19 15:43:10 kristaps Exp $
+.\"	$Id: mdoc.7,v 1.148 2010/08/07 10:31:32 kristaps Exp $
 .\"
 .\" Copyright (c) 2009, 2010 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org>
@@ -15,7 +15,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: July 19 2010 $
+.Dd $Mdocdate: August 7 2010 $
 .Dt MDOC 7
 .Os
 .Sh NAME
@@ -28,9 +28,11 @@ language is used to format
 .Bx
 .Ux
 manuals.
-In this reference document, we describe its syntax, structure, and
+This reference document describes its syntax, structure, and
 usage.
-Our reference implementation is mandoc; the
+The reference implementation is
+.Xr mandoc 1 ;
+the
 .Sx COMPATIBILITY
 section describes compatibility with other troff \-mdoc implementations.
 .Pp
@@ -61,7 +63,7 @@ line.
 A macro line with only a control character and comment escape,
 .Sq \&.\e\*q ,
 is also ignored.
-Macro lines with only a control character and optionally whitespace are
+Macro lines with only a control character and optional whitespace are
 stripped from input.
 .Ss Reserved Characters
 Within a macro line, the following characters are reserved:
@@ -93,10 +95,10 @@ Within a macro line, the following characters are rese
 .Pp
 Use of reserved characters is described in
 .Sx MACRO SYNTAX .
-For general use in macro lines, these characters must either be escaped
+For general use in macro lines, these characters can either be escaped
 with a non-breaking space
 .Pq Sq \e&
-or, if applicable, an appropriate escape sequence used.
+or, if applicable, an appropriate escape sequence can be used.
 .Ss Special Characters
 Special characters may occur in both macro and free-form lines.
 Sequences begin with the escape character
@@ -107,7 +109,7 @@ for two-character sequences; an open-bracket
 .Sq \&[
 for n-character sequences (terminated at a close-bracket
 .Sq \&] ) ;
-or a single one-character sequence.
+or a single one character sequence.
 See
 .Xr mandoc_char 7
 for a complete list.
@@ -120,7 +122,7 @@ and
 .Ss Text Decoration
 Terms may be text-decorated using the
 .Sq \ef
-escape followed by an indicator: B (bold), I, (italic), R (Roman), or P
+escape followed by an indicator: B (bold), I (italic), R (Roman), or P
 (revert to previous mode):
 .Pp
 .D1 \efBbold\efR \efIitalic\efP
@@ -147,7 +149,7 @@ recommended for
 which encourages semantic annotation.
 .Ss Predefined Strings
 Historically,
-.Xr groff 1
+troff
 also defined a set of package-specific
 .Dq predefined strings ,
 which, like
@@ -172,7 +174,7 @@ and
 .Pq vertical bar .
 .Ss Whitespace
 Whitespace consists of the space character.
-In free-form lines, whitespace is preserved within a line; un-escaped
+In free-form lines, whitespace is preserved within a line; unescaped
 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.
@@ -180,24 +182,18 @@ within literal contexts.
 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
+Macro arguments may be quoted with double-quotes 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
+The next double-quote not pairwise adjacent to another double-quote
 terminates the literal, regardless of surrounding whitespace.
 .Pp
-This produces tokens
-.Sq a" ,
-.Sq b c ,
-.Sq de ,
-and
-.Sq fg" .
-Note that any quoted term, be it argument or macro, is indiscriminately
-considered literal text.
+Note that any quoted text, even if it would cause a macro invocation
+when unquoted, is considered literal text.
 Thus, the following produces
-.Sq \&Em a :
+.Sq Op "Fl a" :
 .Bd -literal -offset indent
-\&.Em "Em a"
+\&.Op "Fl a"
 .Ed
 .Pp
 In free-form mode, quotes are regarded as opaque text.
@@ -282,7 +278,7 @@ 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
+When composing a manual, make sure that 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,
@@ -294,7 +290,8 @@ delimiters (
 .Sq \&" ) .
 .Pp
 The proper spacing is also intelligently preserved if a sentence ends at
-the boundary of a macro line, e.g.,
+the boundary of a macro line.
+For example:
 .Pp
 .D1 \&Xr mandoc 1 \.
 .D1 \&Fl T \&Ns \&Cm ascii \.
@@ -304,12 +301,12 @@ A well-formed
 document consists of a document prologue followed by one or more
 sections.
 .Pp
-The prologue, which consists of (in order) the
+The prologue, which consists of the
 .Sx \&Dd ,
 .Sx \&Dt ,
 and
 .Sx \&Os
-macros, is required for every document.
+macros in that order, is required for every document.
 .Pp
 The first section (sections are denoted by
 .Sx \&Sh )
@@ -367,19 +364,19 @@ utility processes files ...
 \&.\e\*q .Sh SECURITY CONSIDERATIONS
 .Ed
 .Pp
-The sections in a
+The sections in an
 .Nm
 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 name(s) and a one line description of the documented material.
 The syntax for this as follows:
 .Bd -literal -offset indent
-\&.Nm name0
-\&.Nm name1
+\&.Nm name0 ,
+\&.Nm name1 ,
 \&.Nm name2
-\&.Nd a short description
+\&.Nd a one line description
 .Ed
 .Pp
 The
@@ -421,8 +418,8 @@ generally structured as follows:
 .Pp
 For the second, function calls (sections 2, 3, 9):
 .Bd -literal -offset indent
-\&.Vt extern const char *global;
 \&.In header.h
+\&.Vt extern const char *global;
 \&.Ft "char *"
 \&.Fn foo "const char *src"
 \&.Ft "char *"
@@ -451,7 +448,7 @@ section, particularly
 and
 .Sx \&Ft .
 All of these macros are output on their own line.
-If two such dissimilar macros are pair-wise invoked (except for
+If two such dissimilar macros are pairwise invoked (except for
 .Sx \&Ft
 before
 .Sx \&Fo
@@ -472,14 +469,14 @@ with the text immediately following the
 .Sx \&Nm
 macro, up to the next
 .Sx \&Nm ,
-.Sx \&Sx ,
+.Sx \&Sh ,
 or
 .Sx \&Ss
 macro or the end of an enclosing block, whichever comes first.
 .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
+It usually contains a breakdown of the options (if documenting a
 command), such as:
 .Bd -literal -offset indent
 The arguments are as follows:
@@ -495,31 +492,30 @@ 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.
+This section 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 .
+Lists the environment variables used by the utility,
+and explains the syntax and semantics of their values.
+The
+.Xr environ 7
+manual provides examples of typical content and formatting.
 .Pp
 See
 .Sx \&Ev .
 .It Em FILES
 Documents files used.
-It's helpful to document both the file and a short description of how
+It's helpful to document both the file name 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.
+This section documents the
+command exit status for section 1, 6, and 8 utilities.
 Historically, this information was described in
 .Em DIAGNOSTICS ,
 a practise that is now discouraged.
@@ -529,7 +525,7 @@ See
 .It Em EXAMPLES
 Example usages.
 This often contains snippets of well-formed, well-tested invocations.
-Make doubly sure that your examples work properly!
+Make sure that examples work properly!
 .It Em DIAGNOSTICS
 Documents error conditions.
 This is most useful in section 4 manuals.
@@ -563,26 +559,25 @@ section should be used instead.
 See
 .Sx \&St .
 .It Em HISTORY
-The history of any manual without a
-.Em STANDARDS
-section should be described in this section.
+A brief history of the subject, including where support first appeared.
 .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.
+Credits to the person or persons who wrote the code and/or documentation.
+Authors should generally be noted by both name and email address.
 .Pp
 See
 .Sx \&An .
 .It Em CAVEATS
-Explanations of common misuses and misunderstandings should be explained
+Common misuses and misunderstandings should be explained
 in this section.
 .It Em BUGS
-Extant bugs should be described in this section.
+Known bugs, limitations, and work-arounds 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 ,
+control character,
 .Sq \&. ,
 at the beginning of the line.
 An arbitrary amount of whitespace may sit between the control character
@@ -615,10 +610,10 @@ produces
 .Sq Fl \&Sh .
 .Pp
 The
-.Em Parsable
+.Em Parsed
 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
+If a macro is not parsed, subsequent macro invocations on the line
 will be interpreted as opaque text.
 .Pp
 The
@@ -635,8 +630,8 @@ contains a head.
 \&.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
+.Bl -column -compact -offset indent "MacroX" "CallableX" "ParsedX" "closed by XXX"
+.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
 .It Sx \&Bd  Ta    \&No     Ta    \&No     Ta    closed by Sx \&Ed
 .It Sx \&Bf  Ta    \&No     Ta    \&No     Ta    closed by Sx \&Ef
 .It Sx \&Bk  Ta    \&No     Ta    \&No     Ta    closed by Sx \&Ek
@@ -658,7 +653,9 @@ All macros have bodies; some
 .Pc
 don't have heads; only one
 .Po
-.Sx \&It Fl column
+.Sx \&It
+in
+.Sx \&Bl Fl column
 .Pc
 has multiple heads.
 .Bd -literal -offset indent
@@ -666,8 +663,8 @@ has multiple heads.
 \(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
+.Bl -column -compact -offset indent "MacroX" "CallableX" "ParsedX" "closed by XXXXXXXXXXX"
+.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
 .It Sx \&It  Ta    \&No     Ta    Yes      Ta    closed by Sx \&It , Sx \&El
 .It Sx \&Nd  Ta    \&No     Ta    \&No     Ta    closed by Sx \&Sh
 .It Sx \&Nm  Ta    \&No     Ta  Yes Ta closed by Sx \&Nm , Sx \&Sh , Sx \&Ss
@@ -702,8 +699,8 @@ and/or tail
 \(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
+.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -compact -offset indent
+.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
 .It Sx \&Ac  Ta    Yes      Ta    Yes      Ta    opened by Sx \&Ao
 .It Sx \&Ao  Ta    Yes      Ta    Yes      Ta    closed by Sx \&Ac
 .It Sx \&Bc  Ta    Yes      Ta    Yes      Ta    closed by Sx \&Bo
@@ -737,8 +734,8 @@ or end of line.
 \&.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
+.Bl -column "MacroX" "CallableX" "ParsedX" -compact -offset indent
+.It Em Macro Ta Em Callable Ta Em Parsed
 .It Sx \&Aq  Ta    Yes      Ta    Yes
 .It Sx \&Bq  Ta    Yes      Ta    Yes
 .It Sx \&Brq Ta    Yes      Ta    Yes
@@ -771,15 +768,15 @@ If a number (or inequality) of arguments is
 .Pq n ,
 then the macro accepts an arbitrary number of arguments.
 .Bd -literal -offset indent
-\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(lbres...\(rb
+\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(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
+.Bl -column "MacroX" "CallableX" "ParsedX" "Arguments" -compact -offset indent
+.It Em Macro Ta Em Callable Ta Em Parsed 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
@@ -805,7 +802,7 @@ then the macro accepts an arbitrary number of argument
 .It Sx \&Cd  Ta    Yes      Ta    Yes      Ta    >0
 .It Sx \&Cm  Ta    Yes      Ta    Yes      Ta    n
 .It Sx \&Db  Ta    \&No     Ta    \&No     Ta    1
-.It Sx \&Dd  Ta    \&No     Ta    \&No     Ta    >0
+.It Sx \&Dd  Ta    \&No     Ta    \&No     Ta    n
 .It Sx \&Dt  Ta    \&No     Ta    \&No     Ta    n
 .It Sx \&Dv  Ta    Yes      Ta    Yes      Ta    n
 .It Sx \&Dx  Ta    Yes      Ta    Yes      Ta    n
@@ -879,10 +876,6 @@ referring to book titles.
 Publication city or location of an
 .Sx \&Rs
 block.
-.Pp
-.Em Remarks :
-this macro is not implemented in
-.Xr groff 1 .
 .Ss \&%D
 Publication date of an
 .Sx \&Rs
@@ -933,52 +926,50 @@ Volume number of an
 .Sx \&Rs
 block.
 .Ss \&Ac
-Closes an
+Close 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.
+Memory address.
+Do not use this for postal addresses.
 .Pp
 Examples:
 .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:
-.Bl -tag -width 12n -offset indent
+Requires either the name of an author or one of the following arguments:
+.Pp
+.Bl -tag -width "-nosplitX" -offset indent -compact
 .It Fl split
-Renders a line break before each author listing.
+Start a new output line before each subsequent invocation of
+.Sx \&An .
 .It Fl nosplit
 The opposite of
 .Fl split .
 .El
 .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
+The default is
+.Fl nosplit .
+The effect of selecting either of the
 .Fl split
-will cause the first listing also to be split.
-If not in the AUTHORS section, the default is not to split.
+modes ends at the beginning of the
+.Em AUTHORS
+section.
+In the
+.Em AUTHORS
+section, the default is
+.Fl nosplit
+for the first author listing and
+.Fl split
+for all other author listings.
 .Pp
 Examples:
 .D1 \&.An -nosplit
-.D1 \&.An J. D. Ullman .
-.Pp
-.Em Remarks :
-the effects of
-.Fl split
-or
-.Fl nosplit
-are re-set when entering the AUTHORS section, so if one specifies
-.Sx \&An Fl nosplit
-in the general document body, it must be re-specified in the AUTHORS
-section.
+.D1 \&.An Kristaps Dzonsons \&Aq kristaps@bsd.lv
 .Ss \&Ao
-Begins a block enclosed by angled brackets.
+Begin a block enclosed by angle brackets.
 Does not have any head arguments.
 .Pp
 Examples:
@@ -989,12 +980,12 @@ See also
 .Ss \&Ap
 Inserts an apostrophe without any surrounding whitespace.
 This is generally used as a grammatical device when referring to the verb
-form of a function:
-.Bd -literal -offset indent
-\&.Fn execve Ap d
-.Ed
+form of a function.
+.Pp
+Examples:
+.D1 \&.Fn execve \&Ap d
 .Ss \&Aq
-Encloses its arguments in angled brackets.
+Encloses its arguments in angle brackets.
 .Pp
 Examples:
 .D1 \&.Fl -key= \&Ns \&Aq \&Ar val
@@ -1014,7 +1005,7 @@ See also
 .Ss \&Ar
 Command arguments.
 If an argument is not provided, the string
-.Dq file ...
+.Dq file ...\&
 is used as a default.
 .Pp
 Examples:
@@ -1023,17 +1014,18 @@ Examples:
 .D1 \&.Ar arg1 , arg2 .
 .Ss \&At
 Formats an AT&T version.
-Accepts at most one parameter:
-.Bl -tag -width 12n -offset indent
+Accepts one optional argument:
+.Pp
+.Bl -tag -width "v[1-7] | 32vX" -offset indent -compact
 .It Cm v[1-7] | 32v
 A version of
 .At .
 .It Cm V[.[1-4]]?
-A system version of
-.At .
+A version of
+.At V .
 .El
 .Pp
-Note that these parameters do not begin with a hyphen.
+Note that these arguments do not begin with a hyphen.
 .Pp
 Examples:
 .D1 \&.At
@@ -1049,83 +1041,93 @@ See also
 and
 .Sx \&Ux .
 .Ss \&Bc
-Closes a
+Close a
 .Sx \&Bo
 block.
 Does not have any tail arguments.
 .Ss \&Bd
-Begins a display block.
+Begin a display block.
 Its syntax is as follows:
 .Bd -ragged -offset indent
 .Pf \. Sx \&Bd
-.Fl type
+.Fl Ns Ar type
 .Op Fl offset Ar width
 .Op Fl compact
 .Ed
 .Pp
-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.
+Display blocks are used to select a different indentation and
+justification than the one used by the surrounding text.
+They may contain both macro lines and free-form text lines.
+By default, a display block is preceded by a vertical space.
 .Pp
-Each display is associated with a type, which must be one of the
-following arguments:
-.Bl -tag -width 12n -offset indent
-.It Fl ragged
-Only left-justify the block.
-.It Fl unfilled
-Do not justify the block at all.
+The
+.Ar type
+must be one of the following:
+.Bl -tag -width 13n -offset indent
+.It Fl centered
+Centre-justify each line.
+Using this display type is not recommended; many
+.Nm
+implementations render it poorly.
 .It Fl filled
 Left- and right-justify the block.
 .It Fl literal
-Alias for
-.Fl unfilled .
-.It Fl centered
-Centre-justify each line.
+Do not justify the block at all.
+Preserve white space as it appears in the input.
+.It Fl ragged
+Only left-justify the block.
+.It Fl unfilled
+An alias for
+.Fl literal .
 .El
 .Pp
-The type must be provided first.
-Secondary arguments are as follows:
-.Bl -tag -width 12n -offset indent
-.It Fl offset Ar val
-Offset by the value of
-.Ar val ,
-which is interpreted as one of the following, specified in order:
+The
+.Ar type
+must be provided first.
+Additional arguments may follow:
+.Bl -tag -width 13n -offset indent
+.It Fl offset Ar width
+Indent the display by the
+.Ar width ,
+which may be one of the following:
 .Bl -item
 .It
-As one of the pre-defined strings
-.Ar indent ,
+One of the pre-defined strings
+.Cm indent ,
 the width of standard indentation;
-.Ar indent-two ,
+.Cm indent-two ,
 twice
-.Ar indent ;
-.Ar left ,
+.Cm indent ;
+.Cm left ,
 which has no effect;
-.Ar right ,
-which justifies to the right margin; and
-.Ar center ,
+.Cm right ,
+which justifies to the right margin; or
+.Cm center ,
 which aligns around an imagined centre axis.
 .It
-As a precalculated width for a named macro.
+A macro invocation, which selects a predefined width
+associated with that macro.
 The most popular is the imaginary macro
 .Ar \&Ds ,
 which resolves to
-.Ar 6n .
+.Sy 6n .
 .It
-As a scaling unit following the syntax described in
+A width using the syntax described in
 .Sx Scaling Widths .
 .It
-As the calculated string length of the opaque string.
+An arbitrary string, which indents by the length of this string.
 .El
 .Pp
-If not provided an argument, it will be ignored.
+When the argument is missing,
+.Fl offset
+is ignored.
 .It Fl compact
-Do not assert a vertical space before the block.
+Do not assert vertical space before the display.
 .El
 .Pp
 Examples:
 .Bd -literal -offset indent
-\&.Bd \-unfilled \-offset two-indent \-compact
+\&.Bd \-literal \-offset indent \-compact
    Hello       world.
 \&.Ed
 .Ed
@@ -1152,7 +1154,7 @@ and
 argument are equivalent, as are
 .Fl symbolic
 and
-.Cm \&Sy,
+.Cm \&Sy ,
 and
 .Fl literal
 and
@@ -1166,21 +1168,22 @@ is encountered.
 See also
 .Sx \&Li ,
 .Sx \&Ef ,
+.Sx \&Em ,
 and
 .Sx \&Sy .
 .Ss \&Bk
-Begins a collection of macros or text not breaking the line.
-Its syntax is as follows:
+Keep the output generated from each macro input line together
+on one single output line.
+Line breaks in free-form text lines are unaffected.
+The syntax is as follows:
 .Pp
 .D1 Pf \. Sx \&Bk Fl words
 .Pp
-Subsequent arguments are ignored.
 The
 .Fl words
-argument is required.
+argument is required; additional arguments are ignored.
 .Pp
-Each line within a keep block is kept intact, so the following example
-will not break within each
+The following example will not break within each
 .Sx \&Op
 macro line:
 .Bd -literal -offset indent
@@ -1193,128 +1196,132 @@ macro line:
 Be careful in using over-long lines within a keep block!
 Doing so will clobber the right margin.
 .Ss \&Bl
-Begins a list composed of one or more list entries.
-Its syntax is as follows:
+Begin a list.
+Lists consist of items started by the
+.Sx \&It
+macro, containing a head or a body or both.
+The list syntax is as follows:
 .Bd -ragged -offset indent
 .Pf \. Sx \&Bl
-.Fl type
+.Fl Ns Ar type
 .Op Fl width Ar val
 .Op Fl offset Ar val
 .Op Fl compact
 .Op HEAD ...
 .Ed
 .Pp
-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
+The list
+.Ar type
+is mandatory and must be specified first.
+The
+.Fl width
+and
+.Fl offset
+arguments accept
 .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).
+or use the length of the given string.
+The
+.Fl offset
+is a global indentation for the whole list, affecting both item heads
+and bodies.
+For those list types supporting it, the
+.Fl width
+argument requests an additional indentation of item bodies,
+to be added to the
+.Fl offset .
+Unless the
+.Fl compact
+argument is specified, list entries are separated by vertical space.
+.Pp
 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
+No item heads can be specified, but a bullet will be printed at the head
+of each item.
+Item bodies start on the same output line as the bullet
+and are indented according to the
 .Fl width
-argument varies the width of list bodies' left-margins.
+argument.
 .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
+argument has no effect; instead, each argument specifies the width
+of one column, using either the
 .Sx Scaling Widths
-or literal text.
-If the initial macro of a
+syntax or the string length of the argument.
+If the first line of the body of a
 .Fl column
 list is not an
-.Sx \&It ,
-an
 .Sx \&It
-context spanning each line is implied until an
+macro line,
 .Sx \&It
-line macro is encountered, at which point list bodies are interpreted as
+contexts spanning one input line each are implied until an
+.Sx \&It
+macro line is encountered, at which point items start being interpreted as
 described in the
 .Sx \&It
 documentation.
 .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.
+Like
+.Fl bullet ,
+except that dashes are used in place of bullets.
 .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.
+except that item heads are not parsed for macro invocations.
+.\" but with additional formatting to the head.
 .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.
+A numbered list.
+Formatted like
+.Fl bullet ,
+except that cardinal numbers are used in place of bullets,
+starting at 1.
 .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.
+except that the first lines of item bodies are not indented, but follow
+the item heads like in
+.Fl inset
+lists.
 .It Fl hyphen
 Synonym for
 .Fl dash .
 .It Fl inset
-List bodies follow the list head.
-The
+Item bodies follow items heads on the same line, using normal inter-word
+spacing.
+Bodies are not indented, and the
 .Fl width
 argument is ignored.
 .It Fl item
-This produces blocks of text.
-The head of list entries must be empty.
-The
+No item heads can be specified, and none are printed.
+Bodies are not indented, and the
 .Fl width
 argument is ignored.
 .It Fl ohang
-List bodies are positioned on the line following the head.
+Item bodies start on the line following item heads and are not indented.
 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
+Item bodies are indented according to the
 .Fl width
 argument.
+When an item head fits inside the indentation, the item body follows
+this head on the same output line.
+Otherwise, the body starts on the output line following the head.
 .El
 .Pp
 See also
+.Sx \&El
+and
 .Sx \&It .
 .Ss \&Bo
-Begins a block enclosed by square brackets.
+Begin a block enclosed by square brackets.
 Does not have any head arguments.
 .Pp
 Examples:
-.Bd -literal -offset indent
+.Bd -literal -offset indent -compact
 \&.Bo 1 ,
 \&.Dv BUFSIZ \&Bc
 .Ed
@@ -1338,16 +1345,16 @@ and
 See also
 .Sx \&Bo .
 .Ss \&Brc
-Closes a
+Close a
 .Sx \&Bro
 block.
 Does not have any tail arguments.
 .Ss \&Bro
-Begins a block enclosed by curly braces.
+Begin a block enclosed by curly braces.
 Does not have any head arguments.
 .Pp
 Examples:
-.Bd -literal -offset indent
+.Bd -literal -offset indent -compact
 \&.Bro 1 , ... ,
 \&.Va n \&Brc
 .Ed
@@ -1381,7 +1388,7 @@ and
 .Sx \&Ux .
 .Ss \&Bt
 Prints
-.Dq is currently in beta test.
+.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.
@@ -1400,7 +1407,7 @@ See also
 and
 .Sx \&Ux .
 .Ss \&Cd
-Configuration declaration.
+Kernel configuration declaration.
 This denotes strings accepted by
 .Xr config 8 .
 .Pp
@@ -1437,13 +1444,15 @@ See also
 and
 .Sx \&Dl .
 .Ss \&Db
-Start a debugging context.
-This macro is parsed, but generally ignored.
+Switch debugging mode.
 Its syntax is as follows:
 .Pp
 .D1 Pf \. Sx \&Db Cm on | off
+.Pp
+This macro is ignored by
+.Xr mandoc 1 .
 .Ss \&Dc
-Closes a
+Close a
 .Sx \&Do
 block.
 Does not have any tail arguments.
@@ -1454,17 +1463,17 @@ This is the mandatory first macro of any
 manual.
 Its syntax is as follows:
 .Pp
-.D1 Pf \. Sx \&Dd Cm date
+.D1 Pf \. Sx \&Dd Op Ar date
 .Pp
 The
-.Cm date
-field may be either
+.Ar date
+may be either
 .Ar $\&Mdocdate$ ,
 which signifies the current manual revision date dictated by
 .Xr cvs 1 ,
 or instead a valid canonical date as specified by
 .Sx Dates .
-If a date does not conform, the current date is used instead.
+If a date does not conform or is empty, the current date is used.
 .Pp
 Examples:
 .D1 \&.Dd $\&Mdocdate$
@@ -1482,18 +1491,23 @@ invocations.
 It is followed by a newline.
 .Pp
 Examples:
-.D1 \&.Dl % mandoc mdoc.7 | less
+.D1 \&.Dl % mandoc mdoc.7 \e(ba less
 .Pp
 See also
 .Sx \&Bd
 and
 .Sx \&D1 .
 .Ss \&Do
-Begins a block enclosed by double quotes.
+Begin a block enclosed by double quotes.
 Does not have any head arguments.
 .Pp
 Examples:
-.D1 \&.D1 \&Do April is the cruellest month \&Dc \e(em T.S. Eliot
+.Bd -literal -offset indent -compact
+\&.Do
+April is the cruellest month
+\&.Dc
+\e(em T.S. Eliot
+.Ed
 .Pp
 See also
 .Sx \&Dq .
@@ -1522,22 +1536,22 @@ Its syntax is as follows:
 .Bd -ragged -offset indent
 .Pf \. Sx \&Dt
 .Oo
-.Cm title
+.Ar title
 .Oo
-.Cm section
-.Op Cm volume | arch
+.Ar section
+.Op Ar volume | arch
 .Oc
 .Oc
 .Ed
 .Pp
 Its arguments are as follows:
 .Bl -tag -width Ds -offset Ds
-.It Cm title
+.It Ar title
 The document's title (name), defaulting to
 .Dq UNKNOWN
 if unspecified.
 It should be capitalised.
-.It Cm section
+.It Ar section
 The manual section.
 This may be one of
 .Ar 1
@@ -1576,7 +1590,7 @@ or
 It should correspond to the manual's filename suffix and defaults to
 .Dq 1
 if unspecified.
-.It Cm volume
+.It Ar volume
 This overrides the volume inferred from
 .Ar section .
 This field is optional, and if specified, must be one of
@@ -1605,10 +1619,10 @@ This field is optional, and if specified, must be one 
 or
 .Ar CON
 .Pq contributed manuals .
-.It Cm arch
+.It Ar arch
 This specifies a specific relevant architecture.
 If
-.Cm volume
+.Ar volume
 is not provided, it may be used in its place, else it may be used
 subsequent that.
 It, too, is optional.
@@ -1683,10 +1697,10 @@ Close a scope started by
 .Sx \&Eo .
 Its syntax is as follows:
 .Pp
-.D1 Pf \. Sx \&Ec Op Cm TERM
+.D1 Pf \. Sx \&Ec Op Ar TERM
 .Pp
 The
-.Cm TERM
+.Ar TERM
 argument is used as the enclosure tail, for example, specifying \e(rq
 will emulate
 .Sx \&Dc .
@@ -1694,13 +1708,13 @@ will emulate
 End a display context started by
 .Sx \&Bd .
 .Ss \&Ef
-Ends a font mode context started by
+End a font mode context started by
 .Sx \&Bf .
 .Ss \&Ek
-Ends a keep context started by
+End a keep context started by
 .Sx \&Bk .
 .Ss \&El
-Ends a list context started by
+End a list context started by
 .Sx \&Bl .
 .Pp
 See also
@@ -1722,15 +1736,16 @@ See also
 and
 .Sx \&Li .
 .Ss \&En
-This macro is obsolete and not implemented.
+This macro is obsolete and not implemented in
+.Xr mandoc 1 .
 .Ss \&Eo
 An arbitrary enclosure.
 Its syntax is as follows:
 .Pp
-.D1 Pf \. Sx \&Eo Op Cm TERM
+.D1 Pf \. Sx \&Eo Op Ar TERM
 .Pp
 The
-.Cm TERM
+.Ar TERM
 argument is used as the enclosure head, for example, specifying \e(lq
 will emulate
 .Sx \&Do .
@@ -1753,16 +1768,16 @@ Examples:
 .D1 \&.Ev DISPLAY
 .D1 \&.Ev PATH
 .Ss \&Ex
-Inserts text regarding a utility's exit value.
-This macro must consist of the
-.Fl std
-argument followed by an optional
-.Ar utility .
-If
+Insert a standard sentence regarding exit values.
+Its syntax is as follows:
+.Pp
+.D1 Pf \. Sx \&Ex Fl std Op Ar utility
+.Pp
+When
 .Ar utility
-is not provided, the document's name as stipulated in
+is not specified, the document's name set by
 .Sx \&Nm
-is provided.
+is used.
 .Pp
 See also
 .Sx \&Rv .
@@ -1798,7 +1813,7 @@ Examples:
 See also
 .Sx \&Fo .
 .Ss \&Fc
-Ends a function context started by
+End a function context started by
 .Sx \&Fo .
 .Ss \&Fd
 Historically used to document include files.
@@ -1905,7 +1920,9 @@ See also
 and
 .Sx \&Fo .
 .Ss \&Fx
-Format the FreeBSD version provided as an argument, or a default value
+Format the
+.Fx
+version provided as an argument, or a default value
 if no argument is provided.
 .Pp
 Examples:
@@ -1934,7 +1951,7 @@ Examples:
 .D1 \&.Ic alias
 .Pp
 Note that using
-.Sx \&Bd No Fl literal
+.Sx \&Bd Fl literal
 or
 .Sx \&D1
 is preferred for displaying code; the
@@ -1949,7 +1966,7 @@ In the
 section (only if invoked as the line macro), the first argument is
 preceded by
 .Dq #include ,
-the arguments is enclosed in angled braces.
+the arguments is enclosed in angle brackets.
 .Pp
 Examples:
 .D1 \&.In sys/types
@@ -2088,7 +2105,10 @@ Synonym for
 .Sx \&Pp .
 .Ss \&Ms
 Display a mathematical symbol.
+Its syntax is as follows:
 .Pp
+.D1 Pf \. Sx \&Ms Cm symbol
+.Pp
 Examples:
 .D1 \&.Ms sigma
 .D1 \&.Ms aleph
@@ -2103,7 +2123,7 @@ Its syntax is as follows:
 Examples:
 .D1 \&.Mt discuss@manpages.bsd.lv
 .Ss \&Nd
-A one-line description of the manual's content.
+A one line description of the manual's content.
 This may only be invoked in the
 .Em SYNOPSIS
 section subsequent the
@@ -2183,7 +2203,9 @@ See also
 and
 .Sx \&Sm .
 .Ss \&Nx
-Format the NetBSD version provided as an argument, or a default value if
+Format the
+.Nx
+version provided as an argument, or a default value if
 no argument is provided.
 .Pp
 Examples:
@@ -2200,7 +2222,7 @@ See also
 and
 .Sx \&Ux .
 .Ss \&Oc
-Closes multi-line
+Close multi-line
 .Sx \&Oo
 context.
 .Ss \&Oo
@@ -2232,7 +2254,7 @@ any
 file.
 Its syntax is as follows:
 .Pp
-.D1 Pf \. Sx \&Os Op Cm system
+.D1 Pf \. Sx \&Os Op Cm system Op Cm version
 .Pp
 The optional
 .Cm system
@@ -2255,7 +2277,9 @@ Unknown usage.
 .Em Remarks :
 this macro has been deprecated.
 .Ss \&Ox
-Format the OpenBSD version provided as an argument, or a default value
+Format the
+.Ox
+version provided as an argument, or a default value
 if no argument is provided.
 .Pp
 Examples:
@@ -2334,12 +2358,12 @@ See also
 and
 .Sx \&Qo .
 .Ss \&Re
-Closes a
+Close an
 .Sx \&Rs
 block.
 Does not have any tail arguments.
 .Ss \&Rs
-Begins a bibliographic
+Begin a bibliographic
 .Pq Dq reference
 block.
 Does not have any head arguments.
@@ -2575,7 +2599,7 @@ Examples:
 .D1 \&.Tn IBM
 .Ss \&Ud
 Prints out
-.Dq currently under development.
+.Dq currently under development .
 .Ss \&Ux
 Format the UNIX name.
 Accepts no argument.
@@ -2648,14 +2672,35 @@ is followed by non-punctuation, an
 .Sx \&Ns
 is inserted into the token stream.
 This behaviour is for compatibility with
-.Xr groff 1 .
+GNU troff.
 .Pp
 Examples:
 .D1 \&.Xr mandoc 1
 .D1 \&.Xr mandoc 1 \&;
 .D1 \&.Xr mandoc 1 \&Ns s behaviour
 .Ss \&br
+Emits a line-break.
+This macro should not be used; it is implemented for compatibility with
+historical manuals.
+.Pp
+Consider using
+.Sx \&Pp
+in the event of natural paragraph breaks.
 .Ss \&sp
+Emits vertical space.
+This macro should not be used; it is implemented for compatibility with
+historical manuals.
+Its syntax is as follows:
+.Pp
+.D1 Pf \. Sx \&sp Op Cm height
+.Pp
+The
+.Cm height
+argument must be formatted as described in
+.Sx Scaling Widths .
+If unspecified,
+.Sx \&sp
+asserts a single vertical space.
 .Sh COMPATIBILITY
 This section documents compatibility between mandoc and other other
 troff implementations, at this time limited to GNU troff
@@ -2672,6 +2717,16 @@ Heirloom troff, the other significant troff implementa
 .Pp
 .Bl -dash -compact
 .It
+The
+.Sq \&%C
+macro is not implemented in GNU troff.
+.It
+An empty
+.Sq \&Dd
+macro in groff prints
+.Dq Epoch .
+In mandoc, it resolves to the current date.
+.It
 The \es (font size), \em (font colour), and \eM (font filling colour)
 font decoration escapes are all discarded in mandoc.
 .It
@@ -2748,7 +2803,7 @@ 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
+In quoted literals, groff allowed pairwise double-quotes to produce a
 standalone double-quote in formatted output.
 This idiosyncratic behaviour is not applicable in mandoc.
 .It