[groff] 10/17: [docs]: Update, sync device control command stuff.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 50ba96d17e13bfb0a33a84c4f1b704fb22dc7ad9
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Tue Jun 6 22:27:40 2023 -0500

    [docs]: Update, sync device control command stuff.
---
 doc/groff.texi       |  2 +-
 man/groff.7.man      | 95 +++++++++++++++++++++++++++++++++++++++++++++-------
 man/groff_diff.7.man | 46 +++++++++++++------------
 3 files changed, 107 insertions(+), 36 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index b42ccac41..3a02a97ed 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -16141,7 +16141,7 @@ 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} arguments is normally an error.
+other escape sequence in @code{\X} parameters is normally an error.
 
 @kindex use_charnames_in_special
 @cindex @file{DESC} file, and @code{use_charnames_in_special} keyword
diff --git a/man/groff.7.man b/man/groff.7.man
index 925a129fa..4dd6d913c 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -2908,20 +2908,25 @@ As
 .request ".dei\~\f[I]macro\~end\f[]" ,
 but disable compatibility mode during macro expansion.
 .
-.
 .TPx
 .REQ .device "anything"
 Write
 .IR anything ,
 read in copy mode,
-to the intermediate output as a device control command.
+to
+.I @g@troff
+output as a device control command.
+.
+An initial neutral double quote is stripped to allow embedding of
+leading spaces.
 .
 .TPx
 .REQ .devicem "name"
 Write contents of macro or string
 .I name
-to the intermediate output as a device control command.
-.
+to
+.I @g@troff
+output as a device control command.
 .
 .TPx
 .REQ .di
@@ -5288,35 +5293,73 @@ Increase vertical spacing of pending output line by
 negative before,
 positive after).
 .
-.
 .TP
 .ESCq X anything
 Write
+.I anything
+to
+.I @g@troff
+output as a device control command.
+.
+Within
 .IR anything ,
-read in copy mode,
-to the intermediate output as a device control command.
+the escape sequences
+.BR \[rs]& ,
+.BR \[rs]) ,
+.BR \[rs]% ,
+and
+.B \[rs]:
+are ignored;
+.BI \[rs] space
+and
+.B \[rs]\[ti]
+are converted to single space characters;
+and
+.B \[rs]\[rs]
+has its escape character stripped.
 .
+So that the basic Latin subset of the Unicode character
+set can be reliably encoded in
+.I anything,
+the special character escape sequences
+.BR \[rs]\- ,
+.BR \[rs][aq] ,
+.BR \[rs][dq] ,
+.BR \[rs][ga] ,
+.BR \[rs][ha] ,
+.BR \[rs][rs] ,
+and
+.B \[rs][ti]
+are mapped to basic Latin characters;
+see
+.MR groff_char @MAN7EXT@ .
+.
+For this transformation,
+character translations and special character definitions are ignored.
 .
 .TP
 .ESC Y n
 Write contents of macro or string
 .I n
-to the intermediate output as a device control command.
-.
+to
+.I @g@troff
+output as a device control command.
 .
 .TP
 .ESC Y( nm
 Write contents of macro or string
 .I nm
-to the intermediate output as a device control command.
-.
+to
+.I @g@troff
+output as a device control command.
 .
 .TP
 .ESC[] Y name
 Write contents of macro or string
 .I name
-to the intermediate output as a device control command.
-.
+to
+.I @g@troff
+output as a device control command.
 .
 .TP
 .ESC z c
@@ -5501,6 +5544,32 @@ 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;
+examples include the embedding of hyperlinks and image files.
+.
+Device-specific functions are documented in
+each output driver's man page.
+.
+.
+.\" ====================================================================
 .SH Strings
 .\" ====================================================================
 .
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index 75b40b940..f9c8e07bf 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -936,23 +936,27 @@ So that the basic Latin subset of the Unicode character 
set
 ISO\~646:1991-IRV or,
 popularly,
 \[lq]US-ASCII\[rq])
-can be reliably encoded in device control commands,
-seven special character escape sequences
-.RB ( \[rs]\- ,
+can be reliably encoded in
+.I anything,
+the special character escape sequences
+.BR \[rs]\- ,
 .BR \[rs][aq] ,
 .BR \[rs][dq] ,
 .BR \[rs][ga] ,
 .BR \[rs][ha] ,
 .BR \[rs][rs] ,
 and
-.BR \[rs][ti] )
-are mapped to basic Latin glyphs;
+.B \[rs][ti]
+are mapped to basic Latin characters;
 see
 .MR groff_char @MAN7EXT@ .
 .
+For this transformation,
+character translations and special character definitions are ignored.
+.
 The use of any other escape sequence in
 .B \[rs]X
-arguments is normally an error.
+parameters is normally an error.
 .
 .
 .IP
@@ -2152,27 +2156,25 @@ is executed.
 .
 .
 .TP
-.BI .device\~ contents
-This request performs (almost) the same operation as the
-.B \[rs]X
-escape sequence.
-.
-.I contents
-is read in copy mode.
+.BI .device\~ anything
+Write
+.IR anything ,
+read in copy mode,
+to
+.I @g@troff
+output as a device control command.
 .
-An initial neutral double quote in
-.I contents
-is stripped off to allow embedding of leading spaces.
+An initial neutral double quote is stripped to allow embedding of
+leading spaces.
 .
 .
 .TP
 .BI .devicem\~ name
-This request performs the same operation as the
-.B \[rs]Y
-escape sequence,
-embedding the contents of a macro in the intermediate output as a
-.RB \[lq] "x X" \[rq]
-device control command.
+Write contents of macro or string
+.I name
+to
+.I @g@troff
+output as a device control command.
 .
 .
 .TP