[groff] 11/49: doc/groff.texi: Fix misleading claim re copy mode.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 3d2e43245a7f7056ae0a5fa97a5aa000906295ed
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Thu Nov 3 03:36:28 2022 -0500

    doc/groff.texi: Fix misleading claim re copy mode.
    
    * doc/groff.texi (Debugging): Fix misleading claim.  The arguments to
      the `tm`, `tmc`, and `tm1` requests are not read in copy mode.  For
      example, you don't need to double backslashes to get them to
      interpolate registers or strings.
    
    (While it is true that the _implementation_ of these requests currently
    use a function called `get_copy`, the latter takes two Boolean arguments
    that change its behavior.  It doesn't seem to me that they operate in
    copy mode in any sense easily intelligible to the general user.  See
    below.)
    
    Also clarify other points about copy mode.
    
    * doc/groff.texi (Using Escape Sequences): Clarify that disabling the
      escape character affects interpretation mode, not copy mode.  For
      instance, comment and input line continuation escape sequences still
      work.
      (Tabs and Fields): Clarify that `\a` and `\t` interpolate tabs and
      leaders, not merely their characters.
    
    * man/groff.7.man: Sync with the foregoing.
    
    Also fix bracketing comment for alignment of Texinfo and man material.
    
    Illustration:
    
    $ cat EXPERIMENTS/tm-and-ds-and-copy-mode.roff
    .nr rr 88
    .nf
    .tc $
    .ds t1 string: unescaped tab    here
    .ds t2 string: backslash t\there
    .ds t3 string: unescaped leader
