Major cleanup (but there is still more to come):

* rewrite .An, .Bd, .Bk, .Bl, .Ex descriptions
* correct "parsable" to "parsed"
* and various formatting and wording tweaks
This commit includes a patch from kristaps@ explaining empty .Dd.
Feedback and OK jmc@ and kristaps@.

1 files changed, 240 insertions, 226 deletions

diff --git a/usr.bin/mandoc/mdoc.7 b/usr.bin/mandoc/mdoc.7
index 1d64e581ead..80539686241 100644
--- a/usr.bin/mandoc/mdoc.7
+++ b/usr.bin/mandoc/mdoc.7
@@ -1,4 +1,4 @@
-.\"	$Id: mdoc.7,v 1.41 2010/07/25 18:05:54 schwarze Exp $
+.\"	$Id: mdoc.7,v 1.42 2010/07/31 22:07:11 schwarze 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 25 2010 $
+.Dd $Mdocdate: July 31 2010 $
 .Dt MDOC 7
 .Os
 .Sh NAME
@@ -93,10 +93,10 @@ Within a macro line, the following characters are reserved:
 .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
@@ -201,24 +201,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
 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.
@@ -325,12 +319,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 )
@@ -394,13 +388,13 @@ 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 name2
-\&.Nd a short description
+\&.Nd a one-line description
 .Ed
 .Pp
 The
@@ -493,7 +487,7 @@ 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.
@@ -524,14 +518,17 @@ It documents the return values of functions in sections 2, 3, and 9.
 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
@@ -589,21 +586,22 @@ The history of any manual without a
 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.
+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
@@ -636,10 +634,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
@@ -656,8 +654,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
@@ -679,7 +677,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
@@ -687,8 +687,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
@@ -723,8 +723,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
@@ -758,8 +758,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
@@ -799,8 +799,8 @@ then the macro accepts an arbitrary number of arguments.
 \&.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
@@ -826,7 +826,7 @@ then the macro accepts an arbitrary number of arguments.
 .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
@@ -954,60 +954,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:
+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
+The default is
+.Fl nosplit .
+The effect of selecting either of the
+.Fl split
+modes ends at the beginning of the
+.Em AUTHORS
+section.
 In the
 .Em 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
+section, the default is
+.Fl nosplit
+for the first author listing and
 .Fl split
-will cause the first listing also to be split.
-If not in the
-.Em AUTHORS
-section, the default is not to 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
-.Em AUTHORS
-section, so if one specifies
-.Sx \&An Fl nosplit
-in the general document body, it must be re-specified in the
-.Em 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:
@@ -1023,7 +1013,7 @@ form of a function.
 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
@@ -1043,7 +1033,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:
@@ -1052,18 +1042,18 @@ Examples:
 .D1 \&.Ar arg1 , arg2 .
 .Ss \&At
 Formats an AT&T version.
-Accepts at most one parameter:
+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
@@ -1079,83 +1069,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
@@ -1196,21 +1196,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
@@ -1223,124 +1224,128 @@ 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
-.Sx Scaling Widths
-value;
-.Fl offset ,
-also 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 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:
@@ -1368,12 +1373,12 @@ 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:
@@ -1430,7 +1435,7 @@ See also
 and
 .Sx \&Ux .
 .Ss \&Cd
-Configuration declaration.
+Kernel configuration declaration.
 This denotes strings accepted by
 .Xr config 8 .
 .Pp
@@ -1467,13 +1472,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.
@@ -1484,17 +1491,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$
@@ -1519,7 +1526,7 @@ See also
 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:
@@ -1557,22 +1564,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
@@ -1611,7 +1618,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
@@ -1640,10 +1647,10 @@ This field is optional, and if specified, must be one of
 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.
@@ -1718,10 +1725,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 .
@@ -1729,13 +1736,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
@@ -1757,15 +1764,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 .
@@ -1788,16 +1796,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 .
@@ -1833,7 +1841,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.
@@ -1984,7 +1992,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
@@ -2238,7 +2246,7 @@ See also
 and
 .Sx \&Ux .
 .Ss \&Oc
-Closes multi-line
+Close multi-line
 .Sx \&Oo
 context.
 .Ss \&Oo
@@ -2372,12 +2380,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.
@@ -2731,6 +2739,12 @@ Heirloom troff, the other significant troff implementation accepting
 .Pp
 .Bl -dash -compact
 .It
+An empty
+.Sq \&Dd
+macro in groff prints
+.Dq Epoch .
+In mandoc, it resolves to the current date.
+.It
 Old groff fails to assert a newline before
 .Sx \&Bd Fl ragged compact .
 .It