[groff] 04/04: Update string documentation (again).

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 1d1ee5548410af3a1e3278fa4ee6664f0e60a78d
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sat Aug 1 17:07:27 2020 +1000

    Update string documentation (again).
    
    * doc/groff.texi (Strings):
      +  Convert paragraph before .ds/.ds1/\* list to serve more of a
         "TL;DR" function, since what follows takes up literally pages of
         text in PDF form.
      + Drop mention that "GNU troff" parses the contents of an interpolated
        string.  What else would do it?
      + Add example of nested string interpolation.
      + Drop phrases "for more details" and "for more information" after
        cross-references.  Without more, I think constructions like this add
        nothing.  Why else would you follow a cross-reference?
      + Drop characterization of, e.g., ".ds foo" as "explicitly" defining
        an empty string.  This is true but tautologous, I think.
      + Clarify that arguments after the first to .ds and friends consume
        the _remainder_ of the input line, not the "entire" line.
      + Clarify why inline comments can lead to trailing spaces in string
        definitions/appendments.  (It's because those blessed few who
        comment source at all generally do not do so barbarously by smashing
        the comment character into the immediately preceding material.)
      + Clarify that escape sequence semantics are not overridden by string
        definition argument handling.
      + Stop describing non-escaped newlines as "real" in favor of a more
        explicit explanation.
      + With .ds1 moved in a previous commit, the discussion of string/macro
        interpolation mixture now flows much more naturally.  Now it almost
        reads as if it were planned that way...recast to assist illusion.
      + Add forward cross-reference to Parameters node when discussion
        string interpolation of macro definition; \$0 has not been seen
        before in the manual.
      + Coalesce adjacent one-sentence paragraphs.
      + Clarify how compatibility save/restore tokens work--they affect the
        behavior of a string when it is later interpolated, not at the time
        the .ds1 and .as1 macros are used (you already have to be outside of
        compatibility mode to use them).
      + Change metasyntactic variable name of .length request from "str" to
        "anything".  .length can measure things that are not (named)
        strings.  Mark up that same argument correctly, with @var instead of
        @code.
      + Change metasyntactic variable name of .chop request from "xx" to
        "object".
      + Change metasyntactic variable names of .rn request from "xx" and
        "yy" to "old" and "new".
      + Change metasyntactic variable name of .rm request from "xx" to
        "name".  Clarify that it is the _name_, not the _object_ to which it
        refers, that is subsequently treated as never having been defined.
      + Add "@:" (Texinfo's '\&') after ":" where it is not followed by a
        new sentence.  In general, a colon does not terminate a sentence.
        What madness is this?
      + Recast language for brevity or less awkwardness (in my opinion).
      + Fix typo.
      + Unhyphenate "previously-defined"; per some online style guides, an
        adverbial qualifier to a phrasal adjectives cancels the hyphenation
        requirement of its portion of an adjectival phrase.  Hence
        "previously defined string variables" but "putatively long-term
        obligations" (not "putatively-long-term", which I would have
        recognized as wrong on sight).  Thanks to Dave Kemper for correcting
        my hypercorrection.
    
    * man/groff.7.man:
      + (.as, .as1, .chop, .ds, ds1, .length, .substring): Sync
        metasyntactic variable renames with our Texinfo manual.
      + (.chop, .ds, .length, .substring): Sync request explanations with
        our Texinfo manual (keeping them to one or occasionally two
        sentences).
      + (Strings): Resync with material from our Texinfo manual, in
        abbreviated form.
    
    * man/groff_diff.7.man:
      + (.als): Prefix request names with a leading dot.
      + (.as1, .chop, .ds1, .length, .stringdown, .stringup, .substring):
        Sync metasyntactic variable renames with our Texinfo manual.  Sync
        request explanations with our Texinfo manual.
      + (.stringdown, .stringup): Fix special character escapes in example.
