1 files changed, 34 insertions, 31 deletions
diff --git a/doc/groff.texi b/doc/groff.texi
index 93a86b202..6e2e1cc3e 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -16421,36 +16421,34 @@ returned by the function @cite{getenv@r{(3)}}.
 @cindex access to postprocessor
 
 Two escape sequences and two requests enable documents to pass
-information directly to a postprocessor.  These are useful for
-exercising device-specific capabilities that the @code{groff} language
-does not abstract or generalize; examples include 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)}}.
+information directly to an output driver or other postprocessor.  These
+are useful for exercising device-specific capabilities that the
+@code{groff} language does not abstract or generalize; examples include
+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 a device control command @w{@samp{x X}}.  The meaning and
-interpretation of such parameters is determined by the output driver or
-other postprocessor.
-
-@cindex @code{device} request, and copy mode
-@cindex copy mode, and @code{device} request
-@cindex mode, copy, and @code{device} request
-The @code{device} request processes its arguments in copy mode
-(@pxref{Copy Mode}).  An initial neutral double quote in @var{contents}
-is stripped to allow embedding of leading spaces.
-@cindex @code{\&}, in @code{\X}
-@cindex @code{\)}, in @code{\X}
-@cindex @code{\%}, in @code{\X}
+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.
+
+The @code{device} request strips an initial neutral double quote from
+@var{contents} to allow embedding of leading spaces.
+
+@cindex @code{\&}, in device control commands
+@cindex @code{\)}, in device control commands
+@cindex @code{\%}, in device control commands
 @ifnotinfo
-@cindex @code{\:}, in @code{\X}
+@cindex @code{\:}, in device control commands
 @end ifnotinfo
 @ifinfo
-@cindex @code{\@r{<colon>}}, in @code{\X}
+@cindex @code{\@r{<colon>}}, in device control commands
 @end ifinfo
-By contrast, within @code{\X} arguments, the escape sequences @code{\&},
+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
@@ -16458,13 +16456,15 @@ 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
+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.} The use of any
-other escape sequence in @code{\X} parameters is normally an error.
+characters---in a PDF bookmark or a URL, for example.}
+
+Escape sequences other than the foregoing in device control command
+may be ignored, or produce an error.
 
 A device control command issued with the @code{device} request will not
 be reflected in the output unless a partially collected line exists at
@@ -16483,6 +16483,9 @@ discussed above).  @code{use_charnames_in_special} is currently employed
 only by @code{grohtml}.
 @endDefesc
 
+GNU @command{troff} also permits the interpolatation of macro contents
+as a device control command.
+
 @DefreqList {devicem, name}
 @DefescItemx {\\Y, , n, }
 @DefescItem {\\Y, (, nm, }
@@ -16490,12 +16493,12 @@ only by @code{grohtml}.
 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; also it is permitted for @var{name} to have been defined as
-a macro and thus contain newlines (it is not permitted for the argument
-to @code{\X} to contain newlines).  The inclusion of newlines requires
-an extension to the @acronym{AT&T} @command{troff} output format, and
-confuses drivers that do not know about this extension (@pxref{Device
-Control Commands}).
+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}).
 @endDefesc
 
 @DefreqList {tag, name}