[groff] 32/50: [docs]: Update and sync device control stuff.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit d8910a97e32caecf1682bdf20455763368dfaa94
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Thu May 19 21:43:07 2022 -0500

    [docs]: Update and sync device control stuff.
    
    * doc/groff.texi (Postprocessor Access): Flesh out introduction;
      motivate the feature better.  Indicate where details can be found.
      Mark node as reviewed for correct glyph usage.  Move cross reference
      to introductory paragraph.
      <device>: Document request's handling of leading double quote in
      argument.  Convert erroneous uses of program index to concept index
      entries.  Drop now-redundant sentence about handling of `\\` input
      sequence in device control escape or request arguments.
      <devicem>: Use `name` as metasyntactic variable name since it is the
      name of a macro, and matches the argument label in the adjacent `\Y[]`
      form.
    
    * man/groff.7.man (Request short reference) <device, devicem>:
      (Escape short reference) <\X, \Y>:
    * man/groff_diff.7.man (Escape sequences) <\X>:
      (New requests) <device, devicem>: Sync with information in our Texinfo
      manual.
    
    Also fix style nit: use semicolons to separate list items that already
    contain commas.
---
 doc/groff.texi       | 32 ++++++++++---------
 man/groff.7.man      | 34 ++++++++++----------
 man/groff_diff.7.man | 88 +++++++++++++++++++++++++++++++++++++++++++++++-----
 3 files changed, 114 insertions(+), 40 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index c16d5691..cfe08abe 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -15446,9 +15446,6 @@ returned by the function @code{getenv}.  @code{\V} is 
interpreted even
 in copy mode (@pxref{Copy Mode}).
 @endDefesc
 
-@codequotebacktick off
-@codequoteundirected off
-
 
 @c =====================================================================
 
@@ -15457,9 +15454,13 @@ in copy mode (@pxref{Copy Mode}).
 @cindex postprocessor access
 @cindex access to postprocessor
 
-There are two escape sequences that give information directly to the
-postprocessor.  This is particularly useful for embedding PostScript
-into the final document.
+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)}}.  @xref{Output Devices}.
 
 @DefreqList {device, xxx @r{@dots{}}}
 @DefescListEndx {\\X, @code{'}, xxx @r{@dots{}}, @code{'}}
@@ -15472,7 +15473,8 @@ other postprocessor.
 @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}).
+(@pxref{Copy Mode}).  A leading @code{"} is stripped; this enables
+@var{xxx} to contain leading spaces.
 @cindex @code{\&}, in @code{\X}
 @cindex @code{\)}, in @code{\X}
 @cindex @code{\%}, in @code{\X}
@@ -15483,8 +15485,8 @@ The @code{device} request processes its arguments in 
copy mode
 @cindex @code{\@r{<colon>}}, in @code{\X}
 @end ifinfo
 By contrast, within @code{\X} arguments, the escape sequences @code{\&},
-@code{\)}, @code{\%}, and @code{\:} are ignored, @code{\SP} and
-@code{\~} are converted to single space characters, and @code{\\} has
+@code{\)}, @code{\%}, and @code{\:} are ignored; @code{\SP} 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
@@ -15495,18 +15497,17 @@ commands, seven special character escape sequences 
(@samp{\-},
 in @code{\X} arguments is normally an error.
 
 @kindex use_charnames_in_special
-@pindex DESC@r{, and @code{use_charnames_in_special}}
+@cindex @file{DESC} file, and @code{use_charnames_in_special} keyword
 @cindex @code{\X}, and special characters
 If the @code{use_charnames_in_special} directive appears in the output
 device's @file{DESC} file, the use of special character escape sequences
 is @emph{not} an error; they are simply output verbatim (with the
 exception of the seven mapped to Unicode basic Latin characters,
-discussed above).  For convenience, the backslash can be represented as
-@samp{\\}.  @code{use_charnames_in_special} is currently used only by
-@code{grohtml}.
+discussed above).  @code{use_charnames_in_special} is currently employed
+only by @code{grohtml}.
 @endDefesc
 
