From mboxrd@z Thu Jan 1 00:00:00 1970 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on inbox.vuxu.org X-Spam-Level: X-Spam-Status: No, score=-1.0 required=5.0 tests=MAILING_LIST_MULTI autolearn=ham autolearn_force=no version=3.4.4 Received: (qmail 9918 invoked from network); 23 Jan 2022 19:46:16 -0000 Received: from minnie.tuhs.org (45.79.103.53) by inbox.vuxu.org with ESMTPUTF8; 23 Jan 2022 19:46:16 -0000 Received: by minnie.tuhs.org (Postfix, from userid 112) id 02BBE9D533; Mon, 24 Jan 2022 05:46:14 +1000 (AEST) Received: from minnie.tuhs.org (localhost [127.0.0.1]) by minnie.tuhs.org (Postfix) with ESMTP id 27E5B9D52C; Mon, 24 Jan 2022 05:45:46 +1000 (AEST) Received: by minnie.tuhs.org (Postfix, from userid 112) id 51BFF9D52C; Mon, 24 Jan 2022 05:45:43 +1000 (AEST) Received: from darkstar.fourwinds.com (fourwinds.com [63.64.179.162]) by minnie.tuhs.org (Postfix) with ESMTPS id C940D9D52B for ; Mon, 24 Jan 2022 05:45:42 +1000 (AEST) Received: from darkstar.fourwinds.com (localhost [127.0.0.1]) by darkstar.fourwinds.com (8.16.1/8.15.2) with ESMTP id 20NJjgdY422899 for ; Sun, 23 Jan 2022 11:45:42 -0800 Received: from darkstar.fourwinds.com (jon@localhost) by darkstar.fourwinds.com (8.16.1/8.15.2/Submit) with ESMTP id 20NJjfab422896 for ; Sun, 23 Jan 2022 11:45:41 -0800 Message-Id: <202201231945.20NJjfab422896@darkstar.fourwinds.com> From: Jon Steinhart To: tuhs@minnie.tuhs.org In-reply-to: References: <20211231234039.GU31637@mcvoy.com> <20220101005605.GL75481@eureka.lemis.com> <20220101031511.GB8135@mcvoy.com> <20220110203300.GY3441@mcvoy.com> <4409b93407ed2118@orthanc.ca> Comments: In-reply-to Douglas McIlroy message dated "Sat, 22 Jan 2022 11:02:10 -0500." MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-ID: <422889.1642967138.1@darkstar.fourwinds.com> Date: Sun, 23 Jan 2022 11:45:41 -0800 X-JON-SPAM: local delivery Subject: Re: [TUHS] troff environments, traps, and diversions (was: TeX and groff) X-BeenThere: tuhs@minnie.tuhs.org X-Mailman-Version: 2.1.26 Precedence: list List-Id: The Unix Heritage Society mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: tuhs-bounces@minnie.tuhs.org Sender: "TUHS" On Fri, Jan 21, 2022 at 9:34 PM Branden Robinson wrote: > > On Tue, Jan 11, 2022 at 1:25 PM Lyndon Nerenberg (VE7TFX/VE6BBM) > 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