===================================================================
RCS file: /cvs/mandoc/mdoc.7,v
retrieving revision 1.141
retrieving revision 1.191
diff -u -p -r1.141 -r1.191
--- mandoc/mdoc.7	2010/07/26 12:51:56	1.141
+++ mandoc/mdoc.7	2011/07/18 10:23:02	1.191
@@ -1,6 +1,6 @@
-.\"	$Id: mdoc.7,v 1.141 2010/07/26 12:51:56 kristaps Exp $
+.\"	$Id: mdoc.7,v 1.191 2011/07/18 10:23:02 kristaps Exp $
 .\"
-.\" Copyright (c) 2009, 2010 Kristaps Dzonsons <kristaps@bsd.lv>
+.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org>
 .\"
 .\" Permission to use, copy, modify, and distribute this software for any
@@ -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 26 2010 $
+.Dd $Mdocdate: July 18 2011 $
 .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
@@ -38,37 +40,39 @@ An
 .Nm
 document follows simple rules: lines beginning with the control
 character
-.Sq \.
+.Sq \&.
 are parsed for macros.
-Other lines are interpreted within the scope of
-prior macros:
+Text lines, those not beginning with the control character, are
+interpreted within the scope of prior macros:
 .Bd -literal -offset indent
 \&.Sh Macro lines change control state.
-Other lines are interpreted within the current state.
+Text lines are interpreted within the current state.
 .Ed
 .Sh LANGUAGE SYNTAX
 .Nm
 documents may contain only graphable 7-bit ASCII characters, the space
 character, and, in certain circumstances, the tab character.
-All manuals must have
-.Ux
-line terminators.
+.Pp
+If the first character of a text line is a space, that line is printed
+with a leading newline.
 .Ss Comments
 Text following a
 .Sq \e\*q ,
-whether in a macro or free-form text line, is ignored to the end of
+whether in a macro or text line, is ignored to the end of
 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:
+.Ss Reserved Terms
+Within a macro line, the following terms are reserved:
 .Pp
 .Bl -tag -width Ds -offset indent -compact
 .It \&.
 .Pq period
+.It \e.
+.Pq escaped period
 .It \&,
 .Pq comma
 .It \&:
@@ -89,16 +93,16 @@ Within a macro line, the following characters are rese
 .Pq exclamation
 .It \&|
 .Pq vertical bar
+.It \e*(Ba
+.Pq reserved-word vertical bar
 .El
 .Pp
-Use of reserved characters is described in
-.Sx MACRO SYNTAX .
-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 can be used.
+For general use in macro lines, these can be escaped with a non-breaking
+space
+.Pq Sq \e& .
+In text lines, these may be used as normal punctuation.
 .Ss Special Characters
-Special characters may occur in both macro and free-form lines.
+Special characters may occur in both macro and text lines.
 Sequences begin with the escape character
 .Sq \e
 followed by either an open-parenthesis
@@ -107,7 +111,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,25 +124,22 @@ 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
+.Dl \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
+If a macro opens a font scope after calling
+.Sq \ef ,
+such as with
+.Sx \&Bf ,
+the
 .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.
+mode will be restored upon exiting the
+.Sx \&Bf
+scope.
 .Pp
 Note this form is
 .Em not
@@ -147,7 +148,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,9 +173,9 @@ 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 text 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
+Blank text lines, which may include whitespace, are only permitted
 within literal contexts.
 .Pp
 In macro lines, whitespace delimits arguments and is discarded.
@@ -183,7 +184,7 @@ If arguments are quoted, whitespace within the quotes 
 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
 Note that any quoted text, even if it would cause a macro invocation
@@ -194,35 +195,7 @@ Thus, the following produces
 \&.Op "Fl 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:
-.Pp
-.D1 Cm Month Day , Year
-.Pp
-The
-.Cm Day
-value is an optionally zero-padded numeral.
-The
-.Cm Month
-value is the full month name.
-The
-.Cm Year
-value is the full four-digit year.
-.Pp
-Reduced form dates are broken-down canonical form dates:
-.Pp
-.D1 Cm Month , Year
-.D1 Cm Year
-.Pp
-Some examples of valid dates follow:
-.Pp
-.D1 "May, 2009" Pq reduced form
-.D1 "2009" Pq reduced form
-.D1 "May 20, 2009" Pq canonical form
+In text lines, quotes are regarded as opaque text.
 .Ss Scaling Widths
 Many macros support scaled widths for their arguments, such as
 stipulating a two-inch list indentation with the following:
@@ -276,22 +249,25 @@ 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,
 or question mark followed by zero or more non-sentence closing
-delimiters (
-.Ns Sq \&) ,
+delimiters
+.Po
+.Sq \&) ,
 .Sq \&] ,
 .Sq \&' ,
-.Sq \&" ) .
+.Sq \&"
+.Pc .
 .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 \.
+.Dl \&.Xr mandoc 1 \&.
+.Dl \&.Fl T \&Ns \&Cm ascii \&.
 .Sh MANUAL STRUCTURE
 A well-formed
 .Nm
@@ -320,18 +296,20 @@ sections, although this varies between manual sections
 .Pp
 The following is a well-formed skeleton
 .Nm
-file:
+file for a utility
+.Qq progname :
 .Bd -literal -offset indent
 \&.Dd $\&Mdocdate$
-\&.Dt mdoc 7
+\&.Dt PROGNAME section
 \&.Os
 \&.Sh NAME
-\&.Nm foo
+\&.Nm progname
 \&.Nd a description goes here
-\&.\e\*q The next is for sections 2, 3, & 9 only.
 \&.\e\*q .Sh LIBRARY
+\&.\e\*q For sections 2, 3, & 9 only.
+\&.\e\*q Not used in OpenBSD.
 \&.Sh SYNOPSIS
-\&.Nm foo
+\&.Nm progname
 \&.Op Fl options
 \&.Ar
 \&.Sh DESCRIPTION
@@ -339,18 +317,19 @@ The
 \&.Nm
 utility processes files ...
 \&.\e\*q .Sh IMPLEMENTATION NOTES
-\&.\e\*q The next is for sections 2, 3, & 9 only.
+\&.\e\*q Not used in OpenBSD.
 \&.\e\*q .Sh RETURN VALUES
-\&.\e\*q The next is for sections 1, 6, 7, & 8 only.
+\&.\e\*q For sections 2, 3, & 9 only.
 \&.\e\*q .Sh ENVIRONMENT
+\&.\e\*q For sections 1, 6, 7, & 8 only.
 \&.\e\*q .Sh FILES
-\&.\e\*q The next is for sections 1 & 8 only.
 \&.\e\*q .Sh EXIT STATUS
