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

[Jon Steinhart]

On Fri, Jan 21, 2022 at 9:34 PM Branden Robinson
<g.branden.robinson at gmail.com> wrote:
>
> On Tue, Jan 11, 2022 at 1:25 PM Lyndon Nerenberg (VE7TFX/VE6BBM)
> <lyndon at 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
> Foo

On Lyndon's comment - if you're trying to get a new generation of troff users
keep in mind that to younger folks than us line noise is a reason to get a
surge protector.  And if they have seen phone line noise, I still have a stack
of old modems in the basement for them.  And troff is a lot less like line
noise that OpenOffice XML.

I like the proposed improvements in the docs but would go further.

 o  As per an earlier thread, I would explain the string/number register stuff
    in programming language terms; these are variables.  And number registers
    have things like auto-increment and all that.  It may be *technically*
    correct to say that registers are interpolated, but would be way more
    accessible to talk about the value of a variable.

 o  It would be nice to have a table mapping groff constructs into those from
    other programming languages.  Common ones, that is, not perl.  Mentioned
    variables above, to me macros are functions, there are a few control
    constructs.  Explain this stuff in terms that people are familiar with,
    try to avoid crufty language.

 o  I think that it would be helpful to summarize that troff was originally
    written for smaller computers which required compromises such as the one
    and two character naming scheme.  And a table that shows how that scheme
    has been compatibly expanded since.  Better than hiding this in the
    description of every request that uses names.

 o  I think that an important point to make about diversions is that they're
    a bit like scratch paper; that one can scribble on it and take measurements
    on them to decide what to do.  For example, dumping a paragraph into a
    diversion and then measuring it to see if it will fit unbroken on what's
    left of a page.

 o  The description of traps could be expanded.  I would say something like the
    original traps were a vertical location on a page, and that since then the
    term has been overloaded with number of additional varieties.

Jon