Do not open a subsection for each and every macro.

Instead, use a tagged list and the canonical .Ic macro
as it is natural for such purposes.
While here, also delete heaps of needless escaping.

1 files changed, 165 insertions, 178 deletions

diff --git a/man.7 b/man.7
index f7b47902..7706b5ca 100644
--- a/man.7
+++ b/man.7
@@ -1,4 +1,4 @@
-.\"	$Id: man.7,v 1.142 2019/01/01 03:45:29 schwarze Exp $
+.\"	$Id: man.7,v 1.143 2019/03/02 22:04:40 schwarze Exp $
 .\"
 .\" Copyright (c) 2009, 2010, 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2011-2015,2017,2018,2019 Ingo Schwarze <schwarze@openbsd.org>
@@ -17,7 +17,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: January 1 2019 $
+.Dd $Mdocdate: March 2 2019 $
 .Dt MAN 7
 .Os
 .Sh NAME
@@ -72,7 +72,7 @@ comments, escape sequences, whitespace, and quoting.
 Each
 .Nm
 document starts with the
-.Sx \&TH
+.Ic TH
 macro specifying the document's name and section, followed by the
 .Sx NAME
 section formatted as follows:
@@ -88,47 +88,48 @@ Deprecated and non-portable macros are not included in the overview,
 but can be found in the alphabetical reference below.
 .Ss Page header and footer meta-data
 .Bl -column "RS, RE" description
-.It Sx TH Ta set the title: Ar name section date Op Ar source Op Ar volume
-.It Sx AT Ta display AT&T UNIX version in the page footer (<= 1 argument)
-.It Sx UC Ta display BSD version in the page footer (<= 1 argument)
+.It Ic TH Ta set the title: Ar name section date Op Ar source Op Ar volume
+.It Ic AT Ta display AT&T UNIX version in the page footer (<= 1 argument)
+.It Ic UC Ta display BSD version in the page footer (<= 1 argument)
 .El
 .Ss Sections and paragraphs
 .Bl -column "RS, RE" description
-.It Sx SH Ta section header (one line)
-.It Sx SS Ta subsection header (one line)
-.It Sx PP Ta start an undecorated paragraph (no arguments)
-.It Sx RS , RE Ta reset the left margin: Op Ar width
-.It Sx IP Ta indented paragraph: Op Ar head Op Ar width
-.It Sx TP Ta tagged paragraph: Op Ar width
-.It Sx PD Ta set vertical paragraph distance: Op Ar height
-.It Sx in Ta additional indent: Op Ar width
+.It Ic SH Ta section header (one line)
+.It Ic SS Ta subsection header (one line)
+.It Ic PP Ta start an undecorated paragraph (no arguments)
+.It Ic RS , RE Ta reset the left margin: Op Ar width
+.It Ic IP Ta indented paragraph: Op Ar head Op Ar width
+.It Ic TP Ta tagged paragraph: Op Ar width
+.It Ic PD Ta set vertical paragraph distance: Op Ar height
+.It Ic in Ta additional indent: Op Ar width
 .El
 .Ss Physical markup
 .Bl -column "RS, RE" description
-.It Sx B Ta boldface font
-.It Sx I Ta italic font
-.It Sx SB Ta small boldface font
-.It Sx SM Ta small roman font
-.It Sx BI Ta alternate between boldface and italic fonts
-.It Sx BR Ta alternate between boldface and roman fonts
-.It Sx IB Ta alternate between italic and boldface fonts
-.It Sx IR Ta alternate between italic and roman fonts
-.It Sx RB Ta alternate between roman and boldface fonts
-.It Sx RI Ta alternate between roman and italic fonts
+.It Ic B Ta boldface font
+.It Ic I Ta italic font
+.It Ic SB Ta small boldface font
+.It Ic SM Ta small roman font
+.It Ic BI Ta alternate between boldface and italic fonts
+.It Ic BR Ta alternate between boldface and roman fonts
+.It Ic IB Ta alternate between italic and boldface fonts
+.It Ic IR Ta alternate between italic and roman fonts
+.It Ic RB Ta alternate between roman and boldface fonts
+.It Ic RI Ta alternate between roman and italic fonts
 .El
 .Sh MACRO REFERENCE
 This section is a canonical reference to all macros, arranged
 alphabetically.
 For the scoping of individual macros, see
 .Sx MACRO SYNTAX .
