[groff] [UTROFF] Pagraph at once adjustment

[Pierre-Jean]

Hello alls,

As stated on my previous mail, I’ll talk today about the
paragraph at once adjustment of Heirloom Troff in Utmac.

# Paragraph at once adjustment details
--------------------------------------

The paragraph at once adjustment appears to be difficult to use,
because of the way it has been implemented by Gunnar Ritter:
macros within the paragraph are executed before the whole
paragraph is adjusted. As a result, notes are diverted in the
page where the paragraph begins, while the corresponding line
could appear on the next page. To solve that problem, Heirloom
Troff provides an output line trap \P[macro] which only executes
the macro when the line is printed. Utmac uses these output line
traps each time it is needed, particularly to divert notes and
refer to a page number.

    .nr num 1 1
    .de NS
    .\" Start a note
    .       \" Put an output line trap.
    \P[note:trap-\\n+[num]]
    .       \" Define an output line trap macro
    .       de note:trap
    .               \" collect all notes in note:div
    .               da note:div
    .                       br
    .                       nf
    .                       \" actually print the note
    .                       note:print-\n[num]
    .                       br
    .               di
    .               ev
    .       ev note
    .       br
    .       \" divert the note to the macro note:print-W,
    .       \" which is only called when the line is printed.
    .       di note:print-\\n[num]
    ..
    .de NE
    .\" End a note
    .       br
    .       di
    .       ev
    ..


As you might notice, it is not easy to understand, even in this
simplified example. That complexity is not the only flail of the
paragraph at once adjustment of Heirloom Troff: it is also
bugged, as noticed on the repository of Karsten Kunze:
<https://github.com/n-t-roff/heirloom-doctools/issues/22>

These two reasons motivated me to try to port Utmac to Neatroff.
That’s a lot of work, since both Neatroff and Heirloom Troff have
their special set of troff commands. Hopefully, once ported to
neatroff, it should be easy to achieve compatibility with groff.

On my next mail, I’ll probably talk about fonts.
Kind Regards,
Pierre-Jean.