+\&.\e\*q For sections 1, 6, & 8 only.
 \&.\e\*q .Sh EXAMPLES
-\&.\e\*q The next is for sections 1, 4, 6, 7, & 8 only.
 \&.\e\*q .Sh DIAGNOSTICS
-\&.\e\*q The next is for sections 2, 3, & 9 only.
+\&.\e\*q For sections 1, 4, 6, 7, & 8 only.
 \&.\e\*q .Sh ERRORS
+\&.\e\*q For sections 2, 3, & 9 only.
 \&.\e\*q .Sh SEE ALSO
 \&.\e\*q .Xr foobar 1
 \&.\e\*q .Sh STANDARDS
@@ -359,23 +338,28 @@ utility processes files ...
 \&.\e\*q .Sh CAVEATS
 \&.\e\*q .Sh BUGS
 \&.\e\*q .Sh SECURITY CONSIDERATIONS
+\&.\e\*q Not used in OpenBSD.
 .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 one-line 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 one-line description
+\&.Nd a one line description
 .Ed
 .Pp
+Multiple
+.Sq \&Nm
+names should be separated by commas.
+.Pp
 The
 .Sx \&Nm
 macro(s) must precede the
@@ -403,26 +387,36 @@ configuration.
 For the first, utilities (sections 1, 6, and 8), this is
 generally structured as follows:
 .Bd -literal -offset indent
-\&.Nm foo
+\&.Nm bar
 \&.Op Fl v
 \&.Op Fl o Ar file
 \&.Op Ar
-\&.Nm bar
+\&.Nm foo
 \&.Op Fl v
 \&.Op Fl o Ar file
 \&.Op Ar
 .Ed
 .Pp
+Commands should be ordered alphabetically.
+.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 *"
 \&.Fn bar "const char *src"
 .Ed
 .Pp
+Ordering of
+.Sx \&In ,
+.Sx \&Vt ,
+.Sx \&Fn ,
+and
+.Sx \&Fo
+macros should follow C header-file conventions.
+.Pp
 And for the third, configurations (section 4):
 .Bd -literal -offset indent
 \&.Cd \*qit* at isa? port 0x2e\*q
