[bug #51072] groff.texi: "Diversions" material from groff_tmac(5) missing

[G. Branden Robinson]

Follow-up Comment #5, bug #51072 (project groff):

Hi, Dave!

[comment #4 comment #4:]
> [comment #1 comment #1:]
> > Here is that material.
> [snip]
> > 
> >        The most powerful feature using diversions is to
> >        start a diversion within a macro definition and end
> >        it within another macro.  Then everything between
> >        each call of this macro pair is stored within the
> >        diversion and can be manipulated from within the
> >        macros.
> > 
> > 
> > Does it communicate any concrete information about _groff_
> > that our Texinfo manual (now) does not?
> 
> That final paragraph quoted above is perhaps inferable from
> the rest, but--much like the second plank of bug #57944--for
> people who didn't grow up groffing, it's a nonintuitive way to
> think of defining a diversion.
> 
> [http://git.savannah.gnu.org/cgit/groff.git/commit/?id=7252c3db
> Commit 7252c3db], which resolved that bug, did include an
> example of how to interleave macro definitions.  I'm not sure
> whether a similar example, of a diversion definition spanning
> macros, would be a valuable addition to the Texinfo manual's
> diversion section, or would just bloat it.

There is room in our Texinfo manual to be discursive.  My
post-1.22.4 tour of the _groff_ language at the beginning of
chapter 5 (up to but not including the node/section
"Measurements") is manifestly conversational, at least compared
to most of the older content.

I have the following already in groff(7), under section "_groff_
elements".


       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.


I have noted elsewhere (I can't remember if it's in a stashed
commit, one I've pushed, or in a comment to a Savannah ticket or
mailing list) that the above might be more appropriately placed
in roff(7) since that page is supposed to discuss "concepts",
it does not yet fulfill this promise nearly as well as it
should, and the foregoing is applicable to all *roffs since 1974
or so.

I think with a little bridging material, the above could be
spliced into our Texinfo manual.  I envision a brief section
between the "Drawing Requests" and "Traps" sections, titled
something like "Planning Ahead" for "Formatting for Later".

Structurally, chapter 5 of the manual ("gtroff Reference") gets
a little chaotic toward the end.  But as a rough rule of thumb,
all the requests and escape sequences before that point "do
something *now*", i.e., move or change the way ink is put on the
page in linear sequence with similar operations before and
after.  If you squint, even the "Conditionals and Loops" fits
this characterization, because it breaches linearity only in its
own context.  But diversions push things out for later and traps
can make events spring up in the midst of others.

Making an analogy like that, I suppose I'm a little more
sympathetic to Bernd's presentation of diversions.  But not a
lot, because his analogy is to an unforgiving compiled
programming language, not to everyday concepts.

I'll note while I'm here that the "Colors" section/node seems to
come much later than it could.  It should be relocated earlier,
no later than "Sizes".  (In fact, nearly everything that an
environment saves/preserves should be discussed by the point
that environments are introduced, with exceptions only for
arcane necessities like the enablement status of compatibility
mode or similar.)  The color-related escapes sequences and
requests do obvious things; apart from the mild complication of
color channels and spaces, they are straightforward to present
and use.

> Maybe this is also something that can be shunted into a
> specific examples file, putting it on the plate of bug #57855.

I think that's too pessimistic.  ms(7) and me(7) are both heavy
users of diversion opening/closing macro pairs.  It's an
idiomatic usage (for footnotes, it's the archetypal one), and
only this fog of mystique has kept diversions from receiving the
emphasis they are due.

Not everybody needs them, but there's a reason they became a
language feature even before Murray Hill acquired the C/A/T.

Regards,
Branden


    _______________________________________________________

Reply to this item at:

  <https://savannah.gnu.org/bugs/?51072>

_______________________________________________
  Message sent via Savannah
  https://savannah.gnu.org/