gbranden pushed a commit to branch master
in repository groff.
commit 9a7c84d7884752cc3414cafca98992eb8fb58803
Author: G. Branden Robinson <[email protected]>
AuthorDate: Tue Dec 30 04:05:39 2025 -0600
doc/groff.texi.in: Clarify GNU troff internals.
Retitle node/section away from archaic "gtroff" nomenclature. Add
`@anchor` for sake of hyperlinks to old copies of the GNU troff manual.
---
doc/groff.texi.in | 78 ++++++++++++++++++++++++++++++++-----------------------
1 file changed, 46 insertions(+), 32 deletions(-)
diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index 73133c387..741550d18 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -5385,7 +5385,7 @@ not interested in details.
* I/O::
* Postprocessor Access::
* Miscellaneous::
-* Gtroff Internals::
+* GNU @command{troff} Internals::
* Debugging::
* Implementation Differences::
@end menu
@@ -8399,7 +8399,7 @@ does not tokenize
when reading it;
the escape sequence updates only the formatter's register dictionary
and does not contribute (directly) to output.
-@xref{Gtroff Internals}.
+@xref{GNU @command{troff} Internals}.
Further surprise can occur if you use registers like
@code{.k},@footnote{@xref{Page Motions}.} whose values are not
@@ -10697,7 +10697,8 @@ environment (@pxref{Environments}).
A @dfn{translation} is a mapping of an input character to an output
glyph. The mapping occurs at output time, i.e., the input character
gets assigned the metric information of the mapped output character
-right before tokens are converted to nodes (@pxref{Gtroff Internals},
+right before tokens are converted to nodes
+(@pxref{GNU @command{troff} Internals},
for more on this process).
@DefreqList {tr, @Var{a}@Var{b}@Var{c}@Var{d}@dots{}}
@@ -10810,7 +10811,7 @@ Translating character to glyphs where one of them or
both are undefined
is possible also; @code{tr} does not check whether the elements of its
argument exist.
-@xref{Gtroff Internals}.
+@xref{GNU @command{troff} Internals}.
@item
Without an argument, the @code{tr} request is ignored.
@@ -12687,7 +12688,7 @@ GNU
processes
@var{contents}
in a temporary environment and enscapsulates the result
-in a node;@footnote{@xref{Gtroff Internals}.}
+in a node;@footnote{@xref{GNU @command{troff} Internals}.}
disabling compatibility mode
and setting the escape character
to@tie{}@code{\}
@@ -14615,7 +14616,8 @@ request.
Remove the last character from the macro, string, or diversion named
@var{object}. This is useful for removing the newline from the end of a
diversion that is to be interpolated as a string. This request can be
-used repeatedly on the same @var{object}; see @ref{Gtroff Internals},
+used repeatedly on the same @var{object}; see
+@ref{GNU @command{troff} Internals},
for details on nodes inserted additionally by GNU @code{troff}.
@endDefreq
@@ -14976,7 +14978,8 @@ in a dummy environment, vertical motions within them
cannot spring
traps.} On the other hand, @samp{.if "\d"\v'0.5m'"} is true, because
@code{\d} is defined as a downward motion of one-half em.@footnote{All
of this is to say that the lists of nodes created by formatting
-@var{xxx} and @var{yyy} must be identical. @xref{Gtroff Internals}.}
+@var{xxx} and @var{yyy} must be identical.
+@xref{GNU @command{troff} Internals}.}
@cindex string comparison
@cindex comparison of strings
@@ -17450,14 +17453,15 @@ spaces).
@c
@c The first thing a leading space macro sees is a token. However, some
@c escape sequences, like @code{\f} and @code{\m}, are handled on the
-@c fly (@pxref{Gtroff Internals} for a complete list) without creating a
-@c token at all. Consider a line that starts with two spaces followed
-@c by @samp{\fIfoo}. After skipping the spaces, @samp{\fI} is handled
-@c as well such that @code{groff}'s current font is set to @code{I}, but
-@c the leading space macro sees only @samp{foo} without the preceding
-@c @samp{\fI}. If the macro should see the font escape, you have to
-@c ``protect'' it with something that creates a token, like the
-@c dummy character; for example, @samp{\&\fIfoo}.
+@c fly
+@c (@pxref{GNU @command{troff} Internals} for a complete list)
+@c without creating a token at all. Consider a line that starts with
+@c two spaces followed by @samp{\fIfoo}. After skipping the spaces,
+@c @samp{\fI} is handled as well such that @code{groff}'s current font
+@c is set to @code{I}, but the leading space macro sees only @samp{foo}
+@c without the preceding @samp{\fI}. If the macro should see the font
+@c escape, you have to ``protect'' it with something that creates a
+@c token, like the dummy character; for example, @samp{\&\fIfoo}.
@endDefreq
@c ---------------------------------------------------------------------
@@ -18124,7 +18128,7 @@ This is \*[xxx].
@result{} This is a funny test.
@endExample
-@xref{Gtroff Internals}.
+@xref{GNU @command{troff} Internals}.
@c =====================================================================
@@ -18748,8 +18752,10 @@ Multiple @code{pi} requests construct a multi-stage
pipeline in the same
order as the formatter encounters the requests.
@code{pi} must be invoked before GNU @command{troff} writes any nodes
-to its output.@footnote{@xref{Gtroff Internals}.} The formatter reports
-an error and ignores the request if @code{pi} is invoked ``too late''.
+to its output.@footnote{@xref{GNU @command{troff} Internals}.}
+The formatter reports an error and ignores the request if
+@code{pi}
+is invoked ``too late''.
Roughly, this means you should set up your @code{pi} pipeline early in a
document, before anything but register, string, and macro definitions
(and/or sourcing of files that comprise these exclusively).
@@ -18996,10 +19002,11 @@ 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.
+particularly in diversions (@pxref{GNU @command{troff} 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 extension
@@ -19085,7 +19092,7 @@ Reserved for internal use.
@c =====================================================================
-@node Miscellaneous, Gtroff Internals, Postprocessor Access, GNU troff
Reference
+@node Miscellaneous, GNU @command{troff} Internals, Postprocessor Access, GNU
troff Reference
@section Miscellaneous
We document here GNU @code{troff} features that fit poorly elsewhere.
@@ -19305,8 +19312,9 @@ command-line option.
@c =====================================================================
-@node Gtroff Internals, Debugging, Miscellaneous, GNU troff Reference
-@section @command{gtroff} Internals
+@node GNU @command{troff} Internals, Debugging, Miscellaneous, GNU troff
Reference
+@anchor{gtroff Internals} @c 1.22.4
+@section GNU @command{troff} Internals
@cindex input token
@cindex token
@@ -19330,7 +19338,8 @@ and
instead update the environment,
if the formatter is not in copy mode.}
the smallest meaningful unit of
-@command{troff} input.
+@command{troff} @c generic
+input.
The process of formatting translates tokens into nodes
that populate a pending output line
(recall
@@ -19352,6 +19361,11 @@ accumulated output line(s) to the output device,
a process that translates each node
into a device-independent output language representation
understood by all output drivers.
+To summarize,
+copy mode tokenizes but does not format;
+diversions
+(apart from that at the top level)
+format but do not write output.
For example,
GNU
@@ -19392,7 +19406,7 @@ The names and structures of node types may change over
time.
The @acronym{JSON} interpreter
@cite{jq@r{(1)}}
is not essential,
-but can be helpful in understanding the structure of the node trees
+but can be helpful in understanding the topology of the node trees
populating output lines and diversions in particular.}
@Example
@@ -19555,7 +19569,7 @@ restore tokens are removed.
@need 1000
@c BEGIN Keep parallel with section "Debugging" of groff(7).
-@node Debugging, Implementation Differences, Gtroff Internals, GNU troff
Reference
+@node Debugging, Implementation Differences, GNU @command{troff} Internals,
GNU troff Reference
@section Debugging
@cindex debugging
@@ -21094,7 +21108,7 @@ inter-sentence space each to the nearest multiple
of@tie{}12.
@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}
@c TODO: A lot of this discussion should move to "Using Symbols" and
-@c "Gtroff Internals".
+@c "GNU @command{troff} Internals".
GNU
@command{troff} @c GNU
distinguishes characters from glyphs.
@@ -21212,8 +21226,8 @@ To store an escape sequence in a diversion that is
interpreted when the
diversion is interpolated, either use the traditional @code{\!}
transparent output facility, or, if this is unsuitable,
@c XXX: Why would it be unsuitable? Line breaking behavior?
-the new @code{\?} escape sequence. @xref{Diversions} and @ref{Gtroff
-Internals}.
+the new @code{\?} escape sequence. @xref{Diversions} and
+@ref{GNU @command{troff} Internals}.
@cindex timing of output flushes, incompatibilities with @acronym{AT&T}
@command{troff}
@cindex output flushes, timing of, incompatibilities with @acronym{AT&T}
@command{troff}
@@ -21226,7 +21240,7 @@ maintains a buffer of device-independent output
commands,@footnote{In
GNU
@command{troff}, @c GNU
node objects produce these commands;
-recall @ref{Gtroff Internals}.}
+recall @ref{GNU @command{troff} Internals}.}
populating the buffer as input accumulates.
GNU
@command{troff} @c GNU
_______________________________________________
groff-commit mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/groff-commit
