summaryrefslogtreecommitdiff
path: root/usr.bin
diff options
context:
space:
mode:
authorIngo Schwarze <schwarze@cvs.openbsd.org>2010-07-31 22:07:12 +0000
committerIngo Schwarze <schwarze@cvs.openbsd.org>2010-07-31 22:07:12 +0000
commit0ab62f4832a08e6e55e6f1b4aa2a1f22c6a6bcca (patch)
tree0213ca818305b4109037da6be15d4572638c2321 /usr.bin
parent4a692b383d095b1f539b196c0e129750c055ff3f (diff)
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@.
Diffstat (limited to 'usr.bin')
-rw-r--r--usr.bin/mandoc/mdoc.7466
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