---
 doc/groff.texi       | 152 ++++++++++++++++++++++++++-------------------------
 man/groff.7.man      | 141 ++++++++++++++++++++++++++++++++---------------
 man/groff_diff.7.man | 116 ++++++++++++++++++++++++++-------------
 3 files changed, 254 insertions(+), 155 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 0930342..f0b45de 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -10394,9 +10394,9 @@ This string contains the current output device (for 
example,
 @samp{utf8} or @samp{pdf}).
 @endDefstr
 
-Although the following requests can be used to create strings, simply
-using (dereferencing) an undefined string will cause it to be defined as
-empty.
+The @code{ds} (or @code{ds1}) request creates a string and the @code{\*}
+escape retrieves (dereferences) its contents.  Dereferencing an
+undefined string name defines it as empty.
 
 @DefreqList {ds, name [@Var{string}]}
 @DefreqItemx {ds1, name [@Var{string}]}
@@ -10417,9 +10417,9 @@ Define and access a string variable @var{name} 
(one-character
 name@tie{}@var{n}, two-character name @var{nm}).  If @var{name} already
 exists, @code{ds} overwrites the previous definition.  The syntax form
 using brackets accepts arguments that are handled as macro arguments
-are; unlike with macro calls, however, a closing bracket as an argument
-must be enclosed in double quotes.  @xref{Request and Macro Arguments},
-and @ref{Parameters}.
+are; in contrast to macro calls, however, a closing bracket as an
+argument must be enclosed in double quotes.  @xref{Request and Macro
+Arguments}, and @ref{Parameters}.
 
 Example:
 
@@ -10430,33 +10430,42 @@ This is \*[foo nice].
     @result{} This is a nice test.
 @endExample
 
-The @code{\*} escape @dfn{interpolates} (expands in place) a
-previously-defined string variable.  To be more precise, the stored
-string is pushed onto the input stack, which is then parsed by GNU
-@code{troff}.  Similarly to number registers, it is possible to nest
-strings; i.e., string variables can be called within string variables.
+The @code{\*} escape @dfn{interpolates} (expands in place) a previously
+defined string variable.  More precisely, the stored string is pushed
+onto the input stack, which is then parsed normally.  Similarly to
+number registers, it is possible to nest strings; i.e., string variables
+can be called within string variables.
+
+@Example
+.ds a hairy
+.ds b \*[a] wildebeest
+.ds c big, \*[b]
+I see a \*[c].
+    @result{} I see a big, hairy wildebeest.
+@endExample
 
 If the string named by the @code{\*} escape does not exist, it is
 defined as empty, and a warning of type @samp{mac} is emitted (see
-@ref{Debugging} for more details).
+@ref{Debugging}).
 
-If @code{ds} is called with only one argument, @var{name} is explicitly
-defined as an empty string.
+If @code{ds} is called with only one argument, @var{name} is defined as
+an empty string.
 
 @cindex comments, with @code{ds}
 @cindex @code{ds} request, and comments
 @strong{Caution:} Unlike other requests, the second argument to the
-@code{ds} request takes up the entire line including trailing spaces.
-This means that comments on a line with such a request can introduce
-unwanted space into a string.
+@code{ds} request consumes the remainder of the input line, including
+trailing spaces.  This means that comments on a line with such a request
+can introduce unwanted space into a string when they are set off from
+the material they annotate, as is conventional.
 
 @Example
 .ds TeX T\h'-.2m'\v'.2m'E\v'-.2m'\h'-.1m'X \" Knuth's TeX
 @endExample
 
 @noindent
-Instead the comment should be put on another line or have the comment
-escape adjacent with the end of the string.
+Instead, place the comment on another line or put the comment escape
+immediately adjacent to the last character of the string.
 
 @Example
 .ds TeX T\h'-.2m'\v'.2m'E\v'-.2m'\h'-.1m'X\" Knuth's TeX
@@ -10478,15 +10487,15 @@ creeping into them during source document maintenance.
 @cindex @code{ds} request, and leading spaces
 To store leading space in a string, start it with a double quote.  A
 double quote is special only in that position; double quotes in any