@@ -445,7 +439,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
@@ -471,9 +465,15 @@ 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
-.Em NAME .
-It usually contains a break-down of the options (if documenting a
+This begins with an expansion of the brief, one line description in
+.Em NAME :
+.Bd -literal -offset indent
+The
+\&.Nm
+utility does this, that, and the other.
+.Ed
+.Pp
+It usually follows with a breakdown of the options (if documenting a
 command), such as:
 .Bd -literal -offset indent
 The arguments are as follows:
@@ -489,10 +489,8 @@ 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 .
@@ -513,10 +511,8 @@ the file is used (created, modified, etc.).
 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.
@@ -526,7 +522,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.
@@ -560,11 +556,9 @@ 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.
+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
@@ -573,7 +567,7 @@ See
 Common misuses and misunderstandings should be explained
 in this section.
 .It Em BUGS
-Known bugs, limitations and work-arounds should be described
+Known bugs, limitations, and work-arounds should be described
 in this section.
 .It Em SECURITY CONSIDERATIONS
 Documents any security precautions that operators should consider.
@@ -604,20 +598,21 @@ 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
+column indicates that the macro may also be called by passing its name
+as an argument to another macro.
+If a macro is not callable but its name appears as an argument
+to another macro, it is interpreted as opaque text.
+For example,
 .Sq \&.Fl \&Sh
 produces
 .Sq Fl \&Sh .
 .Pp
 The
 .Em Parsed
-column indicates whether the macro may be followed by further
-(ostensibly callable) macros.
-If a macro is not parsed, subsequent macro invocations on the line
-will be interpreted as opaque text.
+column indicates whether the macro may call other macros by receiving
+their names as arguments.
+If a macro is not parsed but the name of another macro appears
+as an argument, it is interpreted as opaque text.
 .Pp
 The
 .Em Scope
@@ -626,7 +621,10 @@ column, if applicable, describes closure rules.
 Multi-line scope closed by an explicit closing macro.
 All macros contains bodies; only
 .Sx \&Bf
-contains a head.
+and
+.Pq optionally
+.Sx \&Bl
+contain a head.
 .Bd -literal -offset indent
 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB
 \(lBbody...\(rB
@@ -731,7 +729,7 @@ and/or tail
 .El
 .Ss Block partial-implicit
 Like block full-implicit, but with single-line scope closed by
-.Sx Reserved Characters
+.Sx Reserved Terms
 or end of line.
 .Bd -literal -offset indent
 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB
@@ -762,16 +760,31 @@ in a
 .Em SYNOPSIS
 section line, else it is
 .Sx In-line .
+.Ss Special block macro
+The
+.Sx \&Ta
+macro can only be used below
+.Sx \&It
+in
+.Sx \&Bl Fl column
+lists.
+It delimits blocks representing table cells;
+these blocks have bodies, but no heads.
+.Pp
+.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 \&Ta  Ta    Yes      Ta    Yes    Ta closed by Sx \&Ta , Sx \&It
+.El
 .Ss In-line
 Closed by
-.Sx Reserved Characters ,
+.Sx Reserved Terms ,
 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
-\&.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...
 
@@ -794,8 +807,8 @@ then the macro accepts an arbitrary number of argument
 .It Sx \&%T  Ta    \&No     Ta    \&No     Ta    >0
 .It Sx \&%U  Ta    \&No     Ta    \&No     Ta    >0
 .It Sx \&%V  Ta    \&No     Ta    \&No     Ta    >0
-.It Sx \&Ad  Ta    Yes      Ta    Yes      Ta    n
-.It Sx \&An  Ta    Yes      Ta    Yes      Ta    n
+.It Sx \&Ad  Ta    Yes      Ta    Yes      Ta    >0
+.It Sx \&An  Ta    Yes      Ta    Yes      Ta    >0
 .It Sx \&Ap  Ta    Yes      Ta    Yes      Ta    0
 .It Sx \&Ar  Ta    Yes      Ta    Yes      Ta    n
 .It Sx \&At  Ta    Yes      Ta    Yes      Ta    1
@@ -803,31 +816,31 @@ then the macro accepts an arbitrary number of argument
 .It Sx \&Bt  Ta    \&No     Ta    \&No     Ta    0
 .It Sx \&Bx  Ta    Yes      Ta    Yes      Ta    n
 .It Sx \&Cd  Ta    Yes      Ta    Yes      Ta    >0
-.It Sx \&Cm  Ta    Yes      Ta    Yes      Ta    n
+.It Sx \&Cm  Ta    Yes      Ta    Yes      Ta    >0
 .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 \&Dv  Ta    Yes      Ta    Yes      Ta    >0
 .It Sx \&Dx  Ta    Yes      Ta    Yes      Ta    n
 .It Sx \&Em  Ta    Yes      Ta    Yes      Ta    >0
 .It Sx \&En  Ta    \&No     Ta    \&No     Ta    0
 .It Sx \&Er  Ta    Yes      Ta    Yes      Ta    >0
 .It Sx \&Es  Ta    \&No     Ta    \&No     Ta    0
-.It Sx \&Ev  Ta    Yes      Ta    Yes      Ta    n
+.It Sx \&Ev  Ta    Yes      Ta    Yes      Ta    >0
 .It Sx \&Ex  Ta    \&No     Ta    \&No     Ta    n
-.It Sx \&Fa  Ta    Yes      Ta    Yes      Ta    n
+.It Sx \&Fa  Ta    Yes      Ta    Yes      Ta    >0
 .It Sx \&Fd  Ta    \&No     Ta    \&No     Ta    >0
 .It Sx \&Fl  Ta    Yes      Ta    Yes      Ta    n
 .It Sx \&Fn  Ta    Yes      Ta    Yes      Ta    >0
 .It Sx \&Fr  Ta    \&No     Ta    \&No     Ta    n
-.It Sx \&Ft  Ta    Yes      Ta    Yes      Ta    n
+.It Sx \&Ft  Ta    Yes      Ta    Yes      Ta    >0
 .It Sx \&Fx  Ta    Yes      Ta    Yes      Ta    n
 .It Sx \&Hf  Ta    \&No     Ta    \&No     Ta    n
 .It Sx \&Ic  Ta    Yes      Ta    Yes      Ta    >0
-.It Sx \&In  Ta    \&No     Ta    \&No     Ta    n
+.It Sx \&In  Ta    \&No     Ta    \&No     Ta    1
 .It Sx \&Lb  Ta    \&No     Ta    \&No     Ta    1
-.It Sx \&Li  Ta    Yes      Ta    Yes      Ta    n
-.It Sx \&Lk  Ta    Yes      Ta    Yes      Ta    n
+.It Sx \&Li  Ta    Yes      Ta    Yes      Ta    >0
+.It Sx \&Lk  Ta    Yes      Ta    Yes      Ta    >0
 .It Sx \&Lp  Ta    \&No     Ta    \&No     Ta    0
 .It Sx \&Ms  Ta    Yes      Ta    Yes      Ta    >0
 .It Sx \&Mt  Ta    Yes      Ta    Yes      Ta    >0
@@ -879,16 +892,14 @@ 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
 block.
-This should follow the reduced or canonical form syntax described in
-.Sx Dates .
+Recommended formats of arguments are
+.Ar month day , year
+or just
+.Ar year .
 .Ss \&%I
 Publisher or issuer name of an
 .Sx \&Rs
@@ -942,8 +953,8 @@ Memory address.
 Do not use this for postal addresses.
 .Pp
 Examples:
-.D1 \&.Ad [0,$]
-.D1 \&.Ad 0x00000000
+.Dl \&.Ad [0,$]
+.Dl \&.Ad 0x00000000
 .Ss \&An
 Author name.
 Requires either the name of an author or one of the following arguments:
@@ -973,14 +984,14 @@ for the first author listing and
 for all other author listings.
 .Pp
 Examples:
-.D1 \&.An -nosplit
-.D1 \&.An Kristaps Dzonsons \&Aq kristaps@bsd.lv
+.Dl \&.An -nosplit
+.Dl \&.An Kristaps Dzonsons \&Aq kristaps@bsd.lv
 .Ss \&Ao
 Begin a block enclosed by angle brackets.
 Does not have any head arguments.
 .Pp
 Examples:
-.D1 \&.Fl -key= \&Ns \&Ao \&Ar val \&Ac
+.Dl \&.Fl -key= \&Ns \&Ao \&Ar val \&Ac
 .Pp
 See also
 .Sx \&Aq .
@@ -990,12 +1001,12 @@ This is generally used as a grammatical device when re
 form of a function.
 .Pp
 Examples:
-.D1 \&.Fn execve \&Ap d
+.Dl \&.Fn execve \&Ap d
 .Ss \&Aq
 Encloses its arguments in angle brackets.
 .Pp
 Examples:
-.D1 \&.Fl -key= \&Ns \&Aq \&Ar val
+.Dl \&.Fl -key= \&Ns \&Aq \&Ar val
 .Pp
 .Em Remarks :
 this macro is often abused for rendering URIs, which should instead use
@@ -1016,9 +1027,9 @@ If an argument is not provided, the string
 is used as a default.
 .Pp
 Examples:
-.D1 \&.Fl o \&Ns \&Ar file1
-.D1 \&.Ar
-.D1 \&.Ar arg1 , arg2 .
+.Dl \&.Fl o \&Ns \&Ar file1
+.Dl \&.Ar
+.Dl \&.Ar arg1 , arg2 .
 .Ss \&At
 Formats an AT&T version.
 Accepts one optional argument:
@@ -1035,8 +1046,8 @@ A version of
 Note that these arguments do not begin with a hyphen.
 .Pp
 Examples:
-.D1 \&.At
-.D1 \&.At V.1
+.Dl \&.At
+.Dl \&.At V.1
 .Pp
 See also
 .Sx \&Bsx ,
@@ -1064,7 +1075,7 @@ Its syntax is as follows:
 .Pp
 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.
+They may contain both macro lines and text lines.
 By default, a display block is preceded by a vertical space.
 .Pp
 The
@@ -1161,7 +1172,7 @@ and
 argument are equivalent, as are
 .Fl symbolic
 and
-.Cm \&Sy,
+.Cm \&Sy ,
 and
 .Fl literal
 and
@@ -1179,9 +1190,10 @@ See also
 and
 .Sx \&Sy .
 .Ss \&Bk
-Keep the output generated from each macro input line together
-on one single output line.
-Line breaks in free-form text lines are unaffected.
+For each macro, keep its output together on the same output line,
+until the end of the macro or the end of the input line is reached,
+whichever comes first.
+Line breaks in text lines are unaffected.
 The syntax is as follows:
 .Pp
 .D1 Pf \. Sx \&Bk Fl words
@@ -1204,7 +1216,7 @@ Be careful in using over-long lines within a keep bloc
 Doing so will clobber the right margin.
 .Ss \&Bl
 Begin a list.
-Lists consist of items started by the
+Lists consist of items specified using the
 .Sx \&It
 macro, containing a head or a body or both.
 The list syntax is as follows:
@@ -1339,7 +1351,7 @@ See also
 Encloses its arguments in square brackets.
 .Pp
 Examples:
-.D1 \&.Bq 1 , \&Dv BUFSIZ
+.Dl \&.Bq 1 , \&Dv BUFSIZ
 .Pp
 .Em Remarks :
 this macro is sometimes abused to emulate optional arguments for
@@ -1372,7 +1384,7 @@ See also
 Encloses its arguments in curly braces.
 .Pp
 Examples:
-.D1 \&.Brq 1 , ... , \&Va n
+.Dl \&.Brq 1 , ... , \&Va n
 .Pp
 See also
 .Sx \&Bro .
@@ -1381,8 +1393,8 @@ Format the BSD/OS version provided as an argument, or 
 no argument is provided.
 .Pp
 Examples:
-.D1 \&.Bsx 1.0
-.D1 \&.Bsx
+.Dl \&.Bsx 1.0
+.Dl \&.Bsx
 .Pp
 See also
 .Sx \&At ,
@@ -1395,14 +1407,14 @@ 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.
 .Pp
 Examples:
-.D1 \&.Bx 4.4
-.D1 \&.Bx
+.Dl \&.Bx 4.4
+.Dl \&.Bx
 .Pp
 See also
 .Sx \&At ,
@@ -1419,7 +1431,7 @@ This denotes strings accepted by
 .Xr config 8 .
 .Pp
 Examples:
-.D1 \&.Cd device le0 at scode?
+.Dl \&.Cd device le0 at scode?
 .Pp
 .Em Remarks :
 this macro is commonly abused by using quoted literals to retain
@@ -1432,8 +1444,8 @@ Command modifiers.
 Useful when specifying configuration options or keys.
 .Pp
 Examples:
-.D1 \&.Cm ControlPath
-.D1 \&.Cm ControlMaster
+.Dl \&.Cm ControlPath
+.Dl \&.Cm ControlMaster
 .Pp
 See also
 .Sx \&Fl .
@@ -1444,7 +1456,7 @@ statements.
 It is followed by a newline.
 .Pp
 Examples:
-.D1 \&.D1 \&Fl abcdefgh
+.Dl \&.D1 \&Fl abcdefgh
 .Pp
 See also
 .Sx \&Bd
@@ -1470,22 +1482,41 @@ This is the mandatory first macro of any
 manual.
 Its syntax is as follows:
 .Pp
-.D1 Pf \. Sx \&Dd Ar date
+.D1 Pf \. Sx \&Dd Ar month day , year
 .Pp
 The
-.Ar date
-may be either
-.Ar $\&Mdocdate$ ,
-which signifies the current manual revision date dictated by
+.Ar month
+is the full English month name, the
+.Ar day
+is an optionally zero-padded numeral, and the
+.Ar year
+is the full four-digit year.
+.Pp
+Other arguments are not portable; the
+.Xr mandoc 1
+utility handles them as follows:
+.Bl -dash -offset 3n -compact
+.It
+To have the date automatically filled in by the
+.Ox
+version of
 .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.
+the special string
+.Dq $\&Mdocdate$
+can be given as an argument.
+.It
+A few alternative date formats are accepted as well
+and converted to the standard form.
+.It
+If a date string cannot be parsed, it is used verbatim.
+.It
+If no date string is given, the current date is used.
+.El
 .Pp
 Examples:
-.D1 \&.Dd $\&Mdocdate$
-.D1 \&.Dd $\&Mdocdate: July 21 2007$
-.D1 \&.Dd July 21, 2007
+.Dl \&.Dd $\&Mdocdate$
+.Dl \&.Dd $\&Mdocdate: July 21 2007$
+.Dl \&.Dd July 21, 2007
 .Pp
 See also
 .Sx \&Dt
@@ -1498,7 +1529,7 @@ invocations.
 It is followed by a newline.
 .Pp
 Examples:
-.D1 \&.Dl % mandoc mdoc.7 \e(ba less
+.Dl \&.Dl % mandoc mdoc.7 \e(ba less
 .Pp
 See also
 .Sx \&Bd
@@ -1650,6 +1681,7 @@ It must be one of
 .Ar luna88k ,
 .Ar mac68k ,
 .Ar macppc ,
+.Ar mips64 ,
 .Ar mvme68k ,
 .Ar mvme88k ,
 .Ar mvmeppc ,
@@ -1665,30 +1697,37 @@ or
 .El
 .Pp
 Examples:
-.D1 \&.Dt FOO 1
-.D1 \&.Dt FOO 4 KM
-.D1 \&.Dt FOO 9 i386
+.Dl \&.Dt FOO 1
+.Dl \&.Dt FOO 4 KM
+.Dl \&.Dt FOO 9 i386
 .Pp
 See also
 .Sx \&Dd
 and
 .Sx \&Os .
 .Ss \&Dv
-Defined variables such as preprocessor constants.
+Defined variables such as preprocessor constants, constant symbols,
+enumeration values, and so on.
 .Pp
 Examples:
-.D1 \&.Dv BUFSIZ
-.D1 \&.Dv STDOUT_FILENO
+.Dl \&.Dv NULL
+.Dl \&.Dv BUFSIZ
+.Dl \&.Dv STDOUT_FILENO
 .Pp
 See also
-.Sx \&Er .
+.Sx \&Er
+and
+.Sx \&Ev
+for special-purpose constants and
+.Sx \&Va
+for variable symbols.
 .Ss \&Dx
 Format the DragonFly BSD version provided as an argument, or a default
 value if no argument is provided.
 .Pp
 Examples:
-.D1 \&.Dx 2.4.1
-.D1 \&.Dx
+.Dl \&.Dx 2.4.1
+.Dl \&.Dx
 .Pp
 See also
 .Sx \&At ,
@@ -1734,8 +1773,8 @@ Note that this is a presentation term and should not b
 stylistically decorating technical terms.
 .Pp
 Examples:
-.D1 \&.Em Warnings!
-.D1 \&.Em Remarks :
+.Dl \&.Em Warnings!
+.Dl \&.Em Remarks :
 .Pp
 See also
 .Sx \&Bf ,
@@ -1757,14 +1796,17 @@ argument is used as the enclosure head, for example, s
 will emulate
 .Sx \&Do .
 .Ss \&Er
-Display error constants.
+Error constants for definitions of the
+.Va errno
+libc global variable.
 .Pp
 Examples:
-.D1 \&.Er EPERM
-.D1 \&.Er ENOENT
+.Dl \&.Er EPERM
+.Dl \&.Er ENOENT
 .Pp
 See also
-.Sx \&Dv .
+.Sx \&Dv
+for general constants.
 .Ss \&Es
 This macro is obsolete and not implemented.
 .Ss \&Ev
@@ -1772,19 +1814,27 @@ Environmental variables such as those specified in
 .Xr environ 7 .
 .Pp
 Examples:
-.D1 \&.Ev DISPLAY
-.D1 \&.Ev PATH
+.Dl \&.Ev DISPLAY
+.Dl \&.Ev PATH
+.Pp
+See also
+.Sx \&Dv
+for general constants.
 .Ss \&Ex
-Insert a standard sentence regarding exit values.
+Insert a standard sentence regarding command exit values of 0 on success
+and >0 on failure.
 Its syntax is as follows:
 .Pp
-.D1 Pf \. Sx \&Ex Fl std Op Ar utility
+.D1 Pf \. Sx \&Ex Fl std Op Ar utility...
 .Pp
-When
+If
 .Ar utility
 is not specified, the document's name set by
 .Sx \&Nm
 is used.
+Multiple
+.Ar utility
+arguments are treated as separate utilities.
 .Pp
 See also
 .Sx \&Rv .
@@ -1813,9 +1863,9 @@ Furthermore, if the following macro is another
 the last argument will also have a trailing comma.
 .Pp
 Examples:
-.D1 \&.Fa \(dqconst char *p\(dq
-.D1 \&.Fa \(dqint a\(dq \(dqint b\(dq \(dqint c\(dq
-.D1 \&.Fa foo
+.Dl \&.Fa \(dqconst char *p\(dq
+.Dl \&.Fa \(dqint a\(dq \(dqint b\(dq \(dqint c\(dq
+.Dl \&.Fa foo
 .Pp
 See also
 .Sx \&Fo .
@@ -1843,10 +1893,10 @@ If the argument is a macro, a hyphen is prefixed to th
 output.
 .Pp
 Examples:
-.D1 \&.Fl a b c
-.D1 \&.Fl \&Pf a b
-.D1 \&.Fl
-.D1 \&.Op \&Fl o \&Ns \&Ar file
+.Dl \&.Fl a b c
+.Dl \&.Fl \&Pf a b
+.Dl \&.Fl
+.Dl \&.Op \&Fl o \&Ns \&Ar file
 .Pp
 See also
 .Sx \&Cm .
@@ -1855,9 +1905,9 @@ A function name.
 Its syntax is as follows:
 .Bd -ragged -offset indent
 .Pf \. Ns Sx \&Fn
-.Op Cm functype
-.Cm funcname
-.Op Oo Cm argtype Oc Cm argname
+.Op Ar functype
+.Ar funcname
+.Op Oo Ar argtype Oc Ar argname
 .Ed
 .Pp
 Function arguments are surrounded in parenthesis and
@@ -1865,14 +1915,17 @@ are delimited by commas.
 If no arguments are specified, blank parenthesis are output.
 .Pp
 Examples:
-.D1 \&.Fn "int funcname" "int arg0" "int arg1"
-.D1 \&.Fn funcname "int arg0"
-.D1 \&.Fn funcname arg0
+.Dl \&.Fn \*qint funcname\*q \*qint arg0\*q \*qint arg1\*q
+.Dl \&.Fn funcname \*qint arg0\*q
+.Dl \&.Fn funcname arg0
 .Bd -literal -offset indent -compact
 \&.Ft functype
 \&.Fn funcname
 .Ed
 .Pp
+When referring to a function documented in another manual page, use
+.Sx \&Xr
+instead.
 See also
 .Sx MANUAL STRUCTURE
 and
@@ -1883,17 +1936,17 @@ This is a multi-line version of
 .Sx \&Fn .
 Its syntax is as follows:
 .Pp
-.D1 Pf \. Sx \&Fo Cm funcname
+.D1 Pf \. Sx \&Fo Ar funcname
 .Pp
 Invocations usually occur in the following context:
 .Bd -ragged -offset indent
-.Pf \. Sx \&Ft Cm functype
+.Pf \. Sx \&Ft Ar functype
 .br
-.Pf \. Sx \&Fo Cm funcname
+.Pf \. Sx \&Fo Ar funcname
 .br
-.Pf \. Sx \&Fa Oo Cm argtype Oc Cm argname
+.Pf \. Sx \&Fa Oo Ar argtype Oc Ar argname
 .br
-\.\.\.
+\&.\.\.
 .br
 .Pf \. Sx \&Fc
 .Ed
@@ -1908,14 +1961,16 @@ See also
 .Sx \&Fc ,
 and
 .Sx \&Ft .
+.Ss \&Fr
+This macro is obsolete and not implemented.
 .Ss \&Ft
 A function type.
 Its syntax is as follows:
 .Pp
-.D1 Pf \. Sx \&Ft Cm functype
+.D1 Pf \. Sx \&Ft Ar functype
 .Pp
 Examples:
-.D1 \&.Ft int
+.Dl \&.Ft int
 .Bd -literal -offset indent -compact
 \&.Ft functype
 \&.Fn funcname
@@ -1927,12 +1982,14 @@ 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:
-.D1 \&.Fx 7.1
-.D1 \&.Fx
+.Dl \&.Fx 7.1
+.Dl \&.Fx
 .Pp
 See also
 .Sx \&At ,
@@ -1952,11 +2009,11 @@ This is similar to
 but used for instructions rather than values.
 .Pp
 Examples:
-.D1 \&.Ic hash
-.D1 \&.Ic alias
+.Dl \&.Ic hash
+.Dl \&.Ic alias
 .Pp
 Note that using
-.Sx \&Bd No Fl literal
+.Sx \&Bd Fl literal
 or
 .Sx \&D1
 is preferred for displaying code; the
@@ -1974,7 +2031,7 @@ preceded by
 the arguments is enclosed in angle brackets.
 .Pp
 Examples:
-.D1 \&.In sys/types
+.Dl \&.In sys/types
 .Pp
 See also
 .Sx MANUAL STRUCTURE .
@@ -1991,7 +2048,7 @@ and
 .Fl diag
 have the following syntax:
 .Pp
-.D1 Pf \. Sx \&It Cm args
+.D1 Pf \. Sx \&It Ar args
 .Pp
 Lists of type
 .Fl bullet ,
@@ -2028,33 +2085,29 @@ The
 list is the most complicated.
 Its syntax is as follows:
 .Pp
-.D1 Pf \. Sx \&It Op Cm args
+.D1 Pf \. Sx \&It Ar cell Op <TAB> Ar cell ...
+.D1 Pf \. Sx \&It Ar cell Op Sx \&Ta Ar cell ...
 .Pp
-The
-.Cm args
-are phrases, a mix of macros and text corresponding to a line column,
-delimited by tabs or the special
-.Sq \&Ta
-pseudo-macro.
-Lines subsequent the
+The arguments consist of one or more lines of text and macros
+representing a complete table line.
+Cells within the line are delimited by tabs or by the special
+.Sx \&Ta
+block macro.
+The tab cell delimiter may only be used within the
 .Sx \&It
-are interpreted within the scope of the last phrase.
-Calling the pseudo-macro
-.Sq \&Ta
-will open a new phrase scope (this must occur on a macro line to be
-interpreted as a macro).
-Note that the tab phrase delimiter may only be used within the
+line itself; on following lines, only the
+.Sx \&Ta
+macro can be used to delimit cells, and
+.Sx \&Ta
+is only recognized as a macro when called by other macros,
+not as the first macro on a line.
+.Pp
+Note that quoted strings may span tab-delimited cells on an
 .Sx \&It
-line itself.
-Subsequent this, only the
-.Sq \&Ta
-pseudo-macro may be used to delimit phrases.
-Furthermore, note that quoted sections propagate over tab-delimited
-phrases on an
-.Sx \&It ,
-for example,
+line.
+For example,
 .Pp
-.D1 .It \(dqcol1 ; <TAB> col2 ;\(dq \&;
+.Dl .It \(dqcol1 ; <TAB> col2 ;\(dq \&;
 .Pp
 will preserve the semicolon whitespace except for the last.
 .Pp
@@ -2064,14 +2117,14 @@ See also
 Specify a library.
 The syntax is as follows:
 .Pp
-.D1 Pf \. Sx \&Lb Cm library
+.D1 Pf \. Sx \&Lb Ar library
 .Pp
 The
-.Cm library
+.Ar library
 parameter may be a system library, such as
-.Cm libz
+.Ar libz
 or
-.Cm libpam ,
+.Ar 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.
@@ -2081,8 +2134,8 @@ section as described in
 .Sx MANUAL STRUCTURE .
 .Pp
 Examples:
-.D1 \&.Lb libz
-.D1 \&.Lb mdoc
+.Dl \&.Lb libz
+.Dl \&.Lb mdoc
 .Ss \&Li
 Denotes text that should be in a literal font mode.
 Note that this is a presentation term and should not be used for
@@ -2097,11 +2150,11 @@ and
 Format a hyperlink.
 Its syntax is as follows:
 .Pp
-.D1 Pf \. Sx \&Lk Cm uri Op Cm name
+.D1 Pf \. Sx \&Lk Ar uri Op Ar name
 .Pp
 Examples:
-.D1 \&.Lk http://bsd.lv "The BSD.lv Project"
-.D1 \&.Lk http://bsd.lv
+.Dl \&.Lk http://bsd.lv \*qThe BSD.lv Project\*q
+.Dl \&.Lk http://bsd.lv
 .Pp
 See also
 .Sx \&Mt .
@@ -2112,23 +2165,23 @@ Synonym for
 Display a mathematical symbol.
 Its syntax is as follows:
 .Pp
-.D1 Pf \. Sx \&Ms Cm symbol
+.D1 Pf \. Sx \&Ms Ar symbol
 .Pp
 Examples:
-.D1 \&.Ms sigma
-.D1 \&.Ms aleph
+.Dl \&.Ms sigma
+.Dl \&.Ms aleph
 .Ss \&Mt
 Format a
 .Dq mailto:
 hyperlink.
 Its syntax is as follows:
 .Pp
-.D1 Pf \. Sx \&Mt Cm address
+.D1 Pf \. Sx \&Mt Ar address
 .Pp
 Examples:
-.D1 \&.Mt discuss@manpages.bsd.lv
+.Dl \&.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
@@ -2136,8 +2189,8 @@ section subsequent the
 macro.
 .Pp
 Examples:
-.D1 \&.Sx \&Nd mdoc language reference
-.D1 \&.Sx \&Nd format and display UNIX manuals
+.Dl \&.Sx \&Nd mdoc language reference
+.Dl \&.Sx \&Nd format and display UNIX manuals
 .Pp
 The
 .Sx \&Nd
@@ -2194,26 +2247,30 @@ A
 macro used to terminate prior macro contexts.
 .Pp
 Examples:
-.D1 \&.Sx \&Fl ab \&No cd \&Fl ef
+.Dl \&.Sx \&Fl ab \&No cd \&Fl ef
 .Ss \&Ns
 Suppress a space.
 Following invocation, text is interpreted as free-form text until a
 macro is encountered.
 .Pp
+This has no effect when invoked at the start of a macro line.
+.Pp
 Examples:
-.D1 \&.Fl o \&Ns \&Ar output
+.Dl \&.Fl o \&Ns \&Ar output
 .Pp
 See also
 .Sx \&No
 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:
-.D1 \&.Nx 5.01
-.D1 \&.Nx
+.Dl \&.Nx 5.01
+.Dl \&.Nx
 .Pp
 See also
 .Sx \&At ,
@@ -2244,8 +2301,8 @@ Used when listing options to command-line utilities.
 Prints the argument(s) in brackets.
 .Pp
 Examples:
-.D1 \&.Op \&Fl a \&Ar b
-.D1 \&.Op \&Ar a | b
+.Dl \&.Op \&Fl a \&Ar b
+.Dl \&.Op \&Ar a | b
 .Pp
 See also
 .Sx \&Oo .
@@ -2257,18 +2314,18 @@ any
 file.
 Its syntax is as follows:
 .Pp
-.D1 Pf \. Sx \&Os Op Cm system
+.D1 Pf \. Sx \&Os Op Ar system Op Ar version
 .Pp
 The optional
-.Cm system
+.Ar system
 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:
-.D1 \&.Os
-.D1 \&.Os KTH/CSC/TCS
-.D1 \&.Os BSD 4.3
+.Dl \&.Os
+.Dl \&.Os KTH/CSC/TCS
+.Dl \&.Os BSD 4.3
 .Pp
 See also
 .Sx \&Dd
@@ -2280,12 +2337,14 @@ 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:
-.D1 \&.Ox 4.5
-.D1 \&.Ox
+.Dl \&.Ox 4.5
+.Dl \&.Ox
 .Pp
 See also
 .Sx \&At ,
@@ -2298,10 +2357,13 @@ and
 .Sx \&Ux .
 .Ss \&Pa
 A file-system path.
+If an argument is not provided, the string
+.Dq \(ti
+is used as a default.
 .Pp
 Examples:
-.D1 \&.Pa /usr/bin/mandoc
-.D1 \&.Pa /usr/share/man/man7/mdoc.7
+.Dl \&.Pa /usr/bin/mandoc
+.Dl \&.Pa /usr/share/man/man7/mdoc.7
 .Pp
 See also
 .Sx \&Lk .
@@ -2314,14 +2376,14 @@ Removes the space
 between its arguments.
 Its syntax is as follows:
 .Pp
-.D1 Pf \. \&Pf Cm prefix suffix
+.D1 Pf \. \&Pf Ar prefix suffix
 .Pp
 The
-.Cm suffix
+.Ar suffix
 argument may be a macro.
 .Pp
 Examples:
-.D1 \&.Pf \e. \&Sx \&Pf \&Cm prefix suffix
+.Dl \&.Pf \e. \&Sx \&Pf \&Ar prefix suffix
 .Ss \&Po
 Multi-line version of
 .Sx \&Pq .
@@ -2404,16 +2466,22 @@ block is used within a SEE ALSO section, a vertical sp
 before the rendered output, else the block continues on the current
 line.
 .Ss \&Rv
-Inserts text regarding a function call's return value.
-This macro must consist of the
-.Fl std
-argument followed by an optional
-.Ar function .
+Insert a standard sentence regarding a system call's return value of 0
+on success and \-1 on error, with the
+.Va errno
+libc global variable set on error.
+Its syntax is as follows:
+.Pp
+.D1 Pf \. Sx \&Rv Fl std Op Ar function...
+.Pp
 If
 .Ar function
-is not provided, the document's name as stipulated by the first
+is not specified, the document's name set by
 .Sx \&Nm
-is provided.
+is used.
+Multiple
+.Ar function
+arguments are treated as separate functions.
 .Pp
 See also
 .Sx \&Ex .
@@ -2442,11 +2510,11 @@ Its syntax is as follows:
 .D1 Pf \. Sx \&Sm Cm on | off
 .Pp
 By default, spacing is
-.Cm on .
+.Ar on .
 When switched
-.Cm off ,
+.Ar off ,
 no white space is inserted between macro arguments and between the
-output generated from adjacent macros, but free-form text lines
+output generated from adjacent macros, but text lines
 still get normal spacing between words and sentences.
 .Ss \&So
 Multi-line version of
@@ -2581,7 +2649,12 @@ The referenced section or sub-section name must be ide
 enclosed argument, including whitespace.
 .Pp
 Examples:
-.D1 \&.Sx MANUAL STRUCTURE
+.Dl \&.Sx MANUAL STRUCTURE
+.Pp
+See also
+.Sx \&Sh
+and
+.Sx \&Ss .
 .Ss \&Sy
 Format enclosed arguments in symbolic
 .Pq Dq boldface .
@@ -2593,20 +2666,25 @@ See also
 .Sx \&Li ,
 and
 .Sx \&Em .
+.Ss \&Ta
+Table cell separator in
+.Sx \&Bl Fl column
+lists; can only be used below
+.Sx \&It .
 .Ss \&Tn
 Format a tradename.
 .Pp
 Examples:
-.D1 \&.Tn IBM
+.Dl \&.Tn IBM
 .Ss \&Ud
 Prints out
-.Dq currently under development.
+.Dq currently under development .
 .Ss \&Ux
 Format the UNIX name.
 Accepts no argument.
 .Pp
 Examples:
-.D1 \&.Ux
+.Dl \&.Ux
 .Pp
 See also
 .Sx \&At ,
@@ -2621,8 +2699,8 @@ and
 A variable name.
 .Pp
 Examples:
-.D1 \&.Va foo
-.D1 \&.Va const char *bar ;
+.Dl \&.Va foo
+.Dl \&.Va const char *bar ;
 .Ss \&Vt
 A variable type.
 This is also used for indicating global variables in the
@@ -2641,8 +2719,8 @@ Note that this should not be confused with
 which is used for function return types.
 .Pp
 Examples:
-.D1 \&.Vt unsigned char
-.D1 \&.Vt extern const char * const sys_signame[] \&;
+.Dl \&.Vt unsigned char
+.Dl \&.Vt extern const char * const sys_signame[] \&;
 .Pp
 See also
 .Sx MANUAL STRUCTURE
@@ -2652,33 +2730,37 @@ and
 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.
+Extend the header of an
+.Sx \&It
+macro or the body of a partial-implicit block macro
+beyond the end of the input line.
+This macro originally existed to work around the 9-argument limit
+of historic
+.Xr roff 7 .
 .Ss \&Xr
 Link to another manual
 .Pq Qq cross-reference .
 Its syntax is as follows:
 .Pp
-.D1 Pf \. Sx \&Xr Cm name section
+.D1 Pf \. Sx \&Xr Ar name section
 .Pp
 The
-.Cm name
+.Ar name
 and
-.Cm section
+.Ar section
 are the name and section of the linked manual.
 If
-.Cm section
+.Ar section
 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
+.Dl \&.Xr mandoc 1
+.Dl \&.Xr mandoc 1 \&;
+.Dl \&.Xr mandoc 1 \&Ns s behaviour
 .Ss \&br
 Emits a line-break.
 This macro should not be used; it is implemented for compatibility with
@@ -2693,10 +2775,10 @@ This macro should not be used; it is implemented for c
 historical manuals.
 Its syntax is as follows:
 .Pp
-.D1 Pf \. Sx \&sp Op Cm height
+.D1 Pf \. Sx \&sp Op Ar height
 .Pp
 The
-.Cm height
+.Ar height
 argument must be formatted as described in
 .Sx Scaling Widths .
 If unspecified,
@@ -2708,153 +2790,201 @@ troff implementations, at this time limited to GNU tro
 .Pq Qq groff .
 The term
 .Qq historic groff
-refers to groff versions before the
+refers to groff versions before 1.17,
+which featured a significant update of the
 .Pa doc.tmac
-file re-write
-.Pq somewhere between 1.15 and 1.19 .
+file.
 .Pp
 Heirloom troff, the other significant troff implementation accepting
 \-mdoc, is similar to historic groff.
 .Pp
+The following problematic behaviour is found in groff:
+.ds hist (Historic groff only.)
+.Pp
 .Bl -dash -compact
 .It
-The \es (font size), \em (font colour), and \eM (font filling colour)
-font decoration escapes are all discarded in mandoc.
+Display macros
+.Po
+.Sx \&Bd ,
+.Sx \&Dl ,
+and
+.Sx \&D1
+.Pc
+may not be nested.
+\*[hist]
 .It
-Old groff fails to assert a newline before
-.Sx \&Bd Fl ragged compact .
+.Sx \&At
+with unknown arguments produces no output at all.
+\*[hist]
+Newer groff and mandoc print
+.Qq AT&T UNIX
+and the arguments.
 .It
-groff behaves inconsistently when encountering
-.Pf non- Sx \&Fa
-children of
+.Sx \&Bl Fl column
+does not recognize trailing punctuation characters when they immediately
+precede tabulator characters, but treats them as normal text and
+outputs a space before them.
+.It
+.Sx \&Bd Fl ragged compact
+does not start a new line.
+\*[hist]
+.It
+.Sx \&Dd
+with non-standard arguments behaves very strangely.
+When there are three arguments, they are printed verbatim.
+Any other number of arguments is replaced by the current date,
+but without any arguments the string
+.Dq Epoch
+is printed.
+.It
+.Sx \&Fl
+does not print a dash for an empty argument.
+\*[hist]
+.It
+.Sx \&Fn
+does not start a new line unless invoked as the line macro in the
+.Em SYNOPSIS
+section.
+\*[hist]
+.It
 .Sx \&Fo
-regarding spacing between arguments.
-In mandoc, this is not the case: each argument is consistently followed
-by a single space and the trailing
-.Sq \&)
-suppresses prior spacing.
+with
+.Pf non- Sx \&Fa
+children causes inconsistent spacing between arguments.
+In mandoc, a single space is always inserted between arguments.
 .It
-groff behaves inconsistently when encountering
 .Sx \&Ft
-and
-.Sx \&Fn
 in the
-.Em SYNOPSIS :
-at times newline(s) are suppressed depending on whether a prior
+.Em SYNOPSIS
+causes inconsistent vertical spacing, depending on whether a prior
 .Sx \&Fn
 has been invoked.
-In mandoc, this is not the case.
 See
 .Sx \&Ft
 and
 .Sx \&Fn
-for the normalised behaviour.
+for the normalised behaviour in mandoc.
 .It
-Historic groff does not break before an
-.Sx \&Fn
-when not invoked as the line macro in the
-.Em SYNOPSIS
-section.
-.It
-Historic groff formats the
 .Sx \&In
-badly: trailing arguments are trashed and
-.Em SYNOPSIS
-is not specially treated.
+ignores additional arguments and is not treated specially in the
+.Em SYNOPSIS .
+\*[hist]
 .It
-groff does not accept the
-.Sq \&Ta
-pseudo-macro as a line macro.
-mandoc does.
+.Sx \&It
+sometimes requires a
+.Fl nested
+flag.
+\*[hist]
+In new groff and mandoc, any list may be nested by default and
+.Fl enum
+lists will restart the sequence only for the sub-list.
 .It
-The comment syntax
-.Sq \e\."
-is no longer accepted.
+.Sx \&Li
+followed by a reserved character is incorrectly used in some manuals
+instead of properly quoting that character, which sometimes works with
+historic groff.
 .It
-In groff, the
+.Sx \&Lk
+only accepts a single link-name argument; the remainder is misformatted.
+.It
 .Sx \&Pa
-macro does not format its arguments when used in the FILES section under
+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.
+.Sx \&Ta
+can only be called by other macros, but not at the beginning of a line.
 .It
-groff behaves irregularly when specifying
+.Sx \&%C
+is not implemented.
+.It
+Historic groff only allows up to eight or nine arguments per macro input
+line, depending on the exact situation.
+Providing more arguments causes garbled output.
+The number of arguments on one input line is not limited with mandoc.
+.It
+Historic groff has many un-callable macros.
+Most of these (excluding some block-level macros) are callable
+in new groff and mandoc.
+.It
+.Sq \(ba
+(vertical bar) is not fully supported as a delimiter.
+\*[hist]
+.It
 .Sq \ef
+.Pq font face
+and
+.Sq \ef
+.Pq font family face
 .Sx Text Decoration
-within line-macro scopes.
-mandoc follows a consistent system.
+escapes behave irregularly when specified within line-macro scopes.
 .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.
+Negative scaling units return to prior lines.
+Instead, mandoc truncates them to zero.
+.El
+.Pp
+The following features are unimplemented in mandoc:
+.Pp
+.Bl -dash -compact
 .It
-In quoted literals, groff allowed pair-wise double-quotes to produce a
-standalone double-quote in formatted output.
-This idiosyncratic behaviour is not applicable in mandoc.
+.Sx \&Bd
+.Fl file Ar file .
 .It
-Display offsets
 .Sx \&Bd
 .Fl offset Ar center
 and
-.Fl offset Ar right
-are disregarded in mandoc.
-Furthermore, troff specifies a
-.Fl file Ar file
-argument that is not supported in mandoc.
-Lastly, since text is not right-justified in mandoc (or even groff),
-.Fl ragged
-and
-.Fl filled
-are aliases, as are
-.Fl literal
-and
-.Fl unfilled .
+.Fl offset Ar right .
+Groff does not implement centered and flush-right rendering either,
+but produces large indentations.
 .It
-Historic groff has many un-callable macros.
-Most of these (excluding some block-level macros) are now callable.
-.It
-The vertical bar
-.Sq \(ba
-made historic groff
-.Qq go orbital
-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
-nested and
-.Fl enum
-lists will restart the sequence only for the sub-list.
-.It
-Some manuals use
-.Sx \&Li
-incorrectly by following it with a reserved character and expecting the
-delimiter to render.
-This is not supported in mandoc.
-.It
-In groff, the
-.Sx \&Cd ,
-.Sx \&Er ,
-.Sx \&Ex ,
+The
+.Sq \eh
+.Pq horizontal position ,
+.Sq \ev
+.Pq vertical position ,
+.Sq \em
+.Pq text colour ,
+.Sq \eM
+.Pq text filling colour ,
+.Sq \ez
+.Pq zero-length character ,
+.Sq \ew
+.Pq string length ,
+.Sq \ek
+.Pq horizontal position marker ,
+.Sq \eo
+.Pq text overstrike ,
 and
-.Sx \&Rv
-macros were stipulated only to occur in certain manual sections.
-mandoc does not have these restrictions.
+.Sq \es
+.Pq text size
+escape sequences are all discarded in mandoc.
 .It
-Newer groff and mandoc print
-.Qq AT&T UNIX
-prior to unknown arguments of
-.Sx \&At ;
-older groff did nothing.
+The
+.Sq \ef
+scaling unit is accepted by mandoc, but rendered as the default unit.
+.It
+In quoted literals, groff allows pairwise double-quotes to produce a
+standalone double-quote in formatted output.
+This is not supported by mandoc.
 .El
 .Sh SEE ALSO
+.Xr man 1 ,
 .Xr mandoc 1 ,
+.Xr eqn 7 ,
+.Xr man 7 ,
 .Xr mandoc_char 7
+.Xr roff 7 ,
+.Xr tbl 7
+.Sh HISTORY
+The
+.Nm
+language first appeared as a troff macro package in
+.Bx 4.4 .
+It was later significantly updated by Werner Lemberg and Ruslan Ermilov
+in groff-1.17.
+The standalone implementation that is part of the
+.Xr mandoc 1
+utility written by Kristaps Dzonsons appeared in
+.Ox 4.6 .
 .Sh AUTHORS
 The
 .Nm