gbranden pushed a commit to branch master
in repository groff.
commit 5fe64fb4a6c151c0e95970dc79df80c462d97f6f
Author: G. Branden Robinson <[email protected]>
AuthorDate: Sun Apr 13 14:43:58 2025 -0500
[doc,man]: Revise character vs. glyph discussion.
---
doc/groff.texi.in | 68 ++++++++++++++++++++++++++++++++++----------
man/groff_diff.7.man | 79 +++++++++++++++++++++++++++++++++-------------------
2 files changed, 105 insertions(+), 42 deletions(-)
diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index 63a40b2bd..22db2d31d 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -18881,20 +18881,60 @@ each rounded down to the nearest multiple of@tie{}12.
@cindex output glyphs, and input characters, compatibility with @acronym{AT&T}
@code{troff}
@cindex characters, input, and output glyphs, compatibility with
@acronym{AT&T} @code{troff}
@cindex glyphs, output, and input characters, compatibility with
@acronym{AT&T} @code{troff}
-In GNU @code{troff} there is a fundamental difference between
-(unformatted) characters and (formatted) glyphs. Everything that
-affects how a glyph is output is stored with the glyph node; once a
-glyph node has been constructed, it is unaffected by any subsequent
-requests that are executed, including @code{bd}, @code{cs}, @code{tkf},
-@code{tr}, or @code{fp} requests. Normally, glyphs are constructed from
-characters immediately before the glyph is added to an output line.
-Macros, diversions, and strings are all, in fact, the same type of
-object; they contain a sequence of intermixed character and glyph nodes.
-Special characters transform from one to the other:@: before being added
-to the output, they behave as characters; afterward, they are glyphs. A
-glyph node does not behave like a character node when it is processed by
-a macro:@: it does not inherit any of the special properties that the
-character from which it was constructed might have had. For example,
+@c TODO: A lot of this discussion should move to "Using Symbols" and
+@c "Gtroff Internals".
+GNU
+@command{troff} @c GNU
+fundamentally distinguishes characters from glyphs.
+Characters can be ordinary,
+special,
+or indexed,
+and populate strings and macros.
+Characters
+@emph{per se}
+have not (yet) been formatted.
+Glyphs represent graphemes
+(supplied by the output device)
+and populate diversions
+or the pending output line.
+The formatting process converts characters into
+(sequences of)
+glyphs.
+GNU
+@command{troff} @c GNU
+stores properties of the environment
+that affect how a glyph is rendered with the glyph node's data.
+Thus,
+subsequent formatting operations do not affect it,
+including
+@code{bd},
+@code{cs},
+@code{tkf},
+@code{tr},
+and
+@code{fp}
+requests.
+Normally,
+a macro or string
+contains only a list of characters
+and a diversion
+contains only a list of nodes.
+However,
+applying the
+@code{asciify}
+or
+@code{unformat}
+requests to diversion converts some of its nodes back into characters.
+Where the formatter cannot recover the character representation of node,
+it stores a null character
+corresponding to a single node in the node list.
+
+Consequently,
+a glyph node does not behave like a character
+when it is processed by a macro:@:
+it does not inherit any of the special properties
+that the character from which it was constructed might have had.
+For example,
the input
@Example
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index 1aaec67e9..ad43dac1a 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -6384,46 +6384,69 @@ rounds down the values of minimum inter-word and
additional
inter-sentence space each to the nearest multiple of\~12.
.
.
+.\" TODO: A lot of this discussion should move to "Using Symbols" and
+.\" "Gtroff Internals" (or whatever those section get named once ported
+.\" to this man page).
.P
-In GNU
+GNU
+.I troff \" GNU
+fundamentally distinguishes characters from glyphs.
+.
+Characters can be ordinary,
+special,
+or indexed,
+and populate strings and macros.
+.
+Characters
+.I "per se"
+have not (yet) been formatted.
+.
+Glyphs represent graphemes
+(supplied by the output device)
+and populate diversions
+or the pending output line.
+.
+The formatting process converts characters into
+(sequences of)
+glyphs.
+.
+GNU
.I troff \" GNU
-there is a fundamental difference between (unformatted) characters and
-(formatted) glyphs.
+stores properties of the environment
+that affect how a glyph is rendered with the glyph node's data.
.
-Everything that affects how a glyph is output is stored with the glyph
-node;
-once a glyph node has been constructed,
-it is unaffected by any subsequent requests that are executed,
+Thus,
+subsequent formatting operations do not affect it,
including
.BR bd ,
.BR cs ,
.BR tkf ,
.BR tr ,
-or
+and
.B fp
requests.
.
Normally,
-glyphs are constructed from characters immediately before the glyph is
-added to an output line.
-.
-Macros,
-diversions,
-and strings are all,
-in fact,
-the same type of object;
-they contain a sequence of intermixed character and glyph nodes.
-.
-Special characters transform from one to the other:
-before being added to the output,
-they behave as characters;
-afterward,
-they are glyphs.
-.
-A glyph node does not behave like a character node when it is processed
-by a macro:
-it does not inherit any of the special properties that the character
-from which it was constructed might have had.
+a macro or string
+contains only a list of characters
+and a diversion
+contains only a list of nodes.
+However,
+applying the
+.B \%asciify
+or
+.B \%unformat
+requests to diversion converts some of its nodes back into characters.
+.
+Where the formatter cannot recover the character representation of node,
+it stores a null character
+corresponding to a single node in the node list.
+.
+Consequently,
+a glyph node does not behave like a character
+when it is processed by a macro:
+it does not inherit any of the special properties
+that the character from which it was constructed might have had.
.
.
.P
_______________________________________________
groff-commit mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/groff-commit