-.Ss \&AT
+.Bl -tag -width 3n
+.It Ic AT
 Sets the volume for the footer for compatibility with man pages from
 .At
 releases.
 The optional arguments specify which release it is from.
-.Ss \&B
+.It Ic B
 Text is rendered in bold face.
-.Ss \&BI
+.It Ic BI
 Text is rendered alternately in bold face and italic.
 Thus,
 .Sq .BI this word and that
@@ -146,41 +147,39 @@ Whitespace between arguments is omitted in output.
 Example:
 .Pp
 .Dl \&.BI bold italic bold italic
-.Ss \&BR
+.It Ic BR
 Text is rendered alternately in bold face and roman (the default font).
 Whitespace between arguments is omitted in output.
 See also
-.Sx \&BI .
-.Ss \&DT
+.Ic BI .
+.It Ic DT
 Restore the default tabulator positions.
 They are at intervals of 0.5 inches.
 This has no effect unless the tabulator positions were changed with the
 .Xr roff 7
-.Ic \&ta
+.Ic ta
 request.
-.Ss \&EE
+.It Ic EE
 This is a non-standard GNU extension.
 In
 .Xr mandoc 1 ,
 it does the same as the
 .Xr roff 7
-.Sx \&fi
+.Ic fi
 request (switch to fill mode).
-.Ss \&EX
+.It Ic EX
 This is a non-standard GNU extension.
 In
 .Xr mandoc 1 ,
 it does the same as the
 .Xr roff 7
-.Ic \&nf
+.Ic nf
 request (switch to no-fill mode).
-.Ss \&HP
+.It Ic HP
 Begin a paragraph whose initial output line is left-justified, but
 subsequent output lines are indented, with the following syntax:
-.Bd -filled -offset indent
-.Pf \. Sx \&HP
-.Op Ar width
-.Ed
+.Pp
+.D1 Pf . Ic HP Op Ar width
 .Pp
 The
 .Ar width
@@ -193,20 +192,18 @@ if unspecified, the saved or default width is used.
 This macro is portable, but deprecated
 because it has no good representation in HTML output,
 usually ending up indistinguishable from
-.Sx \&PP .
-.Ss \&I
+.Ic PP .
+.It Ic I
 Text is rendered in italics.
-.Ss \&IB
+.It Ic IB
 Text is rendered alternately in italics and bold face.
 Whitespace between arguments is omitted in output.
 See also
-.Sx \&BI .
-.Ss \&IP
+.Ic BI .
+.It Ic IP
 Begin an indented paragraph with the following syntax:
-.Bd -filled -offset indent
-.Pf \. Sx \&IP
-.Op Ar head Op Ar width
-.Ed
+.Pp
+.D1 Pf . Ic IP Op Ar head Op Ar width
 .Pp
 The
 .Ar width
@@ -220,52 +217,48 @@ The
 .Ar head
 argument is used as a leading term, flushed to the left margin.
 This is useful for bulleted paragraphs and so on.
-.Ss \&IR
+.It Ic IR
 Text is rendered alternately in italics and roman (the default font).
 Whitespace between arguments is omitted in output.
 See also
-.Sx \&BI .
-.Ss \&LP
+.Ic BI .
+.It Ic LP
 A synonym for
-.Sx \&PP .
-.Ss \&ME
+.Ic PP .
+.It Ic ME
 End a mailto block started with
-.Sx \&MT .
+.Ic MT .
 This is a non-standard GNU extension.
-.Ss \&MT
+.It Ic MT
 Begin a mailto block.
 This is a non-standard GNU extension.
 It has the following syntax:
-.Bd -literal -offset indent
-.Pf \. Sx \&MT Ar address
+.Bd -unfilled -offset indent
+.Pf . Ic MT Ar address
 link description to be shown
