[groff] 12/60: [doc,man]: Migrate to "device extension".

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit b6c4802082a3ad076c22ed8a8cd1bcfc6e2acf37
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sun Sep 8 05:26:09 2024 -0500

    [doc,man]: Migrate to "device extension".
---
 doc/groff.texi.in               | 46 ++++++++++++++++++++---------------------
 man/groff.7.man                 | 16 +++++++-------
 man/groff_diff.7.man            |  8 +++----
 man/groff_font.5.man            |  4 +++-
 man/groff_out.5.man             |  6 +++---
 man/groff_tmac.5.man            |  2 +-
 src/devices/grodvi/grodvi.1.man |  6 +++---
 src/devices/gropdf/gropdf.1.man |  2 +-
 src/devices/grops/grops.1.man   |  5 +++++
 src/devices/grotty/grotty.1.man | 13 +++++++-----
 10 files changed, 59 insertions(+), 49 deletions(-)

diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index 3e618e7be..8a2222838 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -1094,7 +1094,7 @@ requests.
 @item
 Output drivers may search for files; for instance, @command{grops} looks
 for files named in @samp{\X'ps: import @r{@dots{}}'}, @samp{\X'ps: file
-@r{@dots{}}'}, and @samp{\X'pdf: pdfpic @r{@dots{}}'} device control
+@r{@dots{}}'}, and @samp{\X'pdf: pdfpic @r{@dots{}}'} device extension
 escape sequences.
 @end itemize
 
@@ -16599,7 +16599,7 @@ each output driver's man page, such as 
@cite{gropdf@r{(1)}},
 @DefreqList {device, [@code{"}]@Var{contents}}
 @DefescListEndx {\\X, @code{'}, contents @r{@dots{}}, @code{'}}
 Embed @var{contents} into GNU @command{troff} output as parameters to an
-@w{@samp{x X}} device control command.@footnote{@xref{gtroff Output}.}
+@w{@samp{x X}} device extension command.@footnote{@xref{gtroff Output}.}
 The interpretation of such parameters is determined by the output driver
 or other postprocessor.
 
@@ -16613,16 +16613,16 @@ 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 nodes, in device control commands
-@cindex special characters, in device control commands
-@cindex @code{\&}, in device control commands
-@cindex @code{\)}, in device control commands
-@cindex @code{\%}, in device control commands
+@cindex nodes, in device extension commands
+@cindex special characters, in device extension commands
+@cindex @code{\&}, in device extension commands
+@cindex @code{\)}, in device extension commands
+@cindex @code{\%}, in device extension commands
 @ifnotinfo
-@cindex @code{\:}, in device control commands
+@cindex @code{\:}, in device extension commands
 @end ifnotinfo
 @ifinfo
-@cindex @code{\@r{<colon>}}, in device control commands
+@cindex @code{\@r{<colon>}}, in device extension commands
 @end ifinfo
 The @code{groff} special character repertoire is unknown to output
 drivers outside of glyphs named in a device's fonts, and even then they
@@ -16636,7 +16636,7 @@ as might be done when writing out tag names for PDF 
bookmarks, which can
 appear in a viewer's navigation pane.
 
 So that documents or macro packages do not have to laboriously
-``sanitize'' strings destined for interpolation in device control
+``sanitize'' strings destined for interpolation in device extension
 commands, the @code{\X} escape sequence
 @c XXX: and soon other things
 performs certain transformations on its argument.  For these
@@ -16645,7 +16645,7 @@ transformations, character translations and definitions 
are ignored.
 GNU @command{troff} converts several ordinary characters that typeset as
 non-basic Latin code points to code points outside that range so that
 they are used consistently whether they are formatted as glyphs or used
-in a device control command argument.  These ordinary characters are
+in a device extension command argument.  These ordinary characters are
 @samp{'}, @samp{-}, @samp{^}, @samp{`}, and @samp{~}; others are written
 as-is.
 
@@ -16662,7 +16662,7 @@ characters, produce warnings in category @samp{char}.
 @endDefesc
 
 GNU @command{troff} also permits the interpolation of macro contents
-as a device control command.
+as a device extension command.
 
 @DefreqList {devicem, name}
 @DefescItemx {\\Y, , n, }
@@ -18106,14 +18106,14 @@ fortunately, in @command{gtroff}'s intermediate 
output, every command
 with at least one argument is followed by a line break, thus providing
 excellent readability.
 
-The other commands---those for drawing and device controlling---have a
-more complicated structure; some recognize long command names, and some
-take a variable number of arguments.  So all @samp{D} and @samp{x}
-commands were designed to request a syntactical line break after their
-last argument.  Only one command, @w{@samp{x X}}, has an argument that
-can span several input lines; all other commands must have all of
-their arguments on the same line as the command, i.e., the arguments may
-not be split by a line break.
+The other commands---those for drawing and device control---have a more
+complicated structure; some recognize long command names, and some take
+a variable number of arguments.  So all @samp{D} and @samp{x} commands
+were designed to request a syntactical line break after their last
+argument.  Only one command, @w{@samp{x X}}, has an argument that can
+span several input lines; all other commands must have all of their
+arguments on the same line as the command, i.e., the arguments may not
+be split by a line break.
 
 Empty lines (these are lines containing only space and/or a comment),
 can occur everywhere.  They are just ignored.
@@ -19085,9 +19085,9 @@ The @code{grohtml} driver uses this directive.
 @c XXX: Savannah #63074 is trying to make this obsolescent.
 @item use_charnames_in_special
 @kindex use_charnames_in_special
-GNU @code{troff} should encode special characters inside device control
-commands; see @ref{Postprocessor Access}.  The @code{grohtml} driver
-uses this directive.
+GNU @code{troff} should encode special characters in arguments to device
+extension commands; see @ref{Postprocessor Access}.  The @code{grohtml}
+driver uses this directive.
 
 @item vert @var{n}
 @kindex vert
diff --git a/man/groff.7.man b/man/groff.7.man
index 5cd228684..777d1c206 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -3021,7 +3021,7 @@ Write
 read in copy mode,
 to
 .I @g@troff
-output as a device control command.
+output as a device extension command.
 .
 A leading neutral double quote is stripped to allow embedding of
 leading spaces.
@@ -3032,7 +3032,7 @@ Write contents of macro or string
 .I name
 to
 .I @g@troff
-output as a device control command.
+output as a device extension command.
 .
 .TPx
 .REQ .di
@@ -5652,7 +5652,7 @@ which can appear in a viewer's navigation pane.
 .\"IP
 So that documents or macro packages do not have to laboriously
 \[lq]sanitize\[rq] strings destined for interpolation
-in device control commands,
+in device extension commands,
 this escape sequence
 .\" XXX: and soon other things
 performs certain transformations on its argument.
@@ -5707,7 +5707,7 @@ Write contents of macro or string
 .I n
 to
 .I @g@troff
-output as a device control command.
+output as a device extension command.
 .
 .TP
 .ESC Y( nm
@@ -5715,7 +5715,7 @@ Write contents of macro or string
 .I nm
 to
 .I @g@troff
-output as a device control command.
+output as a device extension command.
 .
 .TP
 .ESC[] Y name
@@ -5723,7 +5723,7 @@ Write contents of macro or string
 .I name
 to
 .I @g@troff
-output as a device control command.
+output as a device extension command.
 .
 .TP
 .ESC z c
@@ -8178,7 +8178,7 @@ escape sequence embed their arguments into GNU
 .I troff \" GNU
 output as parameters to an
 .RB \[lq] "x X" \[rq]
-device control command
+device extension command
 (see
 .MR groff_out @MAN5EXT@ ).
 .
@@ -8189,7 +8189,7 @@ or other postprocessor.
 .P
 GNU
 .I troff \" GNU
-also permits the interpolation of macro contents as a device control
+also permits the interpolation of macro contents as a device extension
 command.
 .
 The
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index 4d99c3eb9..a7521cfb3 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -1123,7 +1123,7 @@ which can appear in a viewer's navigation pane.
 .\"IP
 So that documents or macro packages do not have to laboriously
 \[lq]sanitize\[rq] strings destined for interpolation
-in device control commands,
+in device extension commands,
 this escape sequence
 .\" XXX: and soon other things
 performs certain transformations on its argument.
@@ -1179,7 +1179,7 @@ produce warnings in category
 .BI \[rs]Y( ma
 .TQ
 .BI \[rs]Y[ mac ]
-Interpolate a macro as a device control command.
+Interpolate a macro as a device extension command.
 .
 This is similar to
 .BI \[rs]X\[aq]\[rs]*[ mac ]\[aq]\f[R],
@@ -2356,7 +2356,7 @@ Write
 read in copy mode,
 to
 .I @g@troff
-output as a device control command.
+output as a device extension command.
 .
 A leading neutral double quote in
 .I anything
@@ -2370,7 +2370,7 @@ Write contents of macro or string
 .I name
 to
 .I @g@troff
-output as a device control command.
+output as a device extension command.
 .
 .
 .TP
diff --git a/man/groff_font.5.man b/man/groff_font.5.man
index 3c9d43e0d..4275881f4 100644
--- a/man/groff_font.5.man
+++ b/man/groff_font.5.man
@@ -473,10 +473,12 @@ The
 driver uses this directive.
 .
 .
+.\" XXX: Savannah #63074 is trying to make this obsolescent.
 .TP
 .B use_charnames_in_special
 .I @g@troff
-should encode named glyphs inside device control commands.
+should encode special characters in arguments to device extension
+commands.
 .
 The
 .I \%grohtml
diff --git a/man/groff_out.5.man b/man/groff_out.5.man
index 633722988..3ae3bb50a 100644
--- a/man/groff_out.5.man
+++ b/man/groff_out.5.man
@@ -304,9 +304,9 @@ every command with at least one argument is followed by a 
line break,
 thus providing excellent readability.
 .
 .P
-The other commands \[em] those for drawing and device controlling \[em]
-have a more complicated structure; some recognize long command names,
-and some take a variable number of arguments.
+The other commands\[em]those for drawing and device control\[em]have a
+more complicated structure; some recognize long command names, and some
+take a variable number of arguments.
 .
 So all
 .B D
diff --git a/man/groff_tmac.5.man b/man/groff_tmac.5.man
index 15dd62cea..5bb82ec89 100644
--- a/man/groff_tmac.5.man
+++ b/man/groff_tmac.5.man
@@ -882,7 +882,7 @@ See
 .I sboxes
 offers an interface to the
 .RB \[lq] "pdf: background" \[rq]
-device control command supported by
+device extension command supported by
 .MR gropdf @MAN1EXT@ .
 .
 Using this package,
diff --git a/src/devices/grodvi/grodvi.1.man b/src/devices/grodvi/grodvi.1.man
index ae52f8f40..b9afe1f90 100644
--- a/src/devices/grodvi/grodvi.1.man
+++ b/src/devices/grodvi/grodvi.1.man
@@ -9,7 +9,7 @@ output driver for TeX DVI format
 .\" Legal Terms
 .\" ====================================================================
 .\"
-.\" Copyright (C) 1989-2020, 2022 Free Software Foundation, Inc.
+.\" Copyright (C) 1989-2024 Free Software Foundation, Inc.
 .\"
 .\" Permission is granted to make and distribute verbatim copies of this
 .\" manual provided the copyright notice and this permission notice are
@@ -371,7 +371,7 @@ supports one device extension,
 accessed with the
 .I groff
 request
-.B device
+.B \%device
 or
 .I roff
 .B \[rs]X
@@ -406,7 +406,7 @@ option.
 .
 .P
 The parameter(s) to
-.B device
+.B \%device
 and
 .B \[rs]X
 are translated to the same DVI file instructions as would be produced by
diff --git a/src/devices/gropdf/gropdf.1.man b/src/devices/gropdf/gropdf.1.man
index 3b4f09c1e..f0334402d 100644
--- a/src/devices/gropdf/gropdf.1.man
+++ b/src/devices/gropdf/gropdf.1.man
@@ -711,7 +711,7 @@ supports many device extensions,
 accessed with the
 .I groff
 request
-.B device
+.B \%device
 or
 .I roff
 .B \[rs]X
diff --git a/src/devices/grops/grops.1.man b/src/devices/grops/grops.1.man
index dcd470156..9f6dd2456 100644
--- a/src/devices/grops/grops.1.man
+++ b/src/devices/grops/grops.1.man
@@ -893,6 +893,11 @@ file.
 .
 .I grops
 recognizes device extension commands produced by the
+.I groff
+request
+.B \%device
+or
+.I roff
 .B \[rs]X
 escape sequence,
 but interprets only those that begin with a
diff --git a/src/devices/grotty/grotty.1.man b/src/devices/grotty/grotty.1.man
index 8dca55c0d..dd44b12b2 100644
--- a/src/devices/grotty/grotty.1.man
+++ b/src/devices/grotty/grotty.1.man
@@ -9,7 +9,7 @@ output driver for typewriter-like (terminal) devices
 .\" Legal Terms
 .\" ====================================================================
 .\"
-.\" Copyright (C) 1989-2023 Free Software Foundation, Inc.
+.\" Copyright (C) 1989-2024 Free Software Foundation, Inc.
 .\"
 .\" Permission is granted to make and distribute verbatim copies of this
 .\" manual provided the copyright notice and this permission notice are
@@ -289,10 +289,13 @@ There is therefore no need to filter its output through
 .SS "Device extension commands"
 .\" ====================================================================
 .
-.I grotty
-supports a device extension command accessed with the
-.RB \%\[lq] device \[rq]
-request or
+.I grops
+recognizes a device extension command produced by the
+.I groff
+request
+.B \%device
+or
+.I roff
 .B \[rs]X
 escape sequence.
 .