-other location are included in the string.  Consequently, no
-trailing quote is needed.
+other location are included in the string (the effect of escape
+sequences notwithstanding).
 
 @c Examples should be more accessible than Unix nerd stuff like this,
 @c but in general document authors shouldn't want to use "straight"
 @c double quotes for ordinary prose anyway.  Also, 56 chars is as fat
 @c as these examples can get and not overrun the right margin in PDF.
 @Example
-.ds saluatation "         Yours in a white wine sauce,\"
+.ds salutation "         Yours in a white wine sauce,\"
 .ds c-var-defn "    char build_date[]="2020-07-29";\"
 .ds sucmd sudo sh -c "fdisk -l /dev/sda > partitions"\"
 @endExample
@@ -10505,9 +10514,9 @@ text on multiple lines \
 of input.
 @endExample
 
-It is not possible to embed ``real'' newlines in a string.  How breaking
-occurs depends on fill mode as usual, and also upon whether the string
-is interpolated as a string or a macro (see below).
+It is not possible to embed a newline in a string that will be
+interpreted as such when the string is interpolated.  To achieve that
+effect, use the @code{\*} escape to interpolate a macro instead.
 
 @cindex name space, common, of macros, diversions, and strings
 @cindex common name space of macros, diversions, and strings
@@ -10515,9 +10524,9 @@ is interpolated as a string or a macro (see below).
 @cindex strings, shared name space with macros and diversions
 @cindex diversions, shared name space with macros and strings
 Strings, macros, and diversions (and boxes) share the same name space.
-Internally, the same mechanism is used to store them.  This has some
-interesting consequences.  For example, it is possible to call a macro
-with string syntax and vice versa.
+Internally, the same mechanism is used to store them.  Thus it is
+possible to invoke a macro with string interpolation syntax and vice
+versa.
 
 @Example
 .de subject
@@ -10576,12 +10585,11 @@ is
 
 @noindent
 Note that the latter calling syntax doesn't change the value of
-@code{\$0}, which is then inherited from the calling macro.
+@code{\$0}, which is then inherited from the calling macro
+(@pxref{Parameters}).
 
-Diversions and boxes can be also called with string syntax.
-
-Another consequence is that you can copy one-line diversions or boxes to
-a string.
+Diversions and boxes can be also called with string syntax.  It is
+sometimes convenient to copy one-line diversions or boxes to a string.
 
 @Example
 .di xxx
@@ -10644,13 +10652,13 @@ This is \*[xxx].
     @result{} This is a funny test.
 @endExample
 
-@xref{Gtroff Internals}, for more information.
+@xref{Gtroff Internals}.
 @endDefreq
 
-The @code{ds1} request turns off compatibility mode while interpreting a
-string.  To be more precise, a @dfn{compatibility save} input token is
-inserted at the beginning of the string, and a @dfn{compatibility
-restore} input token at the end.
+The @code{ds1} request defines a string such that compatibility mode is
+off when the string is later interpolated.  To be more precise, a
+@dfn{compatibility save} input token is inserted at the beginning of the
+string, and a @dfn{compatibility restore} input token at the end.
 
 @Example
 .nr xxx 12345
@@ -10680,10 +10688,10 @@ with only one argument, no operation is performed.
 @endExample
 
 The @code{as1} request is similar to @code{as}, but compatibility mode
-is switched off while the appended string is interpreted.  To be more
-precise, a @dfn{compatibility save} input token is inserted at the
-beginning of the appended string, and a @dfn{compatibility restore}
-input token at the end.
+is switched off while the appended portion of the string is
+interpolated.  To be more precise, a @dfn{compatibility save} input
+token is inserted at the beginning of the appended string, and a
+@dfn{compatibility restore} input token at the end.
 @endDefreq
 
 Several requests exist to perform rudimentary string operations.
@@ -10691,15 +10699,15 @@ Strings can be queried (@code{length}) and modified 
(@code{chop},
 @code{substring}, @code{stringup}, @code{stringdown}), and their names
 can be manipulated (@code{rn}, @code{rm}, @code{als}).
 
