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