The Unix Heritage Society mailing list
 help / color / mirror / Atom feed
From: Branden Robinson <g.branden.robinson@gmail.com>
To: "Lyndon Nerenberg (VE7TFX/VE6BBM)" <lyndon@orthanc.ca>
Cc: tuhs@minnie.tuhs.org
Subject: [TUHS] troff environments, traps, and diversions (was: TeX and groff)
Date: Sat, 22 Jan 2022 13:34:36 +1100	[thread overview]
Message-ID: <CAN4uE+p=LpEJk8mMw7f+58VVnrKqRrx1dgEG8Ofqwc8LbPfgCQ@mail.gmail.com> (raw)
In-Reply-To: <4409b93407ed2118@orthanc.ca>


[-- 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 --]

  parent reply	other threads:[~2022-01-22  2:35 UTC|newest]

Thread overview: 101+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-12-31 15:47 [TUHS] roff(7) Douglas McIlroy
2021-12-31 23:07 ` George Michaelson
2021-12-31 23:40   ` Larry McVoy
2022-01-01  0:56     ` [TUHS] TeX and groff (was: roff(7)) Greg 'groggy' Lehey
2022-01-01  3:15       ` Larry McVoy
2022-01-10 19:00         ` Blake McBride
2022-01-10 20:21           ` Jon Forrest
2022-01-11 22:48             ` Blake McBride
2022-01-11 23:18               ` Larry McVoy
2022-01-12  1:19                 ` Dave Horsfall
2022-01-12  1:46                 ` Blake McBride
2022-01-12  2:12                 ` Bakul Shah
2022-01-12 15:49                   ` Larry McVoy
2022-01-12 16:22                     ` Adam Thornton
2022-01-12  0:06               ` Jon Steinhart
2022-01-12  1:48                 ` Blake McBride
2022-01-12  0:29               ` Nemo Nusquam
2022-01-12  1:53                 ` Blake McBride
     [not found]               ` <E3CC4B8A-4E88-4339-A4D3-4ED26BA80620@gmail.com>
2022-01-12  0:44                 ` Jon Forrest
2022-01-12  2:00                   ` Blake McBride
2022-01-12  2:10                     ` David Arnold
2022-01-12  2:26                       ` Adam Thornton
2022-01-12 19:54                     ` John Cowan
2022-01-13 10:13                       ` Thomas Paulsen
2022-01-13 20:00                         ` John Cowan
2022-01-10 20:33           ` Larry McVoy
2022-01-10 20:37             ` Richard Salz
2022-01-10 21:04               ` Dan Cross
2022-01-10 21:48                 ` Nemo Nusquam
2022-01-11  2:25                 ` Lyndon Nerenberg (VE7TFX/VE6BBM)
2022-01-11  2:47                   ` Larry McVoy
2022-01-22  2:34                   ` Branden Robinson [this message]
2022-01-22 16:02                     ` [TUHS] troff environments, traps, and diversions (was: TeX and groff) Douglas McIlroy
2022-01-23 19:45                       ` Jon Steinhart
2022-01-23 22:26                       ` Jon Steinhart
2022-01-11  1:52               ` [TUHS] Recognizing TeX (was: TeX and groff (was: roff(7))) Greg 'groggy' Lehey
2022-01-12  1:19             ` [TUHS] TeX and groff (was: roff(7)) Mary Ann Horton
2022-01-12  2:03               ` Blake McBride
2022-01-12  2:10               ` Bakul Shah
2022-01-12  3:44                 ` Dan Cross
2022-01-12 16:48               ` Steffen Nurpmeso
2022-01-10 20:46           ` Steffen Nurpmeso
2022-01-11  1:59           ` [TUHS] Demise of " Greg 'groggy' Lehey
2022-01-11  2:13             ` Lyndon Nerenberg (VE7TFX/VE6BBM)
2022-01-11  2:42               ` Larry McVoy
2022-01-11  5:12                 ` Greg 'groggy' Lehey
2022-01-11  5:59                   ` John Labovitz
2022-01-11  8:57                   ` arnold
2022-01-11 20:15                     ` Jon Steinhart
2022-01-11 20:22                       ` Larry McVoy
2022-01-11 20:26                         ` Jon Steinhart
2022-01-11 20:36                           ` Larry McVoy
2022-01-11 20:41                             ` Jon Steinhart
2022-01-11 20:49                               ` Larry McVoy
2022-01-11 21:03                                 ` Jon Steinhart
2022-01-11  8:50                 ` arnold
2022-01-11 14:00                   ` Larry McVoy
2022-01-12 23:22                     ` [TUHS] troff or groff? (was: Demise of TeX and groff (was: roff(7))) Greg 'groggy' Lehey
2022-01-12 23:29                       ` Greg 'groggy' Lehey
2022-01-12 23:32                       ` Larry McVoy
2022-01-11 15:47                 ` [TUHS] Demise of TeX and groff (was: roff(7)) Clem Cole
2022-01-11 16:55                   ` Richard Salz
2022-01-11 18:49                     ` Clem Cole
2022-01-11 19:20                   ` John Cowan
2022-01-11 20:06                     ` Clem Cole
2022-01-11 23:57                       ` Warner Losh
2022-01-12  0:03                         ` Warner Losh
2022-01-12  8:54                       ` arnold
2022-01-12 15:17                         ` Clem Cole
2022-01-12 16:33                         ` Dan Cross
2022-01-12 18:06                           ` [TUHS] *roff history as told to GNU G. Branden Robinson
2022-01-12 18:34                             ` Dan Halbert
2022-01-12 22:48                               ` Clem Cole
2022-01-12 23:27                                 ` Charles H. Sauer
2022-01-13  0:35                                   ` Adam Thornton
2022-01-12 20:01                             ` Dan Cross
2022-01-12 22:32                             ` Clem Cole
2022-01-13  2:38                             ` John Labovitz
2022-01-13  7:42                               ` Lars Brinkhoff
2022-01-13 13:47                                 ` John Labovitz
2022-01-12  8:48                   ` [TUHS] Demise of TeX and groff (was: roff(7)) arnold
2022-01-12 15:51                     ` Larry McVoy
2022-01-12 15:57                       ` Clem Cole
2022-01-12 15:56                     ` Clem Cole
2022-01-11  3:22               ` Adam Thornton
2022-01-12  0:32             ` Nemo Nusquam
2022-01-01 20:00     ` [TUHS] roff(7) [ and other related stuff ] Jon Steinhart
2022-01-02  0:12       ` Larry McVoy
2022-01-02  1:04         ` John Cowan
2022-01-02  1:20           ` Larry McVoy
2022-01-02  1:47             ` Steve Nickolas
2022-01-02  2:12               ` Larry McVoy
2022-01-02  3:56               ` Jon Steinhart
2022-01-02  1:48             ` Jon Steinhart
2022-01-02  3:04             ` John Cowan
2022-01-02  3:30               ` Warner Losh
2022-01-01  1:11   ` [TUHS] roff(7) Phil Budne
2022-01-01  1:17     ` Chris Torek
2022-01-01  3:06       ` Larry McVoy
2022-01-01  3:34       ` George Michaelson
2022-01-05 21:15   ` Tony Finch

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to='CAN4uE+p=LpEJk8mMw7f+58VVnrKqRrx1dgEG8Ofqwc8LbPfgCQ@mail.gmail.com' \
    --to=g.branden.robinson@gmail.com \
    --cc=lyndon@orthanc.ca \
    --cc=tuhs@minnie.tuhs.org \
    --subject='Re: [TUHS] troff environments, traps, and diversions (was: TeX and groff)' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).