-.Pf \. Sx ME
+.Pf . Ic ME
 .Ed
-.Ss \&OP
+.It Ic OP
 Optional command-line argument.
 This is a non-standard GNU extension.
 It has the following syntax:
-.Bd -filled -offset indent
-.Pf \. Sx \&OP
-.Ar key Op Ar value
-.Ed
+.Pp
+.D1 Pf . Ic OP Ar key Op Ar value
 .Pp
 The
 .Ar key
 is usually a command-line flag and
 .Ar value
 its argument.
-.Ss \&P
+.It Ic P
 A synonym for
-.Sx \&PP .
-.Ss \&PD
+.Ic PP .
+.It Ic PD
 Specify the vertical space to be inserted before each new paragraph.
 .br
 The syntax is as follows:
-.Bd -filled -offset indent
-.Pf \. Sx \&PD
-.Op Ar height
-.Ed
+.Pp
+.D1 Pf . Ic PD Op Ar height
 .Pp
 The
 .Ar height
@@ -279,64 +272,60 @@ If the unit is omitted,
 is assumed.
 .Pp
 This macro affects the spacing before any subsequent instances of
-.Sx \&HP ,
-.Sx \&IP ,
-.Sx \&LP ,
-.Sx \&P ,
-.Sx \&PP ,
-.Sx \&SH ,
-.Sx \&SS ,
-.Sx \&SY ,
+.Ic HP ,
+.Ic IP ,
+.Ic LP ,
+.Ic P ,
+.Ic PP ,
+.Ic SH ,
+.Ic SS ,
+.Ic SY ,
 and
-.Sx \&TP .
-.Ss \&PP
+.Ic TP .
+.It Ic PP
 Begin an undecorated paragraph.
 The scope of a paragraph is closed by a subsequent paragraph,
 sub-section, section, or end of file.
 The saved paragraph left-margin width is reset to the default.
-.Ss \&RB
+.It Ic RB
 Text is rendered alternately in roman (the default font) and bold face.
 Whitespace between arguments is omitted in output.
 See also
-.Sx \&BI .
-.Ss \&RE
+.Ic BI .
+.It Ic RE
 Explicitly close out the scope of a prior
-.Sx \&RS .
+.Ic RS .
 The default left margin is restored to the state before that
-.Sx \&RS
+.Ic RS
 invocation.
 .Pp
 The syntax is as follows:
-.Bd -filled -offset indent
-.Pf \. Sx \&RE
-.Op Ar level
-.Ed
+.Pp
+.D1 Pf . Ic RE Op Ar level
 .Pp
 Without an argument, the most recent
-.Sx \&RS
+.Ic RS
 block is closed out.
 If
 .Ar level
 is 1, all open
