[groff] 12/34: [ms]: Exercise terminological discipline in docs.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 2e81da5aa6f8414fa0f7568a89899976348f9aef
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Tue Aug 24 12:22:28 2021 +1000

    [ms]: Exercise terminological discipline in docs.
    
    * "using" macros -> "calling" macros
    * "use" request -> "invoke" request
    * "escape(s)" -> "escape sequence(s)"
    * Clarify that it is only text lines _immediately_ after heading macro
      calls that are treated as part of the heading.
---
 doc/groff.texi      | 24 ++++++++++++------------
 doc/ms.ms           | 29 +++++++++++++++--------------
 tmac/groff_ms.7.man | 13 +++++++------
 3 files changed, 34 insertions(+), 32 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index b2935a7..170390d 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -424,7 +424,7 @@ developing GNU and promoting software freedom.''
 @title groff
 @subtitle The GNU implementation of @code{troff}
 @subtitle Edition 1.23.0
-@subtitle July 2021
+@subtitle August 2021
 @author by Trent A.@tie{}Fisher
 @author and Werner Lemberg
 
@@ -2970,7 +2970,7 @@ headers and footers collectively.}  As their level of 
sophistication (or
 complexity) increases, they tend to acquire dates of revision,
 explicitly identified authors, sponsoring institutions for authors, and,
 at the rarefied heights, an abstract of their content.  Define these
-data by using the macros below in the order shown; @code{DA} or
+data by calling the macros below in the order shown; @code{DA} or
 @code{ND} can be called to set the document date (or other identifier)
 at any time before (a) the abstract, if present, or (b) its information
 is required in a header or footer.  Use of these macros is optional,
@@ -3194,8 +3194,8 @@ Use headings to create a sequential or hierarchical 
structure for your
 document.  The @file{ms} macros print headings in @strong{bold} using
 the same font family and, by default, point size as the body text.
 Headings are available with and without automatic numbering.  Text lines
-after heading macros are treated as part of the heading, rendered on the
-same output line in the same style.
+immediately after heading macro calls are treated as part of the
+heading, rendered on the same output line in the same style.
 
 @DefmacList {NH, @Var{level}, ms}
 @DefmacListEnd {NH, @t{S} @Var{heading-level-index} @dots{}, ms}
@@ -3376,8 +3376,8 @@ otherwise.  This is a Version@tie{}10 Research Unix 
extension.
 @Defmac {BX, [@Var{txt}], ms}
 Prints @var{txt} and draws a box around it.  On terminal devices,
 reverse video is used instead.  If you want the argument to contain
-space, use non-breaking space escapes of appropriate width (@code{\~},
-@code{\^}, @code{\|}, @code{\0}) or @code{\h}.
+space, use non-breaking space escape sequences of appropriate width
+(@code{\~}, @code{\^}, @code{\|}, @code{\0}) or @code{\h}.
 @endDefmac
 
 @Defmac {UL, [@Var{txt} [@Var{post}]], ms}
@@ -3536,7 +3536,7 @@ Firearms,
 @endCartoucheExample
 
 Second, you could apply the @code{\p} escape sequence to force a break.
-The space following the escape is important; if you omit it,
+The space following the escape sequence is important; if you omit it,
 @code{groff} prints the first word of the paragraph text on the same
 line as the term or label (if it fits) @emph{then} breaks the line.
 
@@ -3546,7 +3546,7 @@ line as the term or label (if it fits) @emph{then} breaks 
the line.
 @endCartoucheExample
 
 Finally, you may append unbreakable horizontal space to the term or
-label with the @code{\h} escape; using the same amount as the
+label with the @code{\h} escape sequence; using the same amount as the
 indentation will ensure that it's too wide for @code{groff} to treat it
 as ``fitting'' on the same line as the paragraph text.
 
@@ -4152,8 +4152,8 @@ is @samp{References}.
 
 @Defstr {ABSTRACT, ms}
 Contains the string printed at the beginning of the abstract.  The
-default is @samp{\f[I]ABSTRACT\f[]}; it includes font style escapes to
-set the word in italics.
+default is @samp{\f[I]ABSTRACT\f[]}; it includes font style escape
+sequences to set the word in italics.
 @endDefstr
 
 @Defstr {TOC, ms}
@@ -4383,8 +4383,8 @@ numbering sequence.
 @item
 @code{groff} @file{ms} supports the @code{PN} register, but it is not
 necessary; you can access the page number via the usual @code{%}
