From 4de8241a6ce57bf2595ce466c1bf7eea24487c2e Mon Sep 17 00:00:00 2001
From: "G. Branden Robinson" <g.branden.robinson@gmail.com>
Date: Fri, 12 Jan 2024 14:22:37 -0600
Subject: [docs]: Update explanation of copy mode.

Finally, one I am happy with.
---
 doc/groff.texi  | 22 +++++++++++++---------
 man/groff.7.man | 29 +++++++++++++++++------------
 2 files changed, 30 insertions(+), 21 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 5b1b99de5..93a86b202 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -13661,15 +13661,19 @@ Applying string interpolation to a macro does not change this name.
 @cindex mode, copy
 @cindex mode, copy
 
-When GNU @code{troff} processes certain requests, most importantly those
-which define or append to a macro or string, it does so in @dfn{copy
-mode}: it copies the characters of the definition into a dedicated
-storage region, interpolating the escape sequences @code{\n}, @code{\g},
-@code{\$}, @code{\*}, @code{\V}, and @code{\?} normally; interpreting
-@code{\@key{RET}} immediately; discarding comments @code{\"} and
-@code{\#}; interpolating the current leader, escape, or tab character
-with @code{\a}, @code{\e}, and @code{\t}, respectively; and storing all
-other escape sequences in an encoded form.
+GNU @code{troff} processes certain requests in @dfn{copy mode}: it
+interpolates the escape sequences @code{\n}, @code{\g}, @code{\$},
+@code{\*}, @code{\V}, and @code{\?} normally; interprets
+@code{\@key{RET}} immediately; discards comments @code{\"} and
+@code{\#}; interpolates the current leader, escape, or tab character
+with @code{\a}, @code{\e}, and @code{\t}, respectively; and represents
+all other escape sequences in an encoded form.  The term ``copy mode''
+reflects its most visible application in requests that populate macros
+and strings, but other requests also use it when interpreting arguments
+that can't meaningfully represent typesetting operations.  For example,
+a font selection escape sequence has no meaning in a hyphenation pattern
+file name (@code{hpf}) or a diagnostic message written to the terminal
+(@code{tm}).
 
 @cindex interpretation mode
 @cindex mode, interpretation
diff --git a/man/groff.7.man b/man/groff.7.man
index 7538dd51b..6e8e6974a 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -7158,15 +7158,10 @@ Applying string interpolation to a macro does not change this name.
 .SS "Copy mode"
 .\" ====================================================================
 .
-When
 .I @g@troff
-processes certain requests,
-most importantly those which define or append to a macro or string,
-it does so in
-.IR "copy mode" :
-it copies the characters of the definition into a dedicated storage
-region,
-interpolating the escape sequences
+processes certain requests in
+.I "copy mode:"
+it interpolates the escape sequences
 .BR \[rs]n ,
 .BR \[rs]g ,
 .BR \[rs]$ ,
@@ -7175,14 +7170,14 @@ interpolating the escape sequences
 and
 .B \[rs]?\&
 normally;
-interpreting
+interprets
 .BI \[rs] newline
 immediately;
-discarding comments
+discards comments
 .B \[rs]"
 and
 .BR \[rs]# ;
-interpolating the current leader,
+interpolates the current leader,
 escape,
 or tab character with
 .BR \[rs]a ,
@@ -7190,7 +7185,17 @@ or tab character with
 and
 .BR \[rs]t ,
 respectively;
-and storing all other escape sequences in an encoded form.
+and represents all other escape sequences in an encoded form.
+The term \[lq]copy mode\[rq] reflects its most visible application in
+requests that populate macros and strings,
+but other requests also use it when interpreting arguments that can't
+meaningfully represent typesetting operations.
+For example,
+a font selection escape sequence has no meaning in a hyphenation pattern
+file name
+.RB ( hpf )
+or a diagnostic message written to the terminal
+.RB ( tm ).
 .
 The complement of copy mode\[em]a
 .I roff
-- 
cgit v1.2.3