===================================================================
RCS file: /cvs/mandoc/mdoc.7,v
retrieving revision 1.197
retrieving revision 1.209
diff -u -p -r1.197 -r1.209
--- mandoc/mdoc.7	2011/08/10 14:07:23	1.197
+++ mandoc/mdoc.7	2011/09/16 20:44:57	1.209
@@ -1,4 +1,4 @@
-.\"	$Id: mdoc.7,v 1.197 2011/08/10 14:07:23 kristaps Exp $
+.\"	$Id: mdoc.7,v 1.209 2011/09/16 20:44:57 schwarze Exp $
 .\"
 .\" Copyright (c) 2009, 2010, 2011 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: August 10 2011 $
+.Dd $Mdocdate: September 16 2011 $
 .Dt MDOC 7
 .Os
 .Sh NAME
@@ -30,11 +30,13 @@ language is used to format
 manuals.
 This reference document describes its syntax, structure, and
 usage.
-The reference implementation is
+The reference implementation for
+.Nm
+formatting is
 .Xr mandoc 1 ;
 the
 .Sx COMPATIBILITY
-section describes compatibility with other troff \-mdoc implementations.
+section describes compatibility with other implementations.
 .Pp
 An
 .Nm
@@ -42,7 +44,7 @@ document follows simple rules: lines beginning with th
 character
 .Sq \&.
 are parsed for macros.
-Text lines, those not beginning with the control character, are
+Lines not beginning with the control character are
 interpreted within the scope of prior macros:
 .Bd -literal -offset indent
 \&.Sh Macro lines change control state.
@@ -52,21 +54,37 @@ Text lines are interpreted within the current state.
 .Nm
 documents may contain only graphable 7-bit ASCII characters, the space
 character, and, in certain circumstances, the tab character.
-.Pp
-If the first character of a text line is a space, that line is printed
-with a leading newline.
+The back-space character
+.Sq \e
+indicates the start of an escape sequence for
+.Sx Comments ,
+.Sx Predefined Strings ,
+and
+.Sx Special Characters .
 .Ss Comments
