gbranden pushed a commit to branch master
in repository groff.
commit 82e865fe756a6fa3470c236b6e591376772606f2
Author: G. Branden Robinson <g.branden.robin...@gmail.com>
AuthorDate: Wed Feb 26 18:30:17 2025 -0600
[doc,man]: Clarify trap/diversion/enviro intro.
Also align breaks in text mirrored between Texinfo and man(7) document.
---
doc/groff.texi.in | 43 ++++++++++++++++++++++++++-----------------
man/roff.7.man | 2 +-
2 files changed, 27 insertions(+), 18 deletions(-)
diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index f1df9a969..de96e12ba 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -14871,20 +14871,27 @@ later use. A @dfn{trap} is a condition on the input
or output, tested
automatically by the formatter, that is associated with a macro:
fulfilling the condition @dfn{springs} the trap---calls the macro.
-Footnote support often exercises all three of the foregoing features. A
-simple implementation might work as follows. The author writes a pair
-of macros: one starts a footnote and the other ends it. They further
-set a trap a small distance above the page bottom, reserving a footnote
-area. The author calls the first macro where a footnote marker is
-desired. The macro establishes a diversion so that the footnote text is
-collected at the place in the body text where its corresponding marker
-appears. It further creates an environment for the footnote so that it
-sets at a smaller typeface. The footnote text is formatted in the
-diversion using that environment, but it does not yet appear in the
-output. The document author calls the footnote end macro, which returns
-to the previous environment and ends the diversion. Later, after body
-text nearly fills the page, the trap springs. The macro called by the
-trap draws a line across the page and emits the stored diversion. Thus,
+Footnote support often exercises all three of the foregoing features.
+A simple implementation might work as follows.
+The author writes a pair of macros:@:
+one starts a footnote and the other ends it.
+They further set a trap a small distance above the page bottom,
+reserving a footnote area.
+The author calls the first macro where a footnote marker is desired.
+The macro establishes a diversion so that the footnote text is collected
+at the place in the body text where its corresponding marker appears.
+It further creates an environment for the footnote so that it
+sets at a smaller typeface.
+The footnote text is formatted in the diversion using that environment
+but it does not yet appear in the output.
+The document author calls the footnote end macro,
+which returns to the previous environment and ends the diversion.
+Later,
+after body
+text nearly fills the page, the trap springs.
+The macro called by the trap draws a line across the page
+and emits the stored diversion by calling it like a macro.
+Thus,
the footnote renders.
Diversions and traps make the text formatting process non-linear. Let
@@ -14892,15 +14899,17 @@ us imagine a set of text lines or paragraphs labelled
@samp{A},
@samp{B}, and so on. If we set up a trap that produces text @samp{T}
(as a page footer, say), and we also use a diversion to store the
formatted text @samp{D}, then a document with input text in the order
-@samp{A B C D E F} might render as @samp{A B C E T F}. The diversion
-@samp{D} will never be output if we do not call for it.
+@samp{A B C D E F} might render as @samp{A B C E T F}.
+The diversion
+@samp{D}
+is never output if we do not call it.
Environments of themselves are not a source of non-linearity in document
formatting:@: environment switches have immediate effect. One could
always write a macro to change as many formatting parameters as desired
with a single convenient call. But because diversions can be nested and
macros called by traps that are sprung by other trap-called macros, they
-may be called upon in varying contexts. For example, consider a page
+may be interpolated in varying contexts. For example, consider a page
header that is always to be set in Helvetica. A document that uses
Times for most of its body text, but Courier for displayed code
examples, poses a challenge if a page break occurs in the middle of a
diff --git a/man/roff.7.man b/man/roff.7.man
index aa0a52613..bd6204e06 100644
--- a/man/roff.7.man
+++ b/man/roff.7.man
@@ -841,7 +841,7 @@ after body text nearly fills the page,
the trap springs.
.
The macro called by the trap draws a line across the page
-and emits the stored diversion.
+and emits the stored diversion by calling it like a macro.
.
Thus,
the footnote is rendered.
_______________________________________________
groff-commit mailing list
groff-commit@gnu.org
https://lists.gnu.org/mailman/listinfo/groff-commit
