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