22 Jan
2022
22 Jan
'22
8:34 a.m.
On Tue, Jan 11, 2022 at 1:25 PM Lyndon Nerenberg (VE7TFX/VE6BBM)
<lyndon(a)orthanc.ca> wrote:
A lot of people get turned off by how troff markup can
often look like
line noise. That's true, but if you spend the time to actually learn
the syntax (and it's really not that hard), you can't help but be
overwhelmed by the beauty of its self-consistency. Although after
three decades I still can't wrap my head around traps and diversions
:-P
It seems like a lot of people get stuck on the dread trio of traps,
diversions, and environments. Some old groff documentation did not, I
think, help matters very much by characterizing them as "advanced" and
particularly by comparing diversions to pointers in C. I've been
rewriting a lot of groff's documentation over the past five years.
Here's my attempt to introduce these 3 concepts in the groff(7) page of
the forthcoming 1.23 release. Let me know how I can improve it. (I
retiterate that it's just an introduction--there is much more detail
about all three later in the page and in groff's Texinfo manual, much of
which has parallel content to its man pages.)
A further few language elements arise as page layouts become more
sophisticated and demanding. Environments collect formatting
parameters like line length and typeface. A diversion stores
formatted output for later use. A trap is a condition on the
input or output, tested automatically by the formatter, that is
associated with a macro, causing it to be called when that
condition is fulfilled.
Footnote support often exercises all three of the foregoing
features. A simple implementation might work as follows. A pair
of macros is defined: one starts a footnote and the other ends
it. 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. An environment is created for the
footnote so that it is set 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 much more body text in the
document, a trap, set a small distance above the page bottom, is
sprung. The macro called by the trap draws a line across the
page and emits the stored diversion. Thus, the footnote is
rendered.
Regards,
Branden