commit 19ded9d2f693b534a5796b1e0f325a6030a6c012 Author: G. Branden Robinson Date: Fri Nov 30 23:12:51 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)"). diff --git a/contrib/gdiffmk/gdiffmk.1.man b/contrib/gdiffmk/gdiffmk.1.man index 26532f0f..1e20d473 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 e0457ce4..5eec6bf2 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 3ecf8f09..a95790cb 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 5cf31442..b5fc5aa5 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 b61ee513..c21b1a21 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 8bd0a5e3..6ce59681 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 49b8d848..5d93684f 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 f014de24..4f0efaf9 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 7a3d793b..29b25b6f 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 d240d152..deff211c 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 d532d6c9..684f6ccb 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 d6d98db5..eb7458c1 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 e7b9c48d..2d47da86 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 c0cc4d63..bb6b6e4a 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 8d97daf9..170e3cc4 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 2755c77d..8f53c103 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 eb5209d6..ef5f9f57 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 c3c6280f..ca71280f 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