[TUHS] troff environments, traps, and diversions (was: TeX and groff)

[Branden Robinson <g.branden.robinson@gmail.com>]

[-- Attachment #1.1: Type: text/plain, Size: 2667 bytes --]

On Tue, Jan 11, 2022 at 1:25 PM Lyndon Nerenberg (VE7TFX/VE6BBM)
<lyndon@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

[-- Attachment #1.2: Type: text/html, Size: 1384 bytes --]

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]