here
    .ds t4 string: backslash a\there
    \*(t1
    \*(t2
    \*(t3
    \*(t4
    .tm tm unescaped tab    here
    .tm tm backslash t\there
    .tm tm unescaped leader
here
    .tm tm backslash a\there
    .ds s1 string: foo\n(rr\"bar
    .ds s2 string: foo\\n(rr\"bar
    .nr rr 99
    \*(s1
    \*(s2
    .tm tm baz\n(rr\"bar
    .tm tm qux\\n(rr\"bar
    .ig
    .eo
    .ds s2 string: baz\"qux
    \*(s2
    .tm tm baz\"qux
    .ec
    ..
    .pl \n(nlu
    $ nroff EXPERIMENTS/tm-and-ds-and-copy-mode.roff
    tm unescaped tab        here
    tm backslash t  here
    tm unescaped leader
here
    tm backslash a  here
    tm baz99
    tm qux\n(rr
    string: unescaped tab$$$here
    string: backslash t$$$$$here
    string: unescaped leader........here
    string: backslash a$$$$$here
    string: foo88
    string: foo99
---
 ChangeLog       |  7 +++++++
 doc/groff.texi  | 37 ++++++++++++-------------------------
 man/groff.7.man | 10 ++++------
 3 files changed, 23 insertions(+), 31 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 0333c6c00..c4e7e5ed9 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2022-11-02  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       * doc/groff.texi (Debugging): Fix misleading claim.  The
+       arguments to the `tm`, `tmc`, and `tm1` requests are not read in
+       copy mode.  For example, you don't need to double backslashes to
+       get them to interpolate registers or strings.
+
 2022-11-02  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        * tmac/an.tmac (an-end):
diff --git a/doc/groff.texi b/doc/groff.texi
index f76f9f9f8..e2e0dd41d 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -6843,8 +6843,8 @@ problem because it tracks the nesting depth of 
interpolations.
 
 @c ---------------------------------------------------------------------
 
-@c BEGIN Keep (roughly) parallel with section "Escape sequences" of
-@c groff(7).
+@c BEGIN Keep (roughly) parallel with section "Using escape sequences"
+@c of groff(7).
 @node Using Escape Sequences, Delimiters, Calling Macros, Formatter 
Instructions
 @subsection Using Escape Sequences
 @cindex using escape sequences
@@ -6931,17 +6931,18 @@ character escape sequence.  In macro and string 
definitions, two further
 input sequences @code{\\} and @code{\E} come into play, permitting
 deferred interpretation of escape sequences.  @xref{Copy Mode}.
 
-Escape sequence interpretation can be switched off and back on.  This
-procedure can obviate the need to double the escape character inside
-macro definitions.  @xref{Writing Macros}.  (This approach is not
-available  if your macro needs to interpolate values at the time it is
-@emph{defined}---but many do not.)
+Outside of copy mode, escape sequence interpretation can be switched off
+and back on.  This procedure can obviate the need to double the escape
+character inside macro definitions.  @xref{Writing Macros}.  (This
+approach is not available if your macro needs to interpolate values at
+the time it is @emph{defined}---but many do not.)
 
 @Defreq {eo, }
 @cindex disabling @code{\} (@code{eo})
 @cindex @code{\}, disabling (@code{eo})
-Disable the escape mechanism.  Once this request is invoked, no input
-character is recognized as starting an escape sequence.
+Disable the escape mechanism except in copy mode.  Once this request is
+invoked, no input character is recognized as starting an escape
+sequence in interpretation mode.
 @endDefreq
 
 @Defreq {ec, [@Var{c}]}
@@ -8931,8 +8932,7 @@ any.
 @cindex @code{\t}, and copy mode
 @cindex copy mode, and @code{\t}
 @cindex mode, copy, and @code{\t}
-This escape sequence is a non-interpreted tab character.  In copy mode
-(@pxref{Copy Mode}), @code{\t} is the same as a real tab character.
+Interpolate a tab in copy mode.
 @endDefesc
 
 @DefreqList {ta, [[@Var{n1} @Var{n2} @dots{} @Var{nn} ]@t{T} @Var{r1} @
@@ -9157,9 +9157,7 @@ period @samp{.}.
 @cindex @code{\a}, and copy mode
 @cindex copy mode, and @code{\a}
 @cindex mode, copy, and @code{\a}
-This escape sequence is a non-interpreted leader character.  In copy
-mode (@pxref{Copy Mode}), @code{\a} is the same as a real leader
-character.
+Interpolate a leader in copy mode.
 @endDefesc
 
 @Defreq {lc, [@Var{fill-glyph}]}
@@ -16297,17 +16295,6 @@ source document.
 Send @var{contents}, which consumes the remainder of the input line, to
 the standard error stream.
 
-@cindex @code{tm} request, and copy mode
-@cindex copy mode, and @code{tm} request
-@cindex mode, copy, and @code{tm} request
-@cindex @code{tm1} request, and copy mode
-@cindex copy mode, and @code{tm1} request
-@cindex mode, copy, and @code{tm1} request
-@cindex @code{tmc} request, and copy mode
-@cindex copy mode, and @code{tmc} request
-@cindex mode, copy, and @code{tmc} request
-@var{contents} is read in copy mode.
-
 The @code{tm} request ignores leading spaces of @var{contents};
 @code{tm1} handles its argument similarly to the @code{ds} request: an
 initial neutral double quote is stripped to allow embedding of leading
diff --git a/man/groff.7.man b/man/groff.7.man
index 8c864ccbb..d34e2334f 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -2843,7 +2843,7 @@ after the end of input.
 .
 .TPx
 .REQ .eo
-Disable the escape mechanism.
+Disable the escape mechanism in interpretation mode.
 .
 .
 .TPx
@@ -4492,8 +4492,7 @@ and
 .
 .TP
 .ESC a
-In copy mode,
-interpolate leader character.
+Interpolate a leader in copy mode.
 .
 .TP
 .ESCq A anything
@@ -4553,7 +4552,7 @@ see
 .
 .TP
 .ESC e
-Interpolate the glyph corresponding to the escape character.
+Interpolate the escape character.
 .
 .
 .TP
@@ -4909,8 +4908,7 @@ the direction of text flow is positive.
 .
 .TP
 .ESC t
-In copy mode,
-interpolate tab character.
+Interpolate a tab in copy mode.
 .
 .
 .TP