[groff] 02/09: *.man: Regularize (sub)section cross references.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit a1b2ed16b3f8df2f3900365284a7d67003aca651
Author: G. Branden Robinson <address@hidden>
Date:   Fri Dec 14 09:37:24 2018 -0500

    *.man: Regularize (sub)section cross references.
    
    contrib/gdiffmk/gdiffmk.1.man:
    contrib/groffer/groffer.1.man:
    contrib/mm/groff_mm.7.man:
    contrib/pdfmark/pdfroff.1.man:
    man/groff.7.man:
    man/groff_diff.7.man:
    man/groff_out.5.man:
    man/groff_tmac.5.man:
    man/roff.7.man:
    src/devices/grolbp/grolbp.1.man:
    src/devices/gropdf/gropdf.1.man:
    src/devices/grops/grops.1.man:
    src/preproc/eqn/eqn.1.man:
    src/preproc/refer/refer.1.man:
    src/roff/troff/troff.1.man:
    tmac/groff_ms.7.man:
    + Quote (sub)section names instead of setting them in bold or italics.
    
    contrib/mm/groff_mm.7.man:
    contrib/pdfmark/pdfroff.1.man:
    man/groff.7.man:
    man/groff_out.5.man:
    man/groff_tmac.5.man:
    man/roff.7.man:
    src/devices/grolbp/grolbp.1.man:
    src/devices/gropdf/gropdf.1.man:
    src/devices/grops/grops.1.man:
    src/preproc/eqn/eqn.1.man:
    src/preproc/refer/refer.1.man:
    + When cross referencing a local (sub)section, add direction of
      reference ("above" vs. "below").
    
    contrib/mm/groff_mm.7.man:
    contrib/pdfmark/pdfroff.1.man:
    man/groff.7.man:
    man/groff_diff.7.man:
    man/groff_out.5.man:
    man/groff_tmac.5.man:
    man/roff.7.man:
    src/devices/grolbp/grolbp.1.man:
    src/devices/gropdf/gropdf.1.man:
    src/devices/grops/grops.1.man:
    src/preproc/eqn/eqn.1.man:
    src/roff/troff/troff.1.man:
    tmac/groff_man.7.man:
    + Stop setting (sub)section names in all caps.  That is a presentational
      matter better decided in the implementation of the .SH and .SS macros.
    
    contrib/groffer/groffer.1.man:
    + Fix comma splice.
    + Fix incorrect (or outdated) section name reference to X(7).
    
    contrib/mm/groff_mm.7.man:
    + "See also" is a good section title, but in prose, "also see" is more
      idiomatic.
    
    man/groff_char.7.man:
    + "{next,previous} section" get a definite article.
    
    man/groff_diff.7.man:
    src/devices/grolbp/grolbp.1.man:
    tmac/groff_man.7.man:
    + (Sub)section $IDENTIFIER by contrast does _not_ require a definite
      article.
    
    man/groff_out.5.man:
    + Fix incorrect reference (named section is actually a subsection).
    
    man/groff_tmac.5.man:
    + Fix non-idiomatic English "some" -> "a".  My favorite example of this
      is an old Debian package description of a Moon Patrol clone:
        "drive some car across the moon"
      ...which carries a pointed tone of contempt or ambivalence to a
      native speaker.
    
    src/devices/gropdf/gropdf.1.man:
    src/devices/grops/grops.1.man:
    + There is no need to identify the destination of a cross reference as a
      man page if it's formatted as only man page references are ("foo(1)").
    
    Signed-off-by: G. Branden Robinson <address@hidden>
---
 contrib/gdiffmk/gdiffmk.1.man   |  4 +---
 contrib/groffer/groffer.1.man   | 14 ++++++--------
 contrib/mm/groff_mm.7.man       |  6 ++----
 contrib/pdfmark/pdfroff.1.man   |  8 +++-----
 man/groff.7.man                 | 11 ++++++-----
 man/groff_char.7.man            |  2 +-
 man/groff_diff.7.man            |  8 ++------
 man/groff_out.5.man             | 22 ++++++++++------------
 man/groff_tmac.5.man            |  5 +++--
 man/roff.7.man                  |  7 +++----
 src/devices/grolbp/grolbp.1.man |  4 ++--
 src/devices/gropdf/gropdf.1.man | 11 ++++-------
 src/devices/grops/grops.1.man   | 11 ++++-------
 src/preproc/eqn/eqn.1.man       |  8 ++------
 src/preproc/refer/refer.1.man   | 15 ++++++---------
 src/roff/troff/troff.1.man      |  4 +---
 tmac/groff_man.7.man            | 18 +++++++-----------
 tmac/groff_ms.7.man             |  4 +---
 18 files changed, 64 insertions(+), 98 deletions(-)