-@Defreq {length, reg str}
+@Defreq {length, reg anything}
 @cindex length of a string (@code{length})
 @cindex string, length of (@code{length})
 @cindex @code{length} request, and copy-in mode
 @cindex copy-in mode, and @code{length} request
 @cindex mode, copy-in, and @code{length} request
-Compute the number of characters of @var{str} and return it in the
-number register @var{reg}.  If @var{reg} doesn't exist, it is created.
-@code{str} is read in copy mode.
+Compute the number of characters of @var{anything} and store the count
+in the number register @var{reg}.  If @var{reg} doesn't exist, it is
+created.  @var{anything} is read in copy mode.
 
 @Example
 .ds xxx abcd\h'3i'efgh
@@ -10709,12 +10717,12 @@ number register @var{reg}.  If @var{reg} doesn't 
exist, it is created.
 @endExample
 @endDefreq
 
-@Defreq {chop, xx}
-Remove (chop) the last character from the macro, string, or diversion
-named @var{xx}.  This is useful for removing the newline from the end of
-diversions that are to be interpolated as strings.  This request can be
-used repeatedly; see @ref{Gtroff Internals}, for details on nodes
-inserted additionally by GNU @code{troff}.
+@Defreq {chop, object}
+Remove the last character from the macro, string, or diversion named
+@var{object}.  This is useful for removing the newline from the end of a
+diversion that is to be interpolated as a string.  This request can be
+used repeatedly on the same @var{object}; see @ref{Gtroff Internals},
+for details on nodes inserted additionally by GNU @code{troff}.
 @endDefreq
 
 @Defreq {substring, str start [@Var{end}]}
@@ -10722,10 +10730,9 @@ inserted additionally by GNU @code{troff}.
 Replace the string named @var{str} with its substring bounded by the
 indices @var{start} and @var{end}, inclusive.  The first character in
 the string has index@tie{}0.  If @var{end} is omitted, it is implicitly
-set to the largest valid value (the string length minus one).  If the
-index value @var{start} or @var{end} is negative, it is counted from the
-end of the string, going backwards: the last character has
-index@tie{}@minus{}1, the character before the last has
+set to the largest valid value (the string length minus one).  Negative
+indices count backwards from the end of the string:@: the last character
+has index@tie{}@minus{}1, the character before the last has
 index@tie{}@minus{}2, and so on.
 
 @Example
@@ -10746,12 +10753,12 @@ index@tie{}@minus{}2, and so on.
 @cindex lowercasing a string (@code{stringdown})
 @cindex up-casing a string (@code{stringup})
 @cindex down-casing a string (@code{stringdown})
-Change the string named @var{str} by replacing each of its bytes with
+Alter the string named @var{str} by replacing each of its bytes with
 its lowercase (@code{stringdown}) or uppercase (@code{stringup}) version
-(if any).  @code{groff} special characters (see the @cite{groff_char(7)}
-man page) can be used and the output will usually transform in the
-expected way due to the regular naming convention of the special
-character escapes.
+(if one exists).  GNU @code{troff} special characters (see the
+@cite{groff_char(7)} man page) can be used and the output will usually
+transform in the expected way due to the regular naming convention of
+the special character escapes.
 
 @Example
 .ds resume R\['e]sum\['e]\"
@@ -10764,7 +10771,7 @@ character escapes.
 @endExample
 @endDefreq
 
-@Defreq {rn, xx yy}
+@Defreq {rn, old new}
 @cindex renaming request (@code{rn})
 @cindex request, renaming (@code{rn})
 @cindex renaming macro (@code{rn})
@@ -10773,10 +10780,10 @@ character escapes.
 @cindex string, renaming (@code{rn})
 @cindex renaming diversion (@code{rn})
 @cindex diversion, renaming (@code{rn})
-Rename the request, macro, diversion, or string @var{xx} to @var{yy}.
+Rename the request, macro, diversion, or string @var{old} to @var{new}.
 @endDefreq
 
-@Defreq {rm, xx}
+@Defreq {rm, name}
 @cindex removing request (@code{rm})
 @cindex request, removing (@code{rm})
 @cindex removing macro (@code{rm})
