[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[groff] 32/50: [docs]: Update and sync device control stuff.
From: |
G. Branden Robinson |
Subject: |
[groff] 32/50: [docs]: Update and sync device control stuff. |
Date: |
Sat, 21 May 2022 12:17:28 -0400 (EDT) |
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
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [groff] 32/50: [docs]: Update and sync device control stuff.,
G. Branden Robinson <=