-@DefreqList {devicem, xx}
+@DefreqList {devicem, name}
 @DefescItemx {\\Y, , n, }
 @DefescItem {\\Y, (, nm, }
 @DefescListEnd {\\Y, [, name, ]}
@@ -15521,7 +15522,8 @@ confuses drivers that do not know about this extension 
(@pxref{Device
 Control Commands}).
 @endDefesc
 
-@xref{Output Devices}.
+@codequotebacktick off
+@codequoteundirected off
 
 
 @c =====================================================================
diff --git a/man/groff.7.man b/man/groff.7.man
index 47ec2b49..a02d14cf 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -2023,14 +2023,15 @@ but disable compatibility mode during macro expansion.
 .TPx
 .REQ .device "anything"
 Write
-.I anything
-to the intermediate output as a device control function.
+.IR anything ,
+read in copy mode,
+to the intermediate output as a device control command.
 .
 .TPx
 .REQ .devicem "name"
 Write contents of macro or string
 .I name
-uninterpreted to the intermediate output as a device control function.
+to the intermediate output as a device control command.
 .
 .
 .TPx
@@ -4350,32 +4351,31 @@ positive after).
 .
 .TP
 .ESCq X anything
-Send
-.I anything
-to the output device as a control command;
-see
-.MR groff_out @MAN5EXT@ .
+Write
+.IR anything ,
+read in copy mode,
+to the intermediate output as a device control command.
 .
 .
 .TP
 .ESC Y n
-Send interpolation of string or macro with one-character
-.RI name\~ n
-to the output device as a control command.
+Write contents of macro or string
+.I n
+to the intermediate output as a device control command.
 .
 .
 .TP
 .ESC Y( nm
-Send interpolation of string or macro with two-character
-.RI name\~ nm
-to the output device as a control command.
+Write contents of macro or string
+.I nm
+to the intermediate output as a device control command.
 .
 .
 .TP
 .ESC[] Y name
-Send interpolation of string or macro with arbitrarily long
-.RI name\~ name
-to the output device as a control command.
+Write contents of macro or string
+.I name
+to the intermediate output as a device control command.
 .
 .
 .TP
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index cebed86d..7f75f6ba 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -759,6 +759,69 @@ is interpreted even in copy mode.
 .
 .
 .TP
+.BI \[rs]X\[aq] anything \[aq]
+Within
+.B \[rs]X
+arguments,
+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
+(that is,
+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]\- ,
+.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;
+see
+.MR groff_char @MAN7EXT@ .
+.
+The use of any other escape sequence in
+.B \[rs]X
+arguments is normally an error.
+.
+.
+.IP
+If the
+.B use_charnames_in_special
+directive appears in the output device's
+.I DESC
+file,
+the use of special character escape sequences is
+.I not
+an error;
+they are simply output verbatim
+(with the exception of the seven mapped to Unicode basic Latin
+characters,
+discussed above).
+.
+.B use_charnames_in_special
+is currently employed only by
+.MR grohtml @MAN1EXT@ .
+.
+.
+.TP
 .BI \[rs]Y x
 .TQ
 .BI \[rs]Y( xx
@@ -1895,20 +1958,29 @@ is executed.
 .
 .TP
 .BI .device\~ anything
-This is (almost) the same as the
+This request performs (almost) the same operation as the
 .B \[rs]X
 escape sequence.
+.
 .I anything
-is read in copy mode; a leading\~\c
-.B \[dq]
-is stripped.
+is read in copy mode.
+.
+A
+.RB leading\~ \[dq]
+is stripped;
+this enables
+.I anything
+to contain leading spaces.
+.
 .
 .TP
-.BI .devicem\~ xx
-This is the same as the
+.BI .devicem\~ name
+This request performs the same operation as the
 .B \[rs]Y
-escape (to embed the contents of a macro into the intermediate
-output preceded with \[oq]x\~X\[cq]).
+escape sequence,
+embedding the contents of a macro in the intermediate output as a
+.RB \[lq] "x X" \[rq]
+device control command.
 .
 .
 .TP