diff --git a/contrib/gdiffmk/gdiffmk.1.man b/contrib/gdiffmk/gdiffmk.1.man
index 26532f0..1e20d47 100644
--- a/contrib/gdiffmk/gdiffmk.1.man
+++ b/contrib/gdiffmk/gdiffmk.1.man
@@ -102,9 +102,7 @@ Clearly both cannot be
 Note that the output is not necessarily compatible with all macro packages
 and all preprocessors.
 .
-See the
-.B BUGS
-section below.
+See section \(lqBugs\(rq below.
 .
 .
 .\" ====================================================================
diff --git a/contrib/groffer/groffer.1.man b/contrib/groffer/groffer.1.man
index e0457ce..5eec6bf 100644
--- a/contrib/groffer/groffer.1.man
+++ b/contrib/groffer/groffer.1.man
@@ -1554,10 +1554,10 @@ window.
 .TP
 .BI \-\-display \ X-display
 Set the X Window System display on which the viewer program
-shall be started, see
-.BR X (7),
-section
-.IR "Display Names" ,
+shall be started.
+.
+See section \(lqDisplay Names\(rq in
+.BR X (7)
 for the syntax of the argument.
 .
 .
@@ -1596,10 +1596,8 @@ This is equivalent to
 Set the geometry of the display window, that means its size and its
 starting position.
 .
-See
-.BR \%X (7),
-section
-.IR "Geometry Management" ,
+See section \(lqGeometry Specifications\(rq in
+.BR X (7)
 for the syntax of the argument.
 .
 .
diff --git a/contrib/mm/groff_mm.7.man b/contrib/mm/groff_mm.7.man
index 3ecf8f0..a95790c 100644
--- a/contrib/mm/groff_mm.7.man
+++ b/contrib/mm/groff_mm.7.man
@@ -1997,8 +1997,7 @@ See also
 Format a letter in one of four different styles depending
 on the argument.
 .
-See also section
-.BR INTERNALS .
+Also see section \[lq]Internals\[rq] below.
 .
 .RS
 .IP
@@ -2678,8 +2677,7 @@ otherwise at the last.
 No reference data is printed if the author(s) is specified through
 .BR .WA / .WE .
 .
-See section
-.BR INTERNALS .
+See section \[lq]Internals\[rq] below.
 .
 .TP
 .BI SK\  \fR[\fPpages\fR]\fP
diff --git a/contrib/pdfmark/pdfroff.1.man b/contrib/pdfmark/pdfroff.1.man
index 5cf3144..b5fc5aa 100644
--- a/contrib/pdfmark/pdfroff.1.man
+++ b/contrib/pdfmark/pdfroff.1.man
@@ -305,9 +305,8 @@ has completed PDF document formatting; this may be useful, 
when
 debugging formatting problems.
 .
 .IP
-See section
-.BR FILES ,
-for a description of the temporary files used by
+See section \[lq]Files\[rq] below for a description of the temporary
+files used by
 .BR pdfroff .
 .
 .TP
@@ -665,8 +664,7 @@ Temporary files, created by
 .BR pdfroff ,
 are placed in the file system hierarchy,
 in or below the directory specified by environment variables
-(see section
-.BR ENVIRONMENT ).
+(see section \[lq]Environment\[rq] above).
 .
 If
 .BR mktemp (@MAN1EXT@)
diff --git a/man/groff.7.man b/man/groff.7.man
index b61ee51..c21b1a2 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -2962,8 +2962,7 @@ End conditional input.
 .ESC ( sc
 A glyph with two-character name
 .IR sc ;
-see section
-.BR "Special Characters" .
+see section \[lq]Special Characters\[rq] below.
 .
 .TP
 .ESC[] "" name
@@ -3705,9 +3704,11 @@ command-line option.
 .\" ====================================================================
 .
 Registers are variables that store a value.
-In groff, most registers store numerical values (see section
-.B NUMERICAL EXPRESSIONS
-above), but some can also hold a string value.
+.
+In groff,
+most registers store numerical values
+(see section \[lq]Numerical Expressions\[rq] above),
+but some can also hold a string value.
 .
 .
 .P
diff --git a/man/groff_char.7.man b/man/groff_char.7.man
index 8bd0a5e..6ce5968 100644
--- a/man/groff_char.7.man
+++ b/man/groff_char.7.man
@@ -369,7 +369,7 @@ are printable characters that print as themselves.
 .
 Although they can be specified directly with the keyboard on systems
 with a \%latin1 code page, it is better to use their glyph names;
-see next section.
+see the next section.
 .
 .P
 .na
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index 49b8d84..5d93684 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -73,9 +73,7 @@ format (troff output).
 .
 .
 .P
-The section
-.I SEE ALSO
-gives pointers to both the classical
+Section \[lq]See Also\[rq] below gives pointers to both the classical
 .I roff
 and the modern
 .I groff
@@ -2543,9 +2541,7 @@ is read in copy mode.
 .BR \[rs]D' \*[ellipsis] '
 All drawing commands of groff's intermediate output are accepted.
 .
-See subsection
-.B "Drawing Commands"
-below for more information.
+See subsection \[lq]Drawing Commands\[rq] below.
 .
 .
 .\" ====================================================================
diff --git a/man/groff_out.5.man b/man/groff_out.5.man
index f014de2..4f0efaf 100644
--- a/man/groff_out.5.man
+++ b/man/groff_out.5.man
@@ -406,8 +406,8 @@ is guaranteed to consist of the following three lines (in 
that order):
 .B x init
 .RE
 .P
-with the arguments set as outlined in the section
-.BR "Device Control Commands" .
+with the arguments set as outlined in subsection \[lq]Device Control
+Commands\[rq] below.
 .
 However, the parser for the
 .I intermediate output
@@ -729,8 +729,8 @@ used the unit
 .I points
 (\c
 .BR p )
-instead; see section
-.BR COMPATIBILITY .
+instead;
+see section \[lq]Compatibility\[rq] below.
 .
 .
 .TP
@@ -901,8 +901,7 @@ In the following command reference, the syntax element
 .I \[la]line-break\[ra]
 means a
 .I syntactical line break
-as defined in section
-.BR Separation .
+as defined in subsection \[lq]Separation\[rq] above.
 .
 .
 .TP
@@ -1229,8 +1228,7 @@ In the following, the syntax element
 .I \[la]line-break\[ra]
 means a
 .I syntactical line break
-as defined in section
-.BR Separation .
+as defined in subsection \[lq]Separation\[rq] above.
 .
 .TP
 .x-command F name
@@ -1273,8 +1271,8 @@ Set character height to\~\c
 .I Classical troff
 used the unit points (\c
 .BR p )
-instead; see section
-.BR COMPATIBILITY .
+instead;
+see section \[lq]Compatibility\[rq] below.
 .
 .
 .TP
@@ -1504,8 +1502,8 @@ So a
 .I groff
 postprocessor must only redefine the methods of this class.
 .
-For details, see the reference in section
-.BR FILES .
+For details,
+see the reference in section \[lq]Files\[rq] below.
 .
 .
 .\" ====================================================================
diff --git a/man/groff_tmac.5.man b/man/groff_tmac.5.man
index 7a3d793..29b25b6 100644
--- a/man/groff_tmac.5.man
+++ b/man/groff_tmac.5.man
@@ -806,8 +806,9 @@ to invoke
 .P
 If you want to write your own groff macro file, call it
 .IB whatever .tmac
-and put it in some directory of the tmac path, see section
-.BR FILES .
+and put it in a directory in the tmac path;
+see section \[lq]Files\[rq] below.
+.
 Then documents can include it with the
 .B .mso
 request or the option
diff --git a/man/roff.7.man b/man/roff.7.man
index d240d15..deff211 100644
--- a/man/roff.7.man
+++ b/man/roff.7.man
@@ -85,8 +85,7 @@ many extensions.
 .P
 The ancestry of
 .I roff
-is described in section
-.BR HISTORY .
+is described in section \[lq]History\[rq] below.
 .
 In this document, the term
 .I roff
@@ -331,8 +330,8 @@ output format, and the postprocessor system.
 .
 This completed the structure of a
 .I "roff system"
-as it is still in use today; see section
-.BR "USING ROFF" .
+as it is still in use today;
+see section \[lq]Using Roff\[rq] below.
 .
 In 1979, these novelties were described in the paper
 [CSTR\~#97].
diff --git a/src/devices/grolbp/grolbp.1.man b/src/devices/grolbp/grolbp.1.man
index d532d6c..684f6cc 100644
--- a/src/devices/grolbp/grolbp.1.man
+++ b/src/devices/grolbp/grolbp.1.man
@@ -166,8 +166,8 @@ orientation, which must be \(oqportrait\(cq or 
\(oqlandscape\(cq.
 .BI \-\-papersize= paper-size
 Set the paper size to
 .IR paper-size ,
-which must be a valid paper size description as indicated in the section
-.BR "PAPER SIZES" .
+which must be a valid paper size description as indicated in section
+\[lq]Paper Sizes\[rq], below.
 .
 .
 .TP
diff --git a/src/devices/gropdf/gropdf.1.man b/src/devices/gropdf/gropdf.1.man
index d6d98db..eb7458c 100644
--- a/src/devices/gropdf/gropdf.1.man
+++ b/src/devices/gropdf/gropdf.1.man
@@ -99,9 +99,8 @@ option.
 .
 .
 .LP
-See section
-.B FONT INSTALLATION
-below for a guide how to install fonts for
+See section \[lq]Font Installation\[rq] below for a guide how to install
+fonts for
 .BR gropdf .
 .
 .
@@ -1208,11 +1207,9 @@ and
 Install both the groff font description files and the fonts in a
 \[oq]devpdf\[cq] subdirectory of the font path which groff finds.
 .
-See the
-.B ENVIRONMENT
-section in the
+See section \[lq]Environment\[rq] in
 .BR @address@hidden (@MAN1EXT@)
-man page which lists the actual value of the font path.
+for the actual value of the font path.
 .
 Note that groff doesn't use the AFM files (but it is a good idea to
 store them anyway).
diff --git a/src/devices/grops/grops.1.man b/src/devices/grops/grops.1.man
index e7b9c48..2d47da8 100644
--- a/src/devices/grops/grops.1.man
+++ b/src/devices/grops/grops.1.man
@@ -104,9 +104,8 @@ arguments.
 To print such concatenated output it is necessary to deactivate DSC
 handling in the printing program or previewer.
 .
-See section
-.B FONT INSTALLATION
-below for a guide how to install fonts for
+See section \[lq]Font Installation\[rq] below for a guide how to install
+fonts for
 .BR grops .
 .
 .
@@ -1314,11 +1313,9 @@ and
 Install both the groff font description files and the fonts in a
 \[oq]devps\[cq] subdirectory of the font path which groff finds.
 .
-See the
-.B ENVIRONMENT
-section in the
+See section \[lq]Environment\[rq] in
 .BR troff (@MAN1EXT@)
-man page which lists the actual value of the font path.
+for the actual value of the font path.
 .
 Note that groff doesn't use the AFM files (but it is a good idea
 to store them anyway).
diff --git a/src/preproc/eqn/eqn.1.man b/src/preproc/eqn/eqn.1.man
index c0cc4d6..bb6b6e4 100644
--- a/src/preproc/eqn/eqn.1.man
+++ b/src/preproc/eqn/eqn.1.man
@@ -389,9 +389,7 @@ in these cases
 .B chartype
 changes the font type of the characters.
 .
-See the
-.B Fonts
-subsection.
+See subsection \[lq]Fonts\[rq] below.
 .
 .
 .\" ====================================================================
@@ -1324,9 +1322,7 @@ boundaries.
 .
 .
 .LP
-See the
-.B BUGS
-section for translation limits specific to
+See section \[lq]Bugs\[rq] below for translation limits specific to
 .BR eqn .
 .
 .
diff --git a/src/preproc/refer/refer.1.man b/src/preproc/refer/refer.1.man
index 8d97daf..170e3cc 100644
--- a/src/preproc/refer/refer.1.man
+++ b/src/preproc/refer/refer.1.man
@@ -189,9 +189,8 @@ Whitespace is permitted between a command-line option and 
its argument.
 .
 .LP
 Most options are equivalent to commands
-(for a description of these commands see the
-.B Commands
-subsection):
+(for a description of these commands,
+see subsection \(lqCommands\(rq below).
 .
 .
 .nr a \n(.j
@@ -1031,9 +1030,8 @@ is a label expression that specifies a string with which 
to replace the
 .B D
 field after constructing the label.
 .
-See the
-.B "Label expressions"
-subsection for a description of label expressions.
+See subsection \(lqLabel expressions\(rq below for a description of
+label expressions.
 .
 This command is useful if you do not want explicit labels in the
 reference list,
@@ -1298,9 +1296,8 @@ Also
 can be used to indicate the references should be sorted using the
 (tentative) label.
 .
-(The
-.B "Label expressions"
-subsection describes the concept of a tentative label.)
+(Subsection \(lqLabel expressions\(rq below describes the concept of a
+tentative label.)
 .
 .
 .TP
diff --git a/src/roff/troff/troff.1.man b/src/roff/troff/troff.1.man
index 2755c77..8f53c10 100644
--- a/src/roff/troff/troff.1.man
+++ b/src/roff/troff/troff.1.man
@@ -279,9 +279,7 @@ Print the version number.
 Enable warning
 .IR  name .
 .
-Available warnings are described in the section
-.I WARNINGS
-below.
+Available warnings are described in section \(lqWarnings\(rq below.
 .
 To enable most useful warnings use
 .B \-w
diff --git a/tmac/groff_man.7.man b/tmac/groff_man.7.man
index eb5209d..ef5f9f5 100644
--- a/tmac/groff_man.7.man
+++ b/tmac/groff_man.7.man
@@ -408,8 +408,7 @@ Move the left margin to the right by the value
 .IR indent ,
 if specified,
 and by a default amount otherwise;
-see subsection \(lqHorizontal and vertical spacing\(rq,
-below.
+see subsection \(lqHorizontal and vertical spacing\(rq below.
 .
 Calls to
 .B .RS
@@ -473,8 +472,7 @@ followed by a vertical space downward by a default amount
 macro).
 .
 The font size and style are reset to defaults;
-see subsection \(lqFont style macros\(rq,
-below.
+see subsection \(lqFont style macros\(rq below.
 .
 Finally, the left margin and indentation are reset to default values.
 .
@@ -493,8 +491,7 @@ Subsequent text is indented by
 .IR indent ,
 if specified,
 and by a default amount otherwise;
-see subsection \(lqHorizontal and vertical spacing\(rq,
-below.
+see subsection \(lqHorizontal and vertical spacing\(rq below.
 .
 .
 .IP
@@ -1210,8 +1207,7 @@ see the
 \(oq\e(oq\(cq,
 and
 \(oq\e(cq\(cq
-escapes in the subsection \(lqPortability\(rq,
-below.
+escapes in subsection \(lqPortability\(rq below.
 .
 .
 .\" END USAGE (TODO: move to tutorial/style guide when we have it)
@@ -1368,7 +1364,7 @@ that is,
 the width of a letter \(lqn\(rq in the font current when the macro is
 called.
 .
-See section \(lqNUMERICAL EXPRESSIONS\(rq in
+See section \(lqNumerical Expressions\(rq in
 .IR groff (7)
 for further details.
 .
@@ -1486,7 +1482,7 @@ also cause a break but no insertion of vertical space.
 .SS "Number registers"
 .\" ====================================================================
 .
-Number registers are described in section \(lqOPTIONS\(rq, below.
+Number registers are described in section \(lqOptions\(rq below.
 .
 .
 .\" ====================================================================
@@ -2228,7 +2224,7 @@ Set hyphenation flags.
 .
 Permissible values of
 .I flags
-are documented in section \(lqHYPHENATION\(rq of
+are documented in section \(lqHyphenation\(rq of
 .IR groff (7).
 .
 The default is\~4 if continuous rendering is enabled
diff --git a/tmac/groff_ms.7.man b/tmac/groff_ms.7.man
index c3c6280..ca71280 100644
--- a/tmac/groff_ms.7.man
+++ b/tmac/groff_ms.7.man
@@ -456,9 +456,7 @@ the first line of the paragraph is printed.
 .PP
 Similarly,
 when a section heading
-(see subsection
-.I Headings
-below)
+(see subsection \[lq]Headings\[rq] below)
 precedes any of these paragraph types,
 the
 .B HORPHANS