@@ -10785,8 +10792,8 @@ Rename the request, macro, diversion, or string 
@var{xx} to @var{yy}.
 @cindex string, removing (@code{rm})
 @cindex removing diversion (@code{rm})
 @cindex diversion, removing (@code{rm})
-Remove the request, macro, diversion, or string @var{xx}.  GNU
-@code{troff} treats subsequent invocations as if the object had never
+Remove the request, macro, diversion, or string @var{name}.  GNU
+@code{troff} treats subsequent invocations as if the name had never
 been defined.
 @endDefreq
 
@@ -10806,13 +10813,12 @@ diversion object named @var{old}, causing the names 
to refer to the same
 stored object.  If @var{old} is undefined, a warning of type @samp{mac}
 is generated and the request is ignored.
 
-To understand how the @code{als} request works it is probably best to
-think of two different storage pools: one for objects (macros, strings,
-etc.), and another for names.  As soon as an object is defined, GNU
-@code{troff} adds it to the object pool, adds its name to the name pool,
-and creates a link between them.  When @code{als} creates an alias, it
-adds a new name to the name pool that gets linked to the same object as
-the old name.
+To understand how the @code{als} request works, consider two different
+storage pools:@: one for objects (macros, strings, etc.), and another
+for names.  As soon as an object is defined, GNU @code{troff} adds it to
+the object pool, adds its name to the name pool, and creates a link
+between them.  When @code{als} creates an alias, it adds a new name to
+the name pool that gets linked to the same object as the old name.
 
 Now consider this example.
 
diff --git a/man/groff.7.man b/man/groff.7.man
index 630e50b..246b851 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -1259,18 +1259,18 @@ Same as
 but with compatibility mode switched off during macro expansion.
 .
 .TPx
-.REQ .as "stringvar \fR[\fPanything\fR]\fP"
+.REQ .as "name \fR[\fPstring\fR]\fP"
 Append
-.I anything
-to
-.IR stringvar ;
+.I string
+to the string
+.IR name ;
 no operation if
-.I anything
+.I string
 is omitted.
 .
 .
 .TPx
-.REQ .as1 "stringvar \fR[\fPanything\fR]\fP"
+.REQ .as1 "name \fR[\fPstring\fR]\fP"
 Same as
 .request .as
 but with compatibility mode switched off during string expansion.
@@ -1418,8 +1418,11 @@ as string
 .IR anything .
 .
 .TPx
-.REQ .chop "object"
-Chop the last character off macro, string, or diversion
+.REQ .chop object
+Remove the last character from the macro,
+string,
+or diversion
+named
 .IR object .
 .
 .TPx
@@ -1617,18 +1620,18 @@ of
 is interpreted.
 .
 .TPx
-.REQ .ds "stringvar \fR[\fPanything\fR]\fP"
-Set
-.I stringvar
-to
-.IR anything ,
-or to the empty string if
-.I anything
+.REQ .ds "name \fR[\fPstring\fR]\fP"
+Define a string variable
+.I name
+with contents
+.IR string ,
+or as empty if
+.I string
 is omitted.
 .
 .
 .TPx
-.REQ .ds1 "stringvar \fR[\fPanything\fR]\fP"
+.REQ .ds1 "name \fR[\fPstring\fR]\fP"
 Same as
 .request .ds
 but with compatibility mode switched off during string expansion.
@@ -2012,11 +2015,12 @@ Set leader repetition glyph to\~\c
 .IR c .
 .
 .TPx
-.REQ .length "register anything"
-Write the length of the string
+.REQ .length "reg anything"
+Compute the number of characters of
 .I anything
-to
-.IR register .
+and store the count
+in the number register
+.IR reg .
 .
 .TPx
 .REQ .linetabs
@@ -2538,15 +2542,18 @@ with font position
 .IR n .
 .
 .TPx
-.REQ .substring "xx start \fR[\fPend\fR]\fP"
+.REQ .substring "str start \fR[\fPend\fR]\fP"
 Replace the string named