-Text following a
-.Sq \e\*q ,
+Text following an escaped double-quote
+.Sq \e\(dq ,
 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 ,
+A macro line beginning with a control character and comment escape
+.Sq \&.\e\(dq
 is also ignored.
-Macro lines with only a control character and optional whitespace are
+Furthermore,
+macro lines with only a control character and optional trailing
+whitespace are
 stripped from input.
+.Pp
+Examples:
+.Bd -literal -offset indent -compact
+\&.\e\(dq This is a comment line.
+\&.\e\(dq The next line is ignored:
+\&.
+\&.Em Emphasis \e\(dq This is also a comment.
+.Ed
 .Ss Special Characters
-Special characters may occur in both macro and text lines.
+Special characters are used to encode special glyphs and are rendered
+differently across output media.
+They may occur in both macro and text lines.
 Sequences begin with the escape character
 .Sq \e
 followed by either an open-parenthesis
@@ -76,24 +94,24 @@ for two-character sequences; an open-bracket
 for n-character sequences (terminated at a close-bracket
 .Sq \&] ) ;
 or a single one character sequence.
+.Pp
+Examples:
+.Bl -tag -width Ds -offset indent -compact
+.It Li \e(em
+Two-letter em dash escape.
+.It Li \ee
+One-letter backslash escape.
+.El
+.Pp
 See
 .Xr mandoc_char 7
 for a complete list.
-Examples include
-.Sq \e(em
-.Pq em-dash
-and
-.Sq \ee
-.Pq back-slash .
 .Ss Text Decoration
 Terms may be text-decorated using the
 .Sq \ef
-escape followed by an indicator: B (bold), I (italic), R (Roman), or P
-(revert to previous mode):
-.Pp
-.Dl \efBbold\efR \efIitalic\efP
-.Pp
-A numerical representation 3, 2, or 1 (bold, italic, and Roman,
+escape followed by an indicator: B (bold), I (italic), R (regular), or P
+(revert to previous mode).
+A numerical representation 3, 2, or 1 (bold, italic, and regular,
 respectively) may be used instead.
 If a macro opens a font scope after calling
 .Sq \ef ,
@@ -105,19 +123,23 @@ mode will be restored upon exiting the
 .Sx \&Bf
 scope.
 .Pp
-Note this form is
+Examples:
+.Bl -tag -width Ds -offset indent -compact
+.It Li \efBbold\efR
+Write in bold, then switch to regular font mode.
+.It Li \efIitalic\efP
+Write in italic, then return to previous font mode.
+.El
+.Pp
+Text decoration is
 .Em not
 recommended for
 .Nm ,
 which encourages semantic annotation.
 .Ss Predefined Strings
-Historically,
-troff
-also defined a set of package-specific
-.Dq predefined strings ,
-which, like
+Predefined strings, like
 .Sx Special Characters ,
-mark special output characters and strings by way of input codes.
+mark special output glyphs.
 Predefined strings are escaped with the slash-asterisk,
 .Sq \e* :
 single-character
@@ -126,74 +148,78 @@ two-character
 .Sq \e*(XX ,
 and N-character
 .Sq \e*[N] .
-See
-.Xr mandoc_char 7
-for a complete list.
-Examples include
-.Sq \e*(Am
-.Pq ampersand
-and
-.Sq \e*(Ba
-.Pq vertical bar .
+.Pp
+Examples:
+.Bl -tag -width Ds -offset indent -compact
+.It Li \e*(Am
+Two-letter ampersand predefined string.
+.It Li \e*q
+One-letter double-quote predefined string.
+.El
+.Pp
+These strings are set using
+.Xr roff 7 ,
+although
+.Nm
+consists of several pre-set escapes listed in
+.Xr mandoc_char 7 .
 .Ss Whitespace
 Whitespace consists of the space character.
-In text lines, whitespace is preserved within a line; unescaped
-trailing spaces are stripped from input (unless in a literal context).
-Blank text lines, which may include whitespace, are only permitted
-within literal contexts.
+In text lines, whitespace is preserved within a line.
+In macro lines, whitespace delimits arguments and is discarded.
 .Pp
-In general, trailing whitespace on input lines is discouraged
-for reasons of clarity and portability.
+Unescaped trailing spaces are stripped from text line input unless in a
+literal context.
+In general, trailing whitespace on any input line is discouraged for
+reasons of portability.
 In the rare case that a blank character is needed at the end of an
 input line, it may be forced by
 .Sq \e\ \e& .
 .Pp
-In macro lines, whitespace delimits arguments and is discarded.
+In general, space characters can be rendered as literal
+characters by using non-breaking space escapes or
+.Sx Quotation .
+.Pp
+Blank text lines, which may include whitespace, are only permitted
+within literal contexts.
+If the first character of a text line is a space, that line is printed
+with a leading newline.
 .Ss Quotation
-Macro arguments may be quoted with double-quotes; in this case,
-whitespace within the quotes is retained as part of the argument.
-For example,
+Macro arguments may be quoted with double-quotes to so that the
+enclosed text is one literal term.
+Quoted text, even if whitespace or if it would cause a macro invocation
+when unquoted, is considered literal text.
 .Pp
-.D1 Pf \. \&Fn strlen "\(dqconst char *s\(dq"
-.Pp
-renders as
-.Sq Fn strlen "const char *s" ,
-while
-.Pp
-.D1 Pf \. \&Fn strlen "const char *s"
-.Pp
-would produce
-.Sq Fn strlen const char *s .
-.Pp
 A quoted argument begins with a double-quote preceded by whitespace.
 The next double-quote not pairwise adjacent to another double-quote
 terminates the literal, regardless of surrounding whitespace.
 .Pp
-In unquoted arguments, space characters can alternatively be included
-by preceding them with a backslash
-.Pq Sq \e\~ ,
-but quoting is usually better for clarity.
-.Pp
-Note that any quoted text, even if it would cause a macro invocation
-when unquoted, is considered literal text.
-Thus, the following produces
-.Sq Op "Fl a" :
-.Bd -literal -offset indent
-\&.Op "Fl a"
-.Ed
-.Pp
-In text lines, quotes are regarded as opaque text.
+Examples:
+.Bl -tag -width Ds -offset indent -compact
+.It Li .Fn strlen \(dqconst char *s\(dq
+Group arguments
+.Qq const char *s
+into one function argument.
+If unspecified,
+.Qq const ,
+.Qq char ,
+and
+.Qq *s
+would be considered separate arguments.
+.Pq See Sx \&Fn .
+.It Li .Op \(dqFl a\(dq
+Consider
+.Qq \&Fl a
+as literal text instead of a flag macro.
+.Pq Aee Sx \&Op , \&Fl .
+.El
 .Ss Scaling Widths
-Many macros support scaled widths for their arguments, such as
-stipulating a two-inch list indentation with the following:
-.Bd -literal -offset indent
-\&.Bl -tag -width 2i
-.Ed
-.Pp
-The syntax for scaled widths is
+Many macros support scaled widths for their arguments.
+The syntax for a scaled width is
 .Sq Li [+-]?[0-9]*.[0-9]*[:unit:] ,
 where a decimal must be preceded or proceeded by at least one digit.
 Negative numbers, while accepted, are truncated to zero.
+.Pp
 The following scaling units are accepted:
 .Pp
 .Bl -tag -width Ds -offset indent -compact
@@ -235,10 +261,19 @@ or
 is necessarily non-portable across output media.
 See
 .Sx COMPATIBILITY .
+.Pp
+Examples:
+.Bl -tag -width Ds -offset indent -compact
+.It Li \&.Bl -tag -width 2i
+two-inch tagged list indentation
+.Pq see Sx \&Bl
+.It Li \&.sp 2v
+two vertical spaces
+.Pq see Sx \&sp
+.El
 .Ss Sentence Spacing
-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
+Sentences should terminate at the end of an input line.
+By doing this, a formatter 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
@@ -251,10 +286,14 @@ delimiters
 .Pp
 The proper spacing is also intelligently preserved if a sentence ends at
 the boundary of a macro line.
-For example:
 .Pp
-.Dl \&.Xr mandoc 1 \&.
-.Dl \&.Fl T \&Ns \&Cm ascii \&.
+Examples:
+.Bd -literal -offset indent -compact
+Do not end sentences mid-line like this.  Instead,
+end a sentence like this.
+A macro would end like this:
+\&.Xr mandoc 1 \&.
+.Ed
 .Sh MANUAL STRUCTURE
 A well-formed
 .Nm
@@ -292,9 +331,9 @@ file for a utility
 \&.Sh NAME
 \&.Nm progname
 \&.Nd one line about what it does
-\&.\e\*q .Sh LIBRARY
-\&.\e\*q For sections 2, 3, & 9 only.
-\&.\e\*q Not used in OpenBSD.
+\&.\e\(dq .Sh LIBRARY
+\&.\e\(dq For sections 2, 3, & 9 only.
+\&.\e\(dq Not used in OpenBSD.
 \&.Sh SYNOPSIS
 \&.Nm progname
 \&.Op Fl options
@@ -303,29 +342,29 @@ file for a utility
 The
 \&.Nm
 utility processes files ...
-\&.\e\*q .Sh IMPLEMENTATION NOTES
-\&.\e\*q Not used in OpenBSD.
-\&.\e\*q .Sh RETURN VALUES
-\&.\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 .Sh EXIT STATUS
-\&.\e\*q For sections 1, 6, & 8 only.
-\&.\e\*q .Sh EXAMPLES
-\&.\e\*q .Sh DIAGNOSTICS
-\&.\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
-\&.\e\*q .Sh HISTORY
-\&.\e\*q .Sh AUTHORS
-\&.\e\*q .Sh CAVEATS
-\&.\e\*q .Sh BUGS
-\&.\e\*q .Sh SECURITY CONSIDERATIONS
-\&.\e\*q Not used in OpenBSD.
+\&.\e\(dq .Sh IMPLEMENTATION NOTES
+\&.\e\(dq Not used in OpenBSD.
+\&.\e\(dq .Sh RETURN VALUES
+\&.\e\(dq For sections 2, 3, & 9 only.
+\&.\e\(dq .Sh ENVIRONMENT
+\&.\e\(dq For sections 1, 6, 7, & 8 only.
+\&.\e\(dq .Sh FILES
+\&.\e\(dq .Sh EXIT STATUS
+\&.\e\(dq For sections 1, 6, & 8 only.
+\&.\e\(dq .Sh EXAMPLES
+\&.\e\(dq .Sh DIAGNOSTICS
+\&.\e\(dq For sections 1, 4, 6, 7, & 8 only.
+\&.\e\(dq .Sh ERRORS
+\&.\e\(dq For sections 2, 3, & 9 only.
+\&.\e\(dq .Sh SEE ALSO
+\&.\e\(dq .Xr foobar 1
+\&.\e\(dq .Sh STANDARDS
+\&.\e\(dq .Sh HISTORY
+\&.\e\(dq .Sh AUTHORS
+\&.\e\(dq .Sh CAVEATS
+\&.\e\(dq .Sh BUGS
+\&.\e\(dq .Sh SECURITY CONSIDERATIONS
+\&.\e\(dq Not used in OpenBSD.
 .Ed
 .Pp
 The sections in an
@@ -406,8 +445,8 @@ 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
-\&.Cd \*qit* at isa? port 0x4e\*q
+\&.Cd \(dqit* at isa? port 0x2e\(dq
+\&.Cd \(dqit* at isa? port 0x4e\(dq
 .Ed
 .Pp
 Manuals not in these sections generally don't need a
@@ -471,6 +510,21 @@ Print verbose information.
 .Ed
 .Pp
 Manuals not documenting a command won't include the above fragment.
+.Pp
+Since the
+.Em DESCRIPTION
+section usually contains most of the text of a manual, longer manuals
+often use the
+.Sx \&Ss
+macro to form subsections.
+In very long manuals, the
+.Em DESCRIPTION
+may be split into multiple sections, each started by an
+.Sx \&Sh
+macro followed by a non-standard section name, and each having
+several subsections, like in the present
+.Nm
+manual.
 .It Em IMPLEMENTATION NOTES
 Implementation-specific notes should be kept here.
 This is useful when implementing standard functions that may have side
@@ -532,7 +586,13 @@ This section should exist for most manuals.
 Cross-references should conventionally be ordered first by section, then
 alphabetically.
 .Pp
+References to other documentation concerning the topic of the manual page,
+for example authoritative books or journal articles, may also be
+provided in this section.
+.Pp
 See
+.Sx \&Rs
+and
 .Sx \&Xr .
 .It Em STANDARDS
 References any standards implemented or used.
@@ -543,7 +603,8 @@ section should be used instead.
 See
 .Sx \&St .
 .It Em HISTORY
-A brief history of the subject, including where support first appeared.
+A brief history of the subject, including where it was first implemented,
+and when it was ported to or reimplemented for the operating system at hand.
 .It Em AUTHORS
 Credits to the person or persons who wrote the code and/or documentation.
 Authors should generally be noted by both name and email address.
@@ -628,8 +689,7 @@ contain a head.
 \(lBbody...\(rB
 \&.Yc
 .Ed
-.Pp
-.Bl -column -compact -offset indent "MacroX" "CallableX" "ParsedX" "closed by XXX"
+.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXX" -offset indent
 .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
@@ -661,8 +721,7 @@ has multiple heads.
 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB
 \(lBbody...\(rB
 .Ed
-.Pp
-.Bl -column -compact -offset indent "MacroX" "CallableX" "ParsedX" "closed by XXXXXXXXXXX"
+.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXXXXXXXXX" -offset indent
 .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
@@ -697,8 +756,7 @@ and/or tail
 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \
 \(lBbody...\(rB \&Yc \(lBtail...\(rB
 .Ed
-.Pp
-.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -compact -offset indent
+.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -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
@@ -731,8 +789,7 @@ end of the line.
 .Bd -literal -offset indent
 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB
 .Ed
-.Pp
-.Bl -column "MacroX" "CallableX" "ParsedX" -compact -offset indent
+.Bl -column "MacroX" "CallableX" "ParsedX" -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
@@ -767,8 +824,7 @@ in
 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
+.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -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
@@ -786,8 +842,7 @@ then the macro accepts an arbitrary number of argument
 
 \&.Yo \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN
 .Ed
-.Pp
-.Bl -column "MacroX" "CallableX" "ParsedX" "Arguments" -compact -offset indent
+.Bl -column "MacroX" "CallableX" "ParsedX" "Arguments" -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
@@ -1176,20 +1231,27 @@ The
 must be one of the following:
 .Bl -tag -width 13n -offset indent
 .It Fl centered
-Centre-justify each line.
+Produce one output line from each input line, and 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.
+Change the positions of line breaks to fill each line, and left- and
+right-justify the resulting block.
 .It Fl literal
-Do not justify the block at all.
+Produce one output line from each input line,
+and do not justify the block at all.
 Preserve white space as it appears in the input.
+Always use a constant-width font.
+Use this for displaying source code.
 .It Fl ragged
-Only left-justify the block.
+Change the positions of line breaks to fill each line, and left-justify
+the resulting block.
 .It Fl unfilled
-An alias for
-.Fl literal .
+The same as
+.Fl literal ,
+but using the same font as for normal text, which is a variable width font
+if supported by the output device.
 .El
 .Pp
 The
@@ -1205,7 +1267,7 @@ which may be one of the following:
 .It
 One of the pre-defined strings
 .Cm indent ,
-the width of standard indentation;
+the width of a standard indentation (six constant width characters);
 .Cm indent-two ,
 twice
 .Cm indent ;
@@ -1382,9 +1444,12 @@ except that dashes are used in place of bullets.
 Like
 .Fl inset ,
 except that item heads are not parsed for macro invocations.
-.\" but with additional formatting to the head.
+Most often used in the
+.Em DIAGNOSTICS
+section with error constants in the item heads.
 .It Fl enum
 A numbered list.
+No item heads can be specified.
 Formatted like
 .Fl bullet ,
 except that cardinal numbers are used in place of bullets,
@@ -1424,6 +1489,13 @@ this head on the same output line.
 Otherwise, the body starts on the output line following the head.
 .El
 .Pp
+Lists may be nested within lists and displays.
+Nesting of
+.Fl column
+and
+.Fl enum
+lists may not be portable.
+.Pp
 See also
 .Sx \&El
 and
@@ -1500,12 +1572,13 @@ 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:
+.Dl \&.Bx 4.3 Tahoe
 .Dl \&.Bx 4.4
 .Dl \&.Bx
 .Pp
@@ -1865,9 +1938,12 @@ See also
 and
 .Sx \&It .
 .Ss \&Em
-Denotes text that should be emphasised.
+Denotes text that should be
+.Em emphasised .
 Note that this is a presentation term and should not be used for
 stylistically decorating technical terms.
+Depending on the output device, this is usually represented
+using an italic font or underlined characters.
 .Pp
 Examples:
 .Dl \&.Em Warnings!
@@ -1875,9 +1951,10 @@ Examples:
 .Pp
 See also
 .Sx \&Bf ,
-.Sx \&Sy ,
+.Sx \&Li ,
+.Sx \&No ,
 and
-.Sx \&Li .
+.Sx \&Sy .
 .Ss \&En
 This macro is obsolete and not implemented in
 .Xr mandoc 1 .
@@ -1992,11 +2069,11 @@ If the argument is a macro, a hyphen is prefixed to th
 output.
 .Pp
 Examples:
-.Dl ".Nm cat Fl v No considered harmful"
-.Dl ".Nm cp Fl pR Ar source ... directory"
-.Dl ".Nm find Ar dir Fl type Cm d Fl name Pa CVS
-.Dl ".Nm kill Fl Ar signal_number pid"
-.Dl ".Nm su Fl"
+.Dl ".Fl R Op Fl H | L | P"
+.Dl ".Op Fl 1AaCcdFfgHhikLlmnopqRrSsTtux"
+.Dl ".Fl type Cm d Fl name Pa CVS"
+.Dl ".Fl Ar signal_number"
+.Dl ".Fl o Fl"
 .Pp
 See also
 .Sx \&Cm .
@@ -2019,8 +2096,8 @@ section, this macro starts a new output line,
 and a blank line is automatically inserted between function definitions.
 .Pp
 Examples:
-.Dl \&.Fn \*qint funcname\*q \*qint arg0\*q \*qint arg1\*q
-.Dl \&.Fn funcname \*qint arg0\*q
+.Dl \&.Fn \(dqint funcname\(dq \(dqint arg0\(dq \(dqint arg1\(dq
+.Dl \&.Fn funcname \(dqint arg0\(dq
 .Dl \&.Fn funcname arg0
 .Pp
 .Bd -literal -offset indent -compact
@@ -2069,7 +2146,13 @@ See also
 and
 .Sx \&Ft .
 .Ss \&Fr
-This macro is obsolete and not implemented.
+This macro is obsolete and not implemented in
+.Xr mandoc 1 .
+.Pp
+It was used to show function return values.
+The syntax was:
+.Pp
+.Dl Pf . Sx \&Fr Ar value
 .Ss \&Ft
 A function type.
 Its syntax is as follows:
@@ -2112,7 +2195,13 @@ See also
 and
 .Sx \&Ux .
 .Ss \&Hf
-This macro is obsolete and not implemented.
+This macro is not implemented in
+.Xr mandoc 1 .
+.Pp
+It was used to include the contents of a (header) file literally.
+The syntax was:
+.Pp
+.Dl Pf . Sx \&Hf Ar filename
 .Ss \&Ic
 Designate an internal or interactive command.
 This is similar to
@@ -2213,7 +2302,7 @@ 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,
+is only recognised 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
@@ -2251,15 +2340,21 @@ Examples:
 .Dl \&.Lb libz
 .Dl \&.Lb mdoc
 .Ss \&Li
-Denotes text that should be in a literal font mode.
+Denotes text that should be in a
+.Li literal
+font mode.
 Note that this is a presentation term and should not be used for
 stylistically decorating technical terms.
 .Pp
+On terminal output devices, this is often indistinguishable from
+normal text.
+.Pp
 See also
 .Sx \&Bf ,
-.Sx \&Sy ,
+.Sx \&Em ,
+.Sx \&No ,
 and
-.Sx \&Em .
+.Sx \&Sy .
 .Ss \&Lk
 Format a hyperlink.
 Its syntax is as follows:
@@ -2267,7 +2362,7 @@ Its syntax is as follows:
 .D1 Pf \. Sx \&Lk Ar uri Op Ar name
 .Pp
 Examples:
-.Dl \&.Lk http://bsd.lv \*qThe BSD.lv Project\*q
+.Dl \&.Lk http://bsd.lv \(dqThe BSD.lv Project\(dq
 .Dl \&.Lk http://bsd.lv
 .Pp
 See also
@@ -2303,8 +2398,8 @@ section subsequent the
 macro.
 .Pp
 Examples:
-.Dl \&.Sx \&Nd mdoc language reference
-.Dl \&.Sx \&Nd format and display UNIX manuals
+.Dl Pf . Sx \&Nd mdoc language reference
+.Dl Pf . Sx \&Nd format and display UNIX manuals
 .Pp
 The
 .Sx \&Nd
@@ -2356,21 +2451,44 @@ macro rather than
 .Sx \&Nm
 to mark up the name of the manual page.
 .Ss \&No
-A
-.Dq noop
-macro used to terminate prior macro contexts.
+Normal text.
+Closes the scope of any preceding in-line macro.
+When used after physical formatting macros like
+.Sx \&Em
+or
+.Sx \&Sy ,
+switches back to the standard font face and weight.
+Can also be used to embed plain text strings in macro lines
+using semantic annotation macros.
 .Pp
 Examples:
-.Dl \&.Sx \&Fl ab \&No cd \&Fl ef
+.Dl ".Em italic , Sy bold , No and roman"
+.Pp
+.Bd -literal -offset indent -compact
+\&.Sm off
+\&.Cm :C No / Ar pattern No / Ar replacement No /
+\&.Sm on
+.Ed
+.Pp
+See also
+.Sx \&Em ,
+.Sx \&Li ,
+and
+.Sx \&Sy .
 .Ss \&Ns
-Suppress a space.
-Following invocation, text is interpreted as free-form text until a
-macro is encountered.
+Suppress a space between the output of the preceding macro
+and the following text or macro.
+Following invocation, input is interpreted as normal text
+just like after an
+.Sx \&No
+macro.
 .Pp
 This has no effect when invoked at the start of a macro line.
 .Pp
 Examples:
-.Dl \&.Fl o \&Ns \&Ar output
+.Dl ".Ar name Ns = Ns Ar value"
+.Dl ".Cm :M Ns Ar pattern"
+.Dl ".Fl o Ns Ar output"
 .Pp
 See also
 .Sx \&No
@@ -2448,10 +2566,13 @@ See also
 and
 .Sx \&Dt .
 .Ss \&Ot
-Unknown usage.
+This macro is obsolete and not implemented in
+.Xr mandoc 1 .
 .Pp
-.Em Remarks :
-this macro has been deprecated.
+Historical
+.Xr mdoc 7
+packages described it as
+.Dq "old function type (FORTRAN)" .
 .Ss \&Ox
 Format the
 .Ox
@@ -2487,19 +2608,25 @@ See also
 Close parenthesised context opened by
 .Sx \&Po .
 .Ss \&Pf
-Removes the space
+Removes the space between its argument
 .Pq Dq prefix
-between its arguments.
+and the following macro.
 Its syntax is as follows:
 .Pp
-.D1 Pf \. \&Pf Ar prefix suffix
+.D1 .Pf Ar prefix macro arguments ...
 .Pp
-The
-.Ar suffix
-argument may be a macro.
+This is equivalent to:
 .Pp
+.D1 .No Ar prefix No \&Ns Ar macro arguments ...
+.Pp
 Examples:
-.Dl \&.Pf \e. \&Sx \&Pf \&Ar prefix suffix
+.Dl ".Pf $ Ar variable_name"
+.Dl ".Pf 0x Ar hex_digits"
+.Pp
+See also
+.Sx \&Ns
+and
+.Sx \&Sm .
 .Ss \&Po
 Multi-line version of
 .Sx \&Pq .
@@ -2507,6 +2634,18 @@ Multi-line version of
 Break a paragraph.
 This will assert vertical space between prior and subsequent macros
 and/or text.
+.Pp
+Paragraph breaks are not needed before or after
+.Sx \&Sh
+or
+.Sx \&Ss
+macros or before displays
+.Pq Sx \&Bd
+or lists
+.Pq Sx \&Bl
+unless the
+.Fl compact
+flag is given.
 .Ss \&Pq
 Parenthesised enclosure.
 .Pp
@@ -2526,7 +2665,7 @@ Multi-line version of
 .Sx \&Qq .
 .Ss \&Qq
 Encloses its arguments in
-.Dq typewriter
+.Qq typewriter
 double-quotes.
 Consider using
 .Sx \&Dq .
@@ -2640,7 +2779,7 @@ Multi-line version of
 .Sx \&Sq .
 .Ss \&Sq
 Encloses its arguments in
-.Dq typewriter
+.Sq typewriter
 single-quotes.
 .Pp
 See also
@@ -2649,13 +2788,15 @@ See also
 and
 .Sx \&So .
 .Ss \&Ss
-Begin a new sub-section.
+Begin a new subsection.
 Unlike with
 .Sx \&Sh ,
-there's no convention for sub-sections.
-Conventional sections, as described in
-.Sx MANUAL STRUCTURE ,
-rarely have sub-sections.
+there is no convention for the naming of subsections.
+Except
+.Em DESCRIPTION ,
+the conventional sections described in
+.Sx MANUAL STRUCTURE
+rarely have subsections.
 .Pp
 Sub-section names should be unique so that they may be keyed by
 .Sx \&Sx .
@@ -2735,6 +2876,8 @@ The following standards are recognised:
 .St -ieee754
 .It \-iso8802-3
 .St -iso8802-3
+.It \-iso8601
+.St -iso8601
 .It \-ieee1275-94
 .St -ieee1275-94
 .It \-xpg3
@@ -2767,8 +2910,8 @@ The following standards are recognised:
 .St -svid4
 .El
 .Ss \&Sx
-Reference a section or sub-section.
-The referenced section or sub-section name must be identical to the
+Reference a section or subsection in the same manual page.
+The referenced section or subsection name must be identical to the
 enclosed argument, including whitespace.
 .Pp
 Examples:
@@ -2786,9 +2929,10 @@ stylistically decorating technical terms.
 .Pp
 See also
 .Sx \&Bf ,
+.Sx \&Em ,
 .Sx \&Li ,
 and
-.Sx \&Em .
+.Sx \&No .
 .Ss \&Ta
 Table cell separator in
 .Sx \&Bl Fl column
@@ -2797,11 +2941,16 @@ lists; can only be used below
 .Ss \&Tn
 Format a tradename.
 .Pp
+Since this macro is often implemented to use a small caps font,
+it has historically been used for acronyms (like ASCII) as well.
+Such usage is not recommended because it would use the same macro
+sometimes for semantical annotation, sometimes for physical formatting.
+.Pp
 Examples:
 .Dl \&.Tn IBM
 .Ss \&Ud
 Prints out
-.Dq currently under development .
+.Dq currently under development.
 .Ss \&Ux
 Format the UNIX name.
 Accepts no argument.
@@ -2947,7 +3096,7 @@ Newer groff and mandoc print
 and the arguments.
 .It
 .Sx \&Bl Fl column
-does not recognize trailing punctuation characters when they immediately
+does not recognise trailing punctuation characters when they immediately
 precede tabulator characters, but treats them as normal text and
 outputs a space before them.
 .It
@@ -3059,7 +3208,7 @@ The following features are unimplemented in mandoc:
 .Fl offset Ar center
 and
 .Fl offset Ar right .
-Groff does not implement centered and flush-right rendering either,
+Groff does not implement centred and flush-right rendering either,
 but produces large indentations.
 .It
 The
@@ -3097,7 +3246,7 @@ This is not supported by mandoc.
 .Xr mandoc 1 ,
 .Xr eqn 7 ,
 .Xr man 7 ,
-.Xr mandoc_char 7
+.Xr mandoc_char 7 ,
 .Xr roff 7 ,
 .Xr tbl 7
 .Sh HISTORY
@@ -3115,4 +3264,5 @@ utility written by Kristaps Dzonsons appeared in
 The
 .Nm
 reference was written by
-.An Kristaps Dzonsons Aq kristaps@bsd.lv .
+.An Kristaps Dzonsons ,
+.Mt kristaps@bsd.lv .