[groff] 04/17: [ms]: Improve "basic information" documentation.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 3f0b41f088b6fb68867403a7d69f62480c11632e
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sun Jul 17 06:25:33 2022 -0500

    [ms]: Improve "basic information" documentation.
    
    * More consistently use italics to introduce terminology.
    * Explain what a macro call is.
    * Explain what registers and strings store.
    * Recast discussion of \& to scoop up its application to '.
    * Fix markup nit, setting prose semicolon in Times, not Courier.
    * Resync our Texinfo manual with recent ms.ms edits.
    * Clarify a comment.
---
 doc/groff.texi | 43 +++++++++++++++++++++----------------------
 doc/ms.ms      | 45 +++++++++++++++++++++++++++++++--------------
 2 files changed, 52 insertions(+), 36 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 112e0b2f..fd322ab1 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -2479,9 +2479,10 @@ longer works intended for printing and possible 
publication.
 @file{ms} documents are plain text files; prepare them with your
 preferred text editor.  If you're in a hurry to get started, be advised
 that @file{ms} needs one of its macros called at the beginning of a
-document so that it can initialize.  Put a macro call on a line by
-itself.  Use @samp{.PP} if you want your paragraph's first line to be
-indented, or @samp{.LP} if you don't.
+document so that it can initialize.  A @dfn{macro} is a formatting
+instruction to @file{ms}.  Put a macro call on a line by itself.  Use
+@samp{.PP} if you want your paragraph's first line to be indented, or
+@samp{.LP} if you don't.
 
 After that, start typing normally.  It is a good practice to start each
 sentence on a new line, or to put two spaces after sentence-ending
@@ -2514,10 +2515,9 @@ denied than admitted.
 @endCartoucheExample
 
 @file{ms} exposes many aspects of document layout to user control via
-@code{groff} registers and strings.  Most registers have a default unit
-of measurement.  Specifying a unit explicitly does not cause problems,
-and can avoid them in complex situations.  The following table
-summarizes typical units.
+@code{groff}'s @dfn{registers} and @dfn{strings}, which store numbers
+and text, respectively.  Measurements in @code{groff} are expressed with
+a suffix called a @dfn{scaling unit}.
 
 @table @code
 @item i
@@ -2543,10 +2543,10 @@ ems; width of an ``M'' using the current font
 @end table
 
 Set registers with the @code{nr} request and strings with the @code{ds}
-request.  Requests are like macro calls; they go on lines by themselves
-and start with the control character, a dot (@code{.}).  The difference
-is that they directly instruct the formatter program, rather than the
-macro package.
+request.  @dfn{Requests} are like macro calls; they go on lines by
+themselves and start with the @dfn{control character}, a dot (@code{.}).
+The difference is that they directly instruct the formatter program,
+rather than the macro package.
 
 @CartoucheExample
 .nr PS 10.5p \" Use 10.5-point type.
@@ -2555,10 +2555,10 @@ macro package.
 
 @noindent
 In the foregoing, we see that @code{\"} begins a comment.  This is an
-example of an escape sequence, the other kind of formatting instruction.
-Escape sequences can appear anywhere.  They begin with the escape
-character (@code{\}) and are followed by at least one more character.
-@file{ms} documents
+example of an @dfn{escape sequence}, the other kind of formatting
+instruction.  Escape sequences can appear anywhere.  They begin with the
+escape character (@code{\}) and are followed by at least one more
+character.  @file{ms} documents
 @c like this one
 tend to use only a few of @code{groff}'s many requests and escape
 sequences; see @ref{Request Index} and @ref{Escape Sequence Index} or
@@ -2585,18 +2585,17 @@ Interpolate glyph of special character named @var{char}.
 non-printing, zero-width dummy character
 
 @item \~
-Move horizontally by the current font's space width (``non-breaking
-space'').
+Insert an unbreakble space that is adjustable like a normal space.
 
 @item \|
 Move horizontally by one-sixth em (``thin space'').
 @end table
 
-@code{\&} has two important uses: put it before a word starting with a
-dot @samp{.} if that word is at the beginning of an input line (or might
-become that way in editing) to prevent the dot from being interpreted as
-the control character, and after @samp{.}, @samp{?}, and @samp{!}, when
-needed to cancel end-of-sentence detection.
+Prefix any words that start with a dot @samp{.} or neutral apostrophe
+@samp{'} with @code{\&} if they are at the beginning of an input line
+(or might become that way in editing) to prevent them from being
+interpreted as macro calls or requests.  Suffix @samp{.}, @samp{?}, and
+@samp{!} with @code{\&} when needed to cancel end-of-sentence detection.
 
 @CartoucheExample
 After the criticality accident, Dr.\&
diff --git a/doc/ms.ms b/doc/ms.ms
index b670ece8..b0737b4d 100644
--- a/doc/ms.ms
+++ b/doc/ms.ms
@@ -7,8 +7,8 @@
 .  \" Redefine CW to use bold instead for a visible font change.
 .  als CW B
 .\}
-.\" This document doesn't require the minus sign but we do want a copy-
-.\" and-pastable hyphen-minus.
+.\" This document doesn't require the minus sign (in Times) but we do
+.\" want a copy- and-pastable hyphen-minus.
 .char \- \N'45'
 .\" A very limited output device might not have a dagger glyph.
 .fchar \[dg] *
@@ -140,6 +140,11 @@ be advised that
 needs one of its macros called at the beginning of a document so that it
 can initialize.
 .
+A
+.I macro
+is a formatting instruction to
+.I ms.
+.
 Put a macro call on a line by itself.
 .
 Use
@@ -208,8 +213,12 @@ denied than admitted.
 .LP
 .I ms
 exposes many aspects of document layout to user control via
-.I groff
-registers and strings.
+.I groff 's
+.I registers
+and
+.I strings,
+which store numbers and text,
+respectively.
 .
 Measurements in
 .I groff
@@ -241,8 +250,10 @@ and strings with the
 .CW ds
 request.
 .
-Requests are like macro calls;
-they go on lines by themselves and start with the control character,
+.I Requests
+are like macro calls;
+they go on lines by themselves and start with the
+.I "control character,"
 a dot
 .CW . ). (
 .
@@ -269,7 +280,8 @@ we see that
 .CW \[rs]"
 begins a comment.
 .
-This is an example of an escape sequence,
+This is an example of an
+.I "escape sequence,"
 the other kind of formatting instruction.
 .
 Escape sequences can appear anywhere.
@@ -304,7 +316,7 @@ Interpolate contents of string
 T}
 \[rs]*\f[I]s   T{
 abbreviation of
-.CW \[rs]*[\f[I]s\f[]];
+.CW \[rs]*[\f[I]s\f[]] ;
 the name
 .I s
 must be only one character
@@ -325,18 +337,23 @@ T}
 .
 .
 .PP
-.CW \[rs]&
-has two important uses:
-put it before a word starting with a dot
+Prefix any words that start with a dot
 .CW .\& ) (
-if that word is at the beginning of an input line
+or neutral apostrophe
+.CW \[aq] ) (
+with
+.CW \[rs]&
+if they are at the beginning of an input line
 (or might become that way in editing)
-to prevent the dot from being interpreted as the control character,
-and after
+to prevent the them from being interpreted as macro calls or requests.
+.
+Suffix
 .CW . ,
 .CW ? ,
 and
 .CW !\&
+with
+.CW \[rs]&
 when needed to cancel end-of-sentence detection.
 .
 .