-.I xx
+.I str
 with its substring bounded by the indices
 .I start
 and
 .IR end ,
 inclusive.
 .
+Negative indices count backwards from the end of the string.
+.
+.
 .TPx
 .REQ .sv
 Save
@@ -3891,17 +3898,76 @@ or
 .
 .
 .P
-Strings are defined by the
+The
 .request .ds
-and
-.request .ds1
-requests and can be retrieved by the
+request creates a string and the
 .esc *
-escape sequence.
+escape retrieves (dereferences) its contents.
 .
-Simply using
-(dereferencing)
-an undefined string will cause it to be defined as empty.
+Dereferencing an undefined string name defines it as empty.
+.
+.
+.P
+The
+.request .as
+requests is similar to
+.request .ds
+but appends its arguments
+(after the first)
+to a string instead of redefining it.
+.
+If
+.request .as
+is called with only one argument,
+no operation is performed.
+.
+.
+.P
+The
+.request .ds1
+request defines a string such that compatibility mode is off when the
+string is later interpolated.
+.
+To be more precise,
+a
+.I compatibility save
+input token is inserted at the beginning of the string,
+and a
+.I compatibility restore
+input token at the end.
+.
+Likewise,
+the
+.request .as1
+request is similar to
+.request .as\c
+,
+but compatibility mode is switched off while the appended portion of the
+string is interpolated.
+.
+.
+.P
+.B Caution:
+Unlike other requests,
+the second argument to these requests consumes the remainder of the
+input line,
+including trailing spaces.
+.
+It is good style to end string definitions
+(and appendments)
+with a comment,
+even an empty one,
+to prevent unwanted space from creeping into them during source document
+maintenance.
+.
+.
+.P
+To store leading space in a string,
+start it with a double quote.
+.
+A double quote is special only in that position;
+double quotes in any other location are included in the string
+(the effect of escape sequences notwithstanding).
 .
 .
 .P
@@ -3911,22 +3977,11 @@ and diversions
 (and boxes)
 share the same name space.
 .
-Internally, the same mechanism is used to store them.
+Internally,
+the same mechanism is used to store them.
 .
 .
 .P
-The
-.request .as
-and
-.request .as1
-requests are similar to
-.request .ds
-and
-.request .ds1 ,
-but append their arguments
-(after the first)
-to a string instead of redefining it.
-.
 Several requests exist to perform rudimentary string operations.
 .
 Strings can be queried
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index fae6d65..43996ec 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -980,18 +980,20 @@ To be more precise,
 a \[lq]compatibility save\[rq] token is inserted at the beginning,
 and a \[lq]compatibility restore\[rq] token at the end.
 .
-As a consequence, the requests
-.BR am ,
-.BR am1 ,
-.BR de ,
+As a consequence,
+the requests
+.BR .am ,
+.BR .am1 ,
+.BR .de ,
 and
-.B de1
+.B .de1
 can be intermixed freely since the compatibility save/\:restore tokens
 only affect the macro parts defined by
 .B .am1
 and
 .BR .ds1 .
 .
+.
 .TP
 .BI .ami\~ xx\~yy
 Append to macro indirectly.
@@ -1008,16 +1010,20 @@ request but compatibility mode is switched off during 
execution.
 .
 .
 .TP
-.BI .as1\~ xx\~yy
+.BI .as1\~ "name string"
 Similar to
 .BR .as ,
-but compatibility mode is switched off during expansion.
+but compatibility mode is switched off while the appended portion of the
+string is interpolated.
 .
 To be more precise,
-a \[lq]compatibility save\[rq] token is inserted at the beginning,
+a \[lq]compatibility save\[rq] token is inserted at the beginning of the
+appended string
+.IR string,
 and a \[lq]compatibility restore\[rq] token at the end.
 .
-As a consequence, the requests
+As a consequence,
+the requests
 .BR as ,
 .BR as1 ,
 .BR ds ,
@@ -1390,12 +1396,27 @@ A glyph definition can be removed with the
 .B rchar
 request.
 .
+.
 .TP
