gbranden pushed a commit to branch master
in repository groff.
commit c7a9a6dbf3667bb28b9a30ca7b19ac18f75ab65d
Author: G. Branden Robinson <[email protected]>
AuthorDate: Tue Sep 3 03:59:07 2024 -0500
[doc,man]: Recast the `\X` saga.
---
doc/groff.texi.in | 47 ++++++++++++++++++++----------
man/groff.7.man | 56 ++++++++++++++++++++++++++++++------
man/groff_diff.7.man | 81 ++++++++++++++++++++++++++--------------------------
3 files changed, 119 insertions(+), 65 deletions(-)
diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index 5d9076260..992469c85 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -16586,6 +16586,9 @@ The @code{device} request strips a leading neutral
double quote from
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
@@ -16595,23 +16598,37 @@ is stripped to allow embedding of leading spaces.
@ifinfo
@cindex @code{\@r{<colon>}}, in device control commands
@end ifinfo
-By contrast, within @code{\X} arguments, GNU @command{troff} converts
-several ordinary characters that typeset as non-basic Latin code points
-to code points outside that range to avoid confusion when these
-characters are used in ways that are ultimately visible, as in tag names
-for PDF bookmarks, which can appear in a viewer's navigation pane.
-These ordinary characters are @samp{'}, @samp{-}, @samp{^}, @samp{`},
-and @samp{~}; others are written as-is.
+The @code{groff} special character repertoire is unknown to output
+drivers outside of glyphs named in a device's fonts, and even then they
+may not possess complete coverage of the names documented in the
+@cite{groff_char@r{(7)}} man page. Further, escape sequences that
+produce horizontal or vertical motions, hyphenation breaks, or that are
+dummy characters may appear in strings or be converted to nodes,
+particularly in diversions (@pxref{Gtroff Internals}). These are not
+representable when interpolated directly into device-independent output,
+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
+commands, the @code{\X} escape sequence
+@c XXX: and soon other things
+performs certain transformations on its argument. For these
+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
+@samp{'}, @samp{-}, @samp{^}, @samp{`}, and @samp{~}; others are written
+as-is.
Special characters that typeset as Unicode basic Latin characters are
-translated to basic Latin characters accordingly. For this
-transformation, character translations and definitions are ignored.
-
-So that any Unicode code point can be represented in device extension
-commands, for example in an author's name in document metadata or as a
-usefully named bookmark or hyperlink anchor, GNU @command{troff} maps
-other special characters to Unicode special character notation.
-@xref{Using Symbols}.
+translated to basic Latin characters accordingly. So that any Unicode
+code point can be represented in device extension commands, for example
+in an author's name in document metadata or as a usefully named bookmark
+or hyperlink anchor, GNU @command{troff} maps other special characters
+to Unicode special character notation. @xref{Using Symbols}.
Special characters without a Unicode representation, and escape
sequences that do not interpolate a sequence of ordinary and/or special
diff --git a/man/groff.7.man b/man/groff.7.man
index cb236c592..d5d62f3dd 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -5601,14 +5601,53 @@ to
.I @g@troff
output as a device extension command.
.
+The
+.I groff
+special character repertoire is unknown to output drivers outside of
+glyphs named in a device's fonts,
+and even then they may not possess complete coverage of the names
+documented in
+.MR groff_char @MAN7EXT@ .
+.
+Further,
+escape sequences that produce horizontal or vertical motions,
+hyphenation breaks,
+or that are dummy characters may appear in strings
+or be converted to nodes,
+particularly in diversions. \" (@pxref{Gtroff Internals})
+.
+These are not representable when interpolated directly into
+device-independent output,
+as might be done when writing out tag names for PDF bookmarks,
+which can appear in a viewer's navigation pane.
+.
+.
+.\" XXX: Force paragraph spacing here. I know--it's terrible. And
+.\" unnecessary once we get this giant discussion moved to its own
+.\" (sub)section.
+.if t .sp 0.4v
+.if n .sp 1v
+.\"IP
+So that documents or macro packages do not have to laboriously
+\[lq]sanitize\[rq] strings destined for interpolation
+in device control commands,
+this escape sequence
+.\" XXX: and soon other things
+performs certain transformations on its argument.
+.
+For these transformations,
+character translations and definitions are ignored.
+.
+.
+.if t .sp 0.4v
+.if n .sp 1v
+.\"IP
GNU
.I troff \" GNU
converts several ordinary characters that typeset as non-basic Latin
-code points to code points outside that range
-to avoid confusion when these characters are used in ways that are
-ultimately visible,
-as in tag names for PDF bookmarks,
-which can appear in a viewer's navigation pane.
+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
.RB \[lq]\| \[aq] \|\[rq],
@@ -5620,13 +5659,12 @@ and
others are written as-is.
.
.
-.IP
+.if t .sp 0.4v
+.if n .sp 1v
+.\"IP
Special characters that typeset as Unicode basic Latin characters
are translated to basic Latin characters accordingly.
.
-For this transformation,
-character translations and definitions are ignored.
-.
So that any Unicode code point can be represented in device extension
commands,
for example in an author's name in document metadata
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index 767f5e216..9f6406d91 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -1092,50 +1092,51 @@ is interpreted even in copy mode.
.\" requests, move this discussion into a dedicated subsection above.
.TP
.BI \[rs]X\[aq] contents \[aq]
-GNU
-.I troff \" GNU
-transforms the argument to the device control escape sequence to avoid
-leaking to device-independent output data that are unrepresentable in
-that format,
-and to address the problem of expressing character code points outside
-of the Unicode basic Latin range in an output file format that restricts
-itself to that range.
-.
-(See subsection \[lq]Basic Latin\[rq] of
-.MR groff_char @MAN7EXT@ .)
-.
-The typesetting of such characters is a problem long-solved in
-device-independent
-.I troff \" generic
-by the
-.RB \[lq] C \[rq]
-command;
-see
-.MR groff_out @MAN5EXT@ .
+The
+.I groff
+special character repertoire is unknown to output drivers outside of
+glyphs named in a device's fonts,
+and even then they may not possess complete coverage of the names
+documented in
+.MR groff_char @MAN7EXT@ .
+.
+Further,
+escape sequences that produce horizontal or vertical motions,
+hyphenation breaks,
+or that are dummy characters may appear in strings
+or be converted to nodes,
+particularly in diversions. \" (@pxref{Gtroff Internals})
+.
+These are not representable when interpolated directly into
+device-independent output,
+as might be done when writing out tag names for PDF bookmarks,
+which can appear in a viewer's navigation pane.
.
-The expression of such characters in other contexts,
-such as device extension commands,
-was not addressed by the same design.
.
-Where possible,
-GNU
-.I troff \" GNU
-represents such characters in device-independent
-but non-typesetting contexts using its notation
-for Unicode special character escape sequences;
-see subsection \[lq]Special character escape forms\[rq] of
-.MR groff_char @MAN7EXT@ .
+.\" XXX: Force paragraph spacing here. I know--it's terrible. And
+.\" unnecessary once we get this giant discussion moved to its own
+.\" (sub)section.
+.sp \n[PD]u
+.\"IP
+So that documents or macro packages do not have to laboriously
+\[lq]sanitize\[rq] strings destined for interpolation
+in device control commands,
+this escape sequence
+.\" XXX: and soon other things
+performs certain transformations on its argument.
.
+For these transformations,
+character translations and definitions are ignored.
.
-.IP
+.
+.sp \n[PD]u
+.\"IP
GNU
.I troff \" GNU
converts several ordinary characters that typeset as non-basic Latin
-code points to code points outside that range
-to avoid confusion when these characters are used in ways that are
-ultimately visible,
-as in tag names for PDF bookmarks,
-which can appear in a viewer's navigation pane.
+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
.RB \[lq]\| \[aq] \|\[rq],
@@ -1147,13 +1148,11 @@ and
others are written as-is.
.
.
-.IP
+.sp \n[PD]u
+.\"IP
Special characters that typeset as Unicode basic Latin characters
are translated to basic Latin characters accordingly.
.
-For this transformation,
-character translations and definitions are ignored.
-.
So that any Unicode code point can be represented in device extension
commands,
for example in an author's name in document metadata
_______________________________________________
Groff-commit mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/groff-commit