-.Sx \&RS
+.Ic RS
 blocks are closed out.
 Otherwise,
 .Ar level No \(mi 1
 nested
-.Sx \&RS
+.Ic RS
 blocks remain open.
-.Ss \&RI
+.It Ic RI
 Text is rendered alternately in roman (the default font) and italics.
 Whitespace between arguments is omitted in output.
 See also
-.Sx \&BI .
-.Ss \&RS
+.Ic BI .
+.It Ic RS
 Temporarily reset the default left margin.
 This has the following syntax:
-.Bd -filled -offset indent
-.Pf \. Sx \&RS
-.Op Ar width
-.Ed
+.Pp
+.D1 Pf . Ic RS Op Ar width
 .Pp
 The
 .Ar width
@@ -346,43 +335,40 @@ scaling width.
 If not specified, the saved or default width is used.
 .Pp
 See also
-.Sx \&RE .
-.Ss \&SB
+.Ic RE .
+.It Ic SB
 Text is rendered in small size (one point smaller than the default font)
 bold face.
-.Ss \&SH
+.It Ic SH
 Begin a section.
 The scope of a section is only closed by another section or the end of
 file.
 The paragraph left-margin width is reset to the default.
-.Ss \&SM
+.It Ic SM
 Text is rendered in small size (one point smaller than the default
 font).
-.Ss \&SS
+.It Ic SS
 Begin a sub-section.
 The scope of a sub-section is closed by a subsequent sub-section,
 section, or end of file.
 The paragraph left-margin width is reset to the default.
-.Ss \&SY
+.It Ic SY
 Begin a synopsis block with the following syntax:
 .Bd -unfilled -offset indent
-.Pf \. Sx \&SY Ar command
+.Pf . Ic SY Ar command
 .Ar arguments
-.Pf \. Sx \&YS
+.Pf . Ic YS
 .Ed
 .Pp
 This is a non-standard GNU extension
 and very rarely used even in GNU manual pages.
 Formatting is similar to
-.Sx \&IP .
-.Ss \&TH
+.Ic IP .
+.It Ic TH
 Set the name of the manual page for use in the page header
 and footer with the following syntax:
-.Bd -filled -offset indent
-.Pf \. Sx \&TH
-.Ar name section date
-.Op Ar source Op Ar volume
-.Ed
+.Pp
+.D1 Pf . Ic TH Ar name section date Op Ar source Op Ar volume
 .Pp
 Conventionally, the document
 .Ar name
@@ -415,14 +401,14 @@ string replaces the default volume title of the
 Examples:
 .Pp
 .Dl \&.TH CVS 5 "1992-02-12" GNU
-.Ss \&TP
+.It Ic TP
 Begin a paragraph where the head, if exceeding the indentation width, is
 followed by a newline; if not, the body follows on the same line after
 advancing to the indentation width.
 Subsequent output lines are indented.
 The syntax is as follows:
 .Bd -unfilled -offset indent
-.Pf \. Sx \&TP Op Ar width
+.Pf . Ic TP Op Ar width
 .Ar head No \e" one line
 .Ar body
 .Ed
@@ -434,44 +420,45 @@ argument is a
 scaling width.
 If specified, it's saved for later paragraph left-margins; if
 unspecified, the saved or default width is used.
-.Ss \&TQ
+.It Ic TQ
 Like
-.Sx \&TP ,
+.Ic TP ,
 except that no vertical spacing is inserted before the paragraph.
 This is a non-standard GNU extension
 and very rarely used even in GNU manual pages.
-.Ss \&UC
+.It Ic UC
 Sets the volume for the footer for compatibility with man pages from
 .Bx
 releases.
 The optional first argument specifies which release it is from.
-.Ss \&UE
+.It Ic UE
 End a uniform resource identifier block started with
-.Sx \&UR .
+.Ic UR .
 This is a non-standard GNU extension.
-.Ss \&UR
+.It Ic UR
 Begin a uniform resource identifier block.
 This is a non-standard GNU extension.
 It has the following syntax:
-.Bd -literal -offset indent
-.Pf \. Sx \&UR Ar uri
+.Bd -unfilled -offset indent
+.Pf . Ic UR Ar uri
 link description to be shown
-.Pf \. Sx UE
+.Pf . Ic UE
 .Ed
-.Ss \&YS
+.It Ic YS
 End a synopsis block started with
-.Sx \&SY .
+.Ic SY .
 This is a non-standard GNU extension.
-.Ss \&in
+.It Ic in
 Indent relative to the current indentation:
 .Pp
-.D1 Pf \. Sx \&in Op Ar width
+.D1 Pf . Ic in Op Ar width
 .Pp
 If
 .Ar width
 is signed, the new offset is relative.
 Otherwise, it is absolute.
 This value is reset upon the next paragraph, section, or sub-section.
+.El
 .Sh MACRO SYNTAX
 The
 .Nm
@@ -492,7 +479,7 @@ foo
 .Ed
 .Pp
 is equivalent to
-.Sq \&.I foo .
+.Sq .I foo .
 If next-line macros are invoked consecutively, only the last is used.
 If a next-line macro is followed by a non-next-line macro, an error is
 raised.
@@ -504,25 +491,25 @@ The syntax is as follows:
 .Ed
 .Bl -column "MacroX" "ArgumentsX" "ScopeXXXXX" "CompatX" -offset indent
 .It Em Macro Ta Em Arguments Ta Em Scope     Ta Em Notes
-.It Sx \&AT  Ta    <=1       Ta    current   Ta    \&
-.It Sx \&B   Ta    n         Ta    next-line Ta    \&
-.It Sx \&BI  Ta    n         Ta    current   Ta    \&
-.It Sx \&BR  Ta    n         Ta    current   Ta    \&
-.It Sx \&DT  Ta    0         Ta    current   Ta    \&
-.It Sx \&EE  Ta    0         Ta    current   Ta    GNU
-.It Sx \&EX  Ta    0         Ta    current   Ta    GNU
-.It Sx \&I   Ta    n         Ta    next-line Ta    \&
-.It Sx \&IB  Ta    n         Ta    current   Ta    \&
-.It Sx \&IR  Ta    n         Ta    current   Ta    \&
-.It Sx \&OP  Ta    >=1       Ta    current   Ta    GNU
-.It Sx \&PD  Ta    1         Ta    current   Ta    \&
-.It Sx \&RB  Ta    n         Ta    current   Ta    \&
-.It Sx \&RI  Ta    n         Ta    current   Ta    \&
-.It Sx \&SB  Ta    n         Ta    next-line Ta    \&
-.It Sx \&SM  Ta    n         Ta    next-line Ta    \&
-.It Sx \&TH  Ta    >1, <6    Ta    current   Ta    \&
-.It Sx \&UC  Ta    <=1       Ta    current   Ta    \&
-.It Sx \&in  Ta    1         Ta    current   Ta    Xr roff 7
+.It Ic AT  Ta    <=1       Ta    current   Ta    \&
+.It Ic B   Ta    n         Ta    next-line Ta    \&
+.It Ic BI  Ta    n         Ta    current   Ta    \&
+.It Ic BR  Ta    n         Ta    current   Ta    \&
+.It Ic DT  Ta    0         Ta    current   Ta    \&
+.It Ic EE  Ta    0         Ta    current   Ta    GNU
+.It Ic EX  Ta    0         Ta    current   Ta    GNU
+.It Ic I   Ta    n         Ta    next-line Ta    \&
+.It Ic IB  Ta    n         Ta    current   Ta    \&
+.It Ic IR  Ta    n         Ta    current   Ta    \&
+.It Ic OP  Ta    >=1       Ta    current   Ta    GNU
+.It Ic PD  Ta    1         Ta    current   Ta    \&
+.It Ic RB  Ta    n         Ta    current   Ta    \&
+.It Ic RI  Ta    n         Ta    current   Ta    \&
+.It Ic SB  Ta    n         Ta    next-line Ta    \&
+.It Ic SM  Ta    n         Ta    next-line Ta    \&
+.It Ic TH  Ta    >1, <6    Ta    current   Ta    \&
+.It Ic UC  Ta    <=1       Ta    current   Ta    \&
+.It Ic in  Ta    1         Ta    current   Ta    Xr roff 7
 .El
 .Ss Block Macros
 Block macros comprise a head and body.
@@ -540,19 +527,19 @@ The syntax is as follows:
 .Pp
 The closure of body scope may be to the section, where a macro is closed
 by
-.Sx \&SH ;
+.Ic SH ;
 sub-section, closed by a section or
-.Sx \&SS ;
+.Ic SS ;
 or paragraph, closed by a section, sub-section,
-.Sx \&HP ,
-.Sx \&IP ,
-.Sx \&LP ,
-.Sx \&P ,
-.Sx \&PP ,
-.Sx \&RE ,
-.Sx \&SY ,
+.Ic HP ,
+.Ic IP ,
+.Ic LP ,
+.Ic P ,
+.Ic PP ,
+.Ic RE ,
+.Ic SY ,
 or
-.Sx \&TP .
+.Ic TP .
 No closure refers to an explicit block closing macro.
 .Pp
 As a rule, block macros may not be nested; thus, calling a block macro
@@ -560,23 +547,23 @@ while another block macro scope is open, and the open scope is not
 implicitly closed, is syntactically incorrect.
 .Bl -column "MacroX" "ArgumentsX" "Head ScopeX" "sub-sectionX" "compatX" -offset indent
 .It Em Macro Ta Em Arguments Ta Em Head Scope Ta Em Body Scope  Ta Em Notes
-.It Sx \&HP  Ta    <2        Ta    current    Ta    paragraph   Ta    \&
-.It Sx \&IP  Ta    <3        Ta    current    Ta    paragraph   Ta    \&
-.It Sx \&LP  Ta    0         Ta    current    Ta    paragraph   Ta    \&
-.It Sx \&ME  Ta    0         Ta    none       Ta    none        Ta    GNU
-.It Sx \&MT  Ta    1         Ta    current    Ta    to \&ME     Ta    GNU
-.It Sx \&P   Ta    0         Ta    current    Ta    paragraph   Ta    \&
-.It Sx \&PP  Ta    0         Ta    current    Ta    paragraph   Ta    \&
-.It Sx \&RE  Ta    <=1       Ta    current    Ta    none        Ta    \&
-.It Sx \&RS  Ta    1         Ta    current    Ta    to \&RE     Ta    \&
-.It Sx \&SH  Ta    >0        Ta    next-line  Ta    section     Ta    \&
-.It Sx \&SS  Ta    >0        Ta    next-line  Ta    sub-section Ta    \&
-.It Sx \&SY  Ta    1         Ta    current    Ta    to \&YS     Ta    GNU
-.It Sx \&TP  Ta    n         Ta    next-line  Ta    paragraph   Ta    \&
-.It Sx \&TQ  Ta    n         Ta    next-line  Ta    paragraph   Ta    GNU
-.It Sx \&UE  Ta    0         Ta    current    Ta    none        Ta    GNU
-.It Sx \&UR  Ta    1         Ta    current    Ta    part        Ta    GNU
-.It Sx \&YS  Ta    0         Ta    none       Ta    none        Ta    GNU
+.It Ic HP  Ta    <2        Ta    current    Ta    paragraph   Ta    \&
+.It Ic IP  Ta    <3        Ta    current    Ta    paragraph   Ta    \&
+.It Ic LP  Ta    0         Ta    current    Ta    paragraph   Ta    \&
+.It Ic ME  Ta    0         Ta    none       Ta    none        Ta    GNU
+.It Ic MT  Ta    1         Ta    current    Ta    to \&ME     Ta    GNU
+.It Ic P   Ta    0         Ta    current    Ta    paragraph   Ta    \&
+.It Ic PP  Ta    0         Ta    current    Ta    paragraph   Ta    \&
+.It Ic RE  Ta    <=1       Ta    current    Ta    none        Ta    \&
+.It Ic RS  Ta    1         Ta    current    Ta    to \&RE     Ta    \&
+.It Ic SH  Ta    >0        Ta    next-line  Ta    section     Ta    \&
+.It Ic SS  Ta    >0        Ta    next-line  Ta    sub-section Ta    \&
+.It Ic SY  Ta    1         Ta    current    Ta    to \&YS     Ta    GNU
+.It Ic TP  Ta    n         Ta    next-line  Ta    paragraph   Ta    \&
+.It Ic TQ  Ta    n         Ta    next-line  Ta    paragraph   Ta    GNU
+.It Ic UE  Ta    0         Ta    current    Ta    none        Ta    GNU
+.It Ic UR  Ta    1         Ta    current    Ta    part        Ta    GNU
+.It Ic YS  Ta    0         Ta    none       Ta    none        Ta    GNU
 .El
 .Pp
 If a block macro is next-line scoped, it may only be followed by in-line
@@ -594,7 +581,7 @@ In text lines, the effect of manual font selection by escape sequences
 only lasts until the next macro invocation; in macro lines, it only lasts
 until the end of the macro scope.
 Note that macros like
-.Sx \&BR
+.Ic BR
 open and close a font scope for each argument.
 .Sh SEE ALSO
 .Xr man 1 ,