[groff] 02/17: [docs]: Clarify device control command behavior.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 78ca4f2457a63888efae697bbbefd663ff9326af
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Tue Jan 16 09:50:36 2024 -0600

    [docs]: Clarify device control command behavior.
    
    Revise discussion of `device` and `devicem` requests and `\X` and `\Y`
    escape sequences.
    
    Drop now-redundant subsection "Device control commands" from groff(7).
    The new section "Postprocessor access" covers the subject.
    
    Continues commit 9dbf227a5b, 13 January.
---
 doc/groff.texi       | 55 +++++++++++++++++++++++++++-------------------------
 man/groff.7.man      | 53 +++++++++++++-------------------------------------
 man/groff_diff.7.man | 15 ++++++--------
 3 files changed, 48 insertions(+), 75 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 4ffb9cc20..bf46f9db8 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -16429,13 +16429,15 @@ the embedding of hyperlinks and image files.  
Device-specific functions
 are documented in each output driver's man page, such as
 @cite{gropdf@r{(1)}}, @cite{grops@r{(1)}}, or @cite{grotty@r{(1)}}.
 
-@DefreqList {device, xxx @r{@dots{}}}
-@DefescListEndx {\\X, @code{'}, xxx @r{@dots{}}, @code{'}}
-Embed all @var{xxx} arguments into GNU @command{troff} output as
-parameters to an @w{@samp{x X}} device control
-command.@footnote{@xref{gtroff Output}.}  The meaning and interpretation
-of such parameters is determined by the output driver or other
-postprocessor.
+@DefreqList {device, [@code{"}]@Var{contents}}
+@c XXX: Can't mark the parameters with @Var because @Var gets called
+@c recursively if we do.
+@c @DefescListEndx {\\X, @code{'}, @Var{contents}, @code{'}}
+@DefescListEndx {\\X, @code{'}, contents, @code{'}}
+Embed @var{contents} into GNU @command{troff} output as parameters to an
+@w{@samp{x X}} device control command.@footnote{@xref{gtroff Output}.}
+The interpretation of such parameters is determined by the output driver
+or other postprocessor.
 
 The @code{device} request strips an initial neutral double quote from
 @var{contents} to allow embedding of leading spaces.
@@ -16451,16 +16453,16 @@ The @code{device} request strips an initial neutral 
double quote from
 @end ifinfo
 Within a device control command, the escape sequences @code{\&},
 @code{\)}, @code{\%}, and @code{\:} are ignored; @code{\@key{SPC}} and
-@code{\~} are converted to single space characters; and @code{\\} has
-its escape character stripped.  So that the basic Latin subset of the
-Unicode character set@footnote{that is, ISO@tie{}646:1991-IRV or,
-popularly, ``US-ASCII''} can be reliably encoded in device control
-commands, seven special character escape sequences (@samp{\-},
-@samp{\[aq]}, @samp{\[dq]}, @samp{\[ga]}, @samp{\[ha]}, @samp{\[rs]},
-and @samp{\[ti]}) are mapped to basic Latin characters; see the
-@cite{groff_char@r{(7)}} man page.  For this transformation, character
-translations and special character definitions are
-ignored.@footnote{They are bypassed because these parameters are not
+@code{\~} are converted to single space characters; and a self-escaped
+escape character is output as a backslash @code{\}.  So that the basic
+Latin subset of the Unicode character set@footnote{that is,
+ISO@tie{}646:1991-IRV or, popularly, ``US-ASCII''} can be reliably
+encoded in device control commands, seven special character escape
+sequences (@samp{\-}, @samp{\[aq]}, @samp{\[dq]}, @samp{\[ga]},
+@samp{\[ha]}, @samp{\[rs]}, and @samp{\[ti]}) are mapped to basic Latin
+characters; see the @cite{groff_char@r{(7)}} man page.  For this
+transformation, character translations and special character definitions
+are ignored.@footnote{They are bypassed because these parameters are not
 rendered as glyphs in the output; instead, they remain abstract
 characters---in a PDF bookmark or a URL, for example.}
 
@@ -16491,15 +16493,16 @@ as a device control command.
 @DefescItemx {\\Y, , n, }
 @DefescItem {\\Y, (, nm, }
 @DefescListEnd {\\Y, [, name, ]}
-This is approximately equivalent to @samp{\X'\*[@var{name}]'}
-(one-character name@tie{}@var{n}, two-character name @var{nm}).
-However, the contents of the string or macro @var{name} are not
-interpreted; it is also permitted for @var{name} to have been defined as
-a macro and thus contain newlines.  (There is no way to embed a newline
-in the arguments to @code{device} or @code{\X}.)  The inclusion of
-newlines requires an extension to the @acronym{AT&T} @command{troff}
-output format; their presence confuses drivers that do not know about it
-(@pxref{Device Control Commands}).
+The @code{devicem} request and @code{\Y} escape sequence are each
+approximately equivalent to @samp{\X'\*[@var{name}]'} (one-character
+name@tie{}@var{n}, two-character name @var{nm}).  They differ from that
+construction in that the contents of the string or macro @var{name} are
+not interpreted; further, @var{name} may be a macro and thus contain
+newlines.  (There is no way to embed a newline in the arguments to
+@code{device} or @code{\X}.)  The inclusion of newlines requires an
+extension to the @acronym{AT&T} @command{troff} output format; their
+presence confuses drivers that do not know about it (@pxref{Device
+Control Commands}).
 @endDefesc
 
 @DefreqList {tag, name}
diff --git a/man/groff.7.man b/man/groff.7.man
index 4f2e25647..c0ffc5b79 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -2981,9 +2981,9 @@ As
 with compatibility mode disabled when the macro is interpreted.
 .
 .TPx
-.REQ .device anything
+.REQ .device contents
 Write
-.I anything
+.I contents
 to
 .I @g@troff
 output as a device control command.
@@ -5375,9 +5375,9 @@ negative before,
 positive after).
 .
 .TP
-.ESCq X anything
+.ESCq X contents
 Write
-.I anything
+.I contents
 to
 .I @g@troff
 output as a device control command.
@@ -5624,32 +5624,6 @@ this is the default.
 .
 .
 .\" ====================================================================
-.SS "Device control commands"
-.\" ====================================================================
-.
-The
-.B .device
-and
-.B .devicem
-requests,
-and
-.B \[rs]X
-and
-.B \[rs]Y
-escape sequences,
-enable documents to pass information directly to a postprocessor.
-.
-These are useful for
-exercising device-specific capabilities that the
-.I groff
-language does not abstract or generalize;
-such functions include the embedding of hyperlinks and image files.
-.
-Device-specific functions are documented in
-each output driver's man page.
-.
-.
-.\" ====================================================================
 .SH Strings
 .\" ====================================================================
 .
@@ -7824,8 +7798,8 @@ device control command
 (see
 .MR groff_out @MAN5EXT@ ).
 .
-The meaning and interpretation of such parameters is determined by the
-output driver or other postprocessor.
+The interpretation of such parameters is determined by the output driver
+or other postprocessor.
 .
 .
 .P
@@ -7841,9 +7815,8 @@ are ignored;
 and
 .B \[rs]\[ti]
 are converted to single space characters;
-and @code{\\} has
-.B \[rs]\[rs]
-its escape character stripped.
+and a self-escaped escape character is output as a backslash
+.BR \[rs] .
 .
 So that the basic Latin subset of the Unicode character set
 (that is,
@@ -7925,18 +7898,18 @@ The
 request
 and
 .B \[rs]Y
-escape sequence are approximately equivalent to
+escape sequence are each approximately equivalent to
 .RB \[lq] \[rs]X\[aq]\c
 .IB name \[aq]\c
 \[rq].
 .
-However,
-the contents of the string or macro
+They differ from that construction in that the contents of the string or
+macro
 .I name
 are not interpreted;
-it is also permitted for
+futher,
 .I name
-to have been defined as a macro and thus contain newlines.
+may be a macro and thus contain newlines.
 .
 (There is no way to embed a newline
 in the arguments to
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index 1ff305aed..5312175b0 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -1056,10 +1056,9 @@ is interpreted even in copy mode.
 .
 .
 .TP
-.BI \[rs]X\[aq] anything \[aq]
+.BI \[rs]X\[aq] contents \[aq]
 Within
-.B \[rs]X
-arguments,
+.I contents,
 the escape sequences
 .BR \[rs]& ,
 .BR \[rs]) ,
@@ -1071,9 +1070,7 @@ are ignored;
 and
 .B \[rs]\[ti]
 are converted to single space characters;
-and
-.B \[rs]\[rs]
-is reduced to
+and a self-escaped escape character is output as a backslash
 .BR \[rs] .
 .
 So that the basic Latin subset of the Unicode character set
@@ -1082,7 +1079,7 @@ ISO\~646:1991-IRV or,
 popularly,
 \[lq]US-ASCII\[rq])
 can be reliably encoded in
-.I anything,
+.I contents,
 the special character escape sequences
 .BR \[rs]\- ,
 .BR \[rs][aq] ,
@@ -2218,9 +2215,9 @@ is interpreted.
 .
 .
 .TP
-.BI .device\~ anything
+.BI .device\~ contents
 Write
-.IR anything ,
+.IR contents ,
 read in copy mode,
 to
 .I @g@troff