Hi Sébastien, At 2026-09-20T15:14:56-0300, Sébastien Peterson-Boudreau wrote: > In technical writing, it is a well-understood practice to expand the > meaning of an abbreviation/acronym on its first usage. It is also > sometimes recommended to additionally expand it after some stretch of > text (I've seen suggestions as frequently as each paragraph, to > infrequently as each section/chapter; I am a fan of re-expansion after > a page break), to remind the reader in case they forgot since they > first saw it.
I concur; I've frequently seen these practices in high-quality writing, and have tried to bring them to the groff and ncurses man pages in particular. > I was wondering if anyone had ever written a macro to automate this? A similar thing was done from very early days at the Bell Labs CSRC to mark the word "Unix" with a "registered sign" ® only on its first occurrence. You can imagine how easily this maps to abbreviation expansion. > I > haven't actually made any attempts myself, which I know is a little > rude, but I don't really have need of one right now, and am moreso > curious about the techniques that could be used to accomplish this. First, make a macro! *roff users swiftly get comfortable with strings. .ds XT XTerm .\" ...verbiage or other document setup follows \*[XT] is a DEC VT220 emulator for the X Window System. But if you have a string that needs to change its behavior depending on its placement in the document, or really on any condition that is exposed to the *roff language, what you want is a macro instead. This first step is simple enough. .de XT XTerm .. .\" ...verbiage or other document setup follows .XT is a DEC VT220 emulator for the X Window System. > What I was particularly pondering was the process to employ to decide > when to expand the name additional times -- the "reader reminder" I > mentioned at the start. Right. Let's reimplement a CSRC-style `UX` macro. .nr ux 0 .de UX Unix\c .if !\\n[ux] \[rg]\c .nop \" put a word space on the output .nr ux 1 .. You can see we've configured the `ux` register as a Boolean flag, and set up the logic to add ® only if the flag is not set, and then force it at the end of macro. [reorganizing] > You could also couple the abbreviation mechanism with your > paragraph/sectioning macros to have them trigger a "reset", if you > wished to trigger re-expansion every paragraph or section, as > mentioned before. Yes! So a chaptering macro might do this. .de CH .bp .nr ux 0 .\" other stuff .. > This doesn't help us if we have a metric to re-expand abbrevations > after X words/characters, That's true, but you can get close with a paragraphing macro. If you're writing a paragraph so lengthy that abbreviation reëxpansion is warranted within, your paragraph might be (way) too long. .de PP .sp \\n[PD] \" The `PD` register needs to be set up by the package. .nr ux 0 .ft R \" maybe .\" other stuff > or after a page break, though. Yes, but there's a way to do that. > Perhaps traps could be used for this? I don't have much expertise with > them; only time I've tried to use one I horribly failed... You guessed it. Any macro package that does page layout in any manner more sophisticated than line printer-style blasting of 66 lines to an 11-inch page (the *roff default) will set up page headers and footers, and so traps will already be in use. All you need to do is piggyback on an existing one. For the purpose of resetting a flag, either can be made to work, but I'd probably pick a header trap. .de HD .nr ux 0 .. The macro package will already have done something like this. .wh 0 HD or .de PT .sp .5i .tl '\\*[LH]'\\*[CH]'\\*[RH] .if d HD .HD .. .\" other package setup .wh 0 PT > One aspect of this I had *not* considered, was a ergonomic way of > handling how/where the abbreviation(s) are defined. I have written a > script before for this task (working with abbreviations) for my > webpage authoring, but I was content to write the expansion everytime > I referenced the abbreviation, even if it didn't show in the text. > There was also a list of abbreviations with well-known definitions > hard-coded in the script, such as HTML and CSS... I never said it was > a super elegant program; it's just a script I use! This is probably > easily handled in roff with strings and/or macros; a user could define > strings or macros with the abbreviation and its definition, and our > abbreviation macros could probably work over these in a generic way? I'm not sure I'm completely understanding you here, but I think I might have illustrated above the techniques you're wondering about. Incidentally, the names I've picked for most of the examples I've given bear a suspicious resemblance to those used by groff_ms(7) and earlier implementations of the manuscript macro package. Please let me know if this helps, or doesn't. Regards, Branden
signature.asc
Description: PGP signature