-register and use the @code{af} request to assign a different format to
-it if desired.@footnote{If you redefine the @file{ms} @code{PT} macro
+register and invoke the @code{af} request to assign a different format
+to it if desired.@footnote{If you redefine the @file{ms} @code{PT} macro
 @c I wouldn't mention that, but Lesk 1978 encourages doing so.  :-/
 and desire special treatment of certain page numbers (like @samp{1}),
 you may need to handle a non-Arabic page number format, as @code{groff}
diff --git a/doc/ms.ms b/doc/ms.ms
index 4a8abca..7e1f173 100644
--- a/doc/ms.ms
+++ b/doc/ms.ms
@@ -21,8 +21,8 @@
 .ds FR 1
 .ie t .nr PI 3.5n
 .el   .nr PI 4n
-.ND July 2021
-.EH '%''July 2021'
+.ND August 2021
+.EH '%''August 2021'
 .EF ''''
 .OH 'Using \f[I]groff\f[] with the \f[I]ms\f[] macros''%'
 .OF ''''
@@ -443,7 +443,7 @@ and,
 at the rarefied heights,
 an abstract of their content.
 .
-Define these data by using the macros below in the order shown;
+Define these data by calling the macros below in the order shown;
 .CW .DA
 or
 .CW .ND
@@ -891,7 +891,8 @@ point size as the body text.
 .
 Headings are available with and without automatic numbering.
 .
-Text lines after heading macros are treated as part of the heading,
+Text lines immediately after heading macro calls are treated as part of
+the heading,
 rendered on the same output line in the same style.
 .
 .
@@ -1311,7 +1312,7 @@ reverse video is used instead
 (see the implementation note below).
 .
 If you want the argument to contain space,
-use non-breaking space escapes of appropriate width
+use non-breaking space escape sequences of appropriate width
 .CW \[rs]\[ti] , (
 .CW \[rs]\[ha] ,
 .CW \[rs]| ,
@@ -1444,11 +1445,11 @@ the
 .CW BX
 macro \[lq]boxes\[rq] its argument by bracketing it with
 .I groff
-extension escapes to set the foreground color to black and the
+extension escape sequences to set the foreground color to black and the
 background to white and then reset them to their previous values;
 the terminal output driver,
 .I grotty (1),
-converts these to ISO\~6429 color escapes,
+converts these to ISO\~6429 color escape sequences,
 which may be ignored or mishandled by some terminals,
 or may be disabled by
 .I grotty 's
@@ -1465,9 +1466,9 @@ Surmounting these challenges would require adding 
features to
 for instance to provide a mechanism to request ISO\~6429's
 \[lq]standout\[rq] mode \" That's "smso" and "rmso" in terminfo.
 (often supported on monochrome terminals),
-or to replace the presumed support of the terminal for ISO\~6429 escapes
-with the use of a library that can query the capabilities of the
-terminal and adapt the output sent to the device accordingly.
+or to replace the presumed support of the terminal for ISO\~6429 escape
+sequences with the use of a library that can query the capabilities of
+the terminal and adapt the output sent to the device accordingly.
 .
 (Practically,
 this likely means adding a dependency on
@@ -1600,7 +1601,7 @@ you could apply the
 .CW \[rs]p
 escape sequence to force a break.
 .
-The space following the escape is important;
+The space following the escape sequence is important;
 if you omit it,
 .I groff
 prints the first word of the paragraph text on the same line as the term
@@ -1613,7 +1614,7 @@ Finally,
 you may append unbreakable horizontal space to the term or label with
 the
 .CW \[rs]h
-escape;
+escape sequence;
 using the same amount as the indentation will ensure that it's too wide
 for
 .I groff
@@ -2925,7 +2926,7 @@ register,
 but it is not necessary;
 you can access the page number via the usual
 .CW %
-register and use the
+register and invoke the
 .CW af
 request to assign a different format to it if desired.\**
 .FS
@@ -3122,7 +3123,7 @@ _
 .PP
 The default for
 .CW \[rs]*[ABSTRACT]
-includes font style escapes to set the word in italics.
+includes font style escape sequences to set the word in italics.
 .
 .
 .\" ------------------------
diff --git a/tmac/groff_ms.7.man b/tmac/groff_ms.7.man
index abad739..2dcb21c 100644
--- a/tmac/groff_ms.7.man
+++ b/tmac/groff_ms.7.man
@@ -377,8 +377,8 @@ is preferable.
 .SS "Document description macros"
 .\" ====================================================================
 .
-Define information describing the document by using the macros below in
-the order shown;
+Define information describing the document by calling the macros below
+in the order shown;
 .B .DA
 or
 .B .ND
@@ -699,7 +699,8 @@ point size as the body text.
 .
 Headings are available with and without automatic numbering.
 .
-Text lines after heading macros are treated as part of the heading,
+Text lines immediately after heading macro calls are treated as part of
+the heading,
 rendered on the same output line in the same style.
 .
 .
@@ -983,7 +984,7 @@ On terminal devices,
 reverse video is used instead.
 .
 If you want the argument to contain space,
-use non-breaking space escapes of appropriate width
+use non-breaking space escape sequences of appropriate width
 .RB ( \[rs]\[ti] ,
 .BR \[rs]\[ha] ,
 .BR \[rs]| ,
@@ -1979,7 +1980,7 @@ register,
 but it is not necessary;
 you can access the page number via the usual
 .B %
-register and use the
+register and invoke the
 .B af
 request to assign a different format to it if desired.
 .
@@ -2086,7 +2087,7 @@ _
 .
 The default for
 .B ABSTRACT
-includes font style escapes to set the word in italics.
+includes font style escape sequences to set the word in italics.
 .
 .
 .\" TODO: Put this in a legacy feature support section, alongside AT&T