-.BI .chop\~ xx
-Chop the last element off macro, string, or diversion
-.IR xx .
-This is useful for removing the newline from the end of diversions
-that are to be interpolated as strings.
+.BI .chop\~ object
+Remove the last character from the macro,
+string,
+or diversion
+named
+.IR object .
+.
+This is useful for removing the newline from the end of a diversion that
+is to be interpolated as a string.
+.
+This request can be used repeatedly on the same
+.IR object ;
+see section \[lq]Gtroff Internals\[rq] in
+.IR "Groff: The GNU Implementation of troff" ,
+the
+.I groff
+Texinfo manual,
+for details on nodes inserted additionally by
+.IR groff .
 .
 .
 .TP
@@ -1773,13 +1794,16 @@ as output.
 .RE \" this "extra" RE avoids indentation of the remaining paragraphs
 .
 .TP
-.BI .ds1\~ xx\~yy
+.BI .ds1\~ "name string"
 Similar to
 .BR .ds ,
+but compatibility mode is switched off when the string is later
+interpolated.
 but compatibility mode is switched off during expansion.
 .
 To be more precise,
-a \[lq]compatibility save\[rq] token is inserted at the beginning,
+a \[lq]compatibility save\[rq] token is inserted at the beginning of the
+string,
 and a \[lq]compatibility restore\[rq] token at the end.
 .
 .
@@ -2349,12 +2373,30 @@ If
 is non-zero or missing, enable pairwise kerning, otherwise disable it.
 .
 .TP
-.BI .length\~ xx\~string
-Compute the length of
-.I string
-and return it in the number register
-.I xx
-(which is not necessarily defined before).
+.BI .length\~ "reg anything"
+Compute the number of characters in
+.I anything
+and return the count in the number register
+.IR reg.
+.
+If
+.I reg
+doesn't exist,
+it is created.
+.
+.I anything
+is read in copy mode.
+.
+.RS
+.IP
+.EX
+.B .ds xxx abcd\eh\[aq]3i\[aq]efgh
+.B .length yyy \e*[xxx]
+.B \en[yyy]
+14
+.EE
+.RE
+.
 .
 .TP
 .BI .linetabs\~ n
@@ -2783,17 +2825,18 @@ See
 for warning types and control.
 .
 .TP
-.BI .stringdown \~stringvar
+.BI .stringdown \~str
 .TQ
-.BI .stringup \~stringvar
-Change the string named
-.I stringvar
+.BI .stringup \~str
+Alter the string named
+.I str
 by replacing each of its bytes with its
 lowercase
 .RB ( down )
 or uppercase
 .RB ( up )
-version (if any).
+version
+(if one exists).
 .
 .I groff
 special characters
@@ -2807,11 +2850,11 @@ due to the regular naming convention of the special 
character escapes.
 .RS
 .EX
 \&.ds resume R\e['e]sum\e['e]\e"
-\e*[resume] \e# R['e]sum['e]
+\e*[resume] \e# R\['e]sum\['e]
 \&.stringdown resume
-\e*[resume] \e# r['e]sum['e]
+\e*[resume] \e# r\['e]sum\['e]
 \&.stringup resume
-\e*[resume] \e# R['E]SUM['E]
+\e*[resume] \e# R\['E]SUM\['E]
 .EE
 .RE
 .RE
@@ -2864,9 +2907,10 @@ file controls which font positions (if any) are 
initially associated
 with styles rather than fonts.
 .
 .TP
-.BI .substring\~ xx\~start\~ [ end ]
+.BI .substring\~ "str start\~"\c
+.RI [ end ]
 Replace the string named
-.I xx
+.I str
 with its substring bounded by the indices
 .I start
 and
@@ -2881,13 +2925,7 @@ is omitted,
 it is implicitly set to the largest valid value
 (the string length minus one).
 .
-If the index value
-.I start
-or
-.I end
-is negative,
-it is counted from the end of the string,
-going backwards:
+Negative indices count backwards from the end of the string:
 the last character has index\~\-1,
 the character before the last has index\~\-2,
 and so on.