Hi Steve, Thanks for writing with an eye toward historical accuracy. I appreciate that. :)
At 2026-02-24T07:09:58-0800, Steve L wrote: > Hi, I noticed the below description of an ".OP" macro in > groff_man_style. However the macro as described does not exist that I > can find it. I think this was an erroneous edit and should be removed > from the documentation. By "edit", are you referring to a specific groff commit? > The description states that it appears in the Documenter's Workbench > macros which is true (see > https://github.com/n-t-roff/DWB3.3/blob/master/macros/man/an.sr ). Concur. > However I believe that it was only in the DWB man macros for > compatibility with the mdoc macros (see > https://github.com/n-t-roff/DWB3.3/blob/master/macros/man/man.5 which > states that this version of the man macros recognizes most macro > commands defined in BSD). I find this claim implausible for three reasons. 1. Since no comprehensive history of DWB troff is available, it's hard to say when DWB man's `OP` macro debuted. DWB 3.3 was released in about 1992,[1] but it seems DWB 2.0 came out sometime around 1986 or 1987.[2] Those dates are important because they bracket the introduction of the mdoc macros by the Berkeley CSRG.[3] DWB man's `OP` cannot have been motivated by mdoc if the former antedates the latter. 2. The DWB macros do not conform to mdoc's naming convention for its macros. Neither the 2nd nor the 3rd versions of the mdoc macro package implement an `OP` macro. While `Op` is present as a macro in both, *roff identifiers are case-sensitive--so offering an `OP` macro would have done nothing to help DWB man render an mdoc document. 3. Even if the macro names were identical, supporting mdoc's `Op` is far from a sufficient condition to permit DWB man to render an mdoc document. The man(7) and mdoc(7) macro languages are radically different; the latter's bespoke macro processing system, layered on top of *roff's (viz. "parsed" vs. "callable" macros, concepts unknown in any other *roff macro package) is the main culprit here. Possibly you mean that DWB man's `OP` was inspired by mdoc's `Op` rather than implemented for compatibility per se. About that, I express no opinion. > they are described in groff_man_style (compare the two excerpts at the > bottom of this e-mail). > > In groff you can grep for ".de OP" in .../tmac and you'll only find > the definition in m.tmac (where it means "force odd page" -- not > relevant). If you grep for ".de Op" you find the definition in > "doc.tmac". The file groff_man_style, as best I understand, is only > intended to document the man macros not the mdoc macros (see "See > also" section, as well as the discussion in "Files"). All correct. > I checked the Illumos version ( > https://sourceforge.net/projects/heirloom/files/heirloom-doctools/080407/heirloom-doctools-080407.tar.bz2/download > in heirloom-doctools-080407/troff/troff.d/tmac.d ) and likewise it did > not define .OP except in "mmn" and "mmt" and ".Op" in "doc.in". To the best of my knowledge, System Vr4 troff, including that used in Solaris (whence Illumos descends) is based on DWB 2.0 troff. Your observation suggests that DWB man's `OP` came in after DWB 2.0 was released. (Having DWB 2.0 sources to check this would be nice...) > Since the description of .OP does not match the DWB implementation, This is a good point and was overlooked in groff documentation for many years. In retrospect I don't think anyone anticipated that Eric Raymond, who contributed that macro to groff man(7),[4] would seize the name while implementing an incompatible interface. Further consideration of Raymond's track record suggests that such a decision was utterly predictable and consistent with other decisions of his.[5] At any rate, I stumbled across this realization myself last August. https://cgit.git.savannah.gnu.org/cgit/groff.git/commit/?id=f6d1f960dd0ee67b61884d2020dcbbbf63c2962b > which I believe was only included for compatibility with mdoc, and is > not present in groff man at all (as far as I can tell), I suggest > removing that paragraph from groff_man_style. It has been rewritten since groff 1.23.0. Here is the language that appears in groff_man(7) in the groff 1.24.0.rc4 release candidate.[6] .OP option‐name [option‐argument] Indicate an optional command parameter called option‐name, which is set in bold. If the option takes an argument, specify option‐argument using a noun, abbreviation, or hyphenated noun phrase. If present, option‐argument is preceded by a space and set in italics. Square brackets in roman surround both arguments. Use of this quasi‐semantic macro, an extension whose name originated in DWB troff, is deprecated; groff’s implementation differs. Neither can easily be used to annotate options that take optional arguments or options whose arguments have internal structure (such as a mixture of literal and variable components). One could work around these limitations with font selection escape sequences, but font style alternation macros are preferable; they are more flexible and perform italic corrections on typesetters. > I could be wrong of course but I have run this down to the best of my > ability. Your findings are mostly consistent with my own; the main exception is that I don't regard mdoc as having been more than superficially influential on DWB man's choice of name for the macro, which is easily explained on other, strictly mnemonic, terms ("OPtion"). Regards, Branden [1] https://github.com/n-t-roff/DWB3.3/blob/master/CHANGES_1993 [2] DWB 2.0 appeared between the two editions of Gehani's book _Document Formatting & Typesetting on the UNIX System_, copyright 1986 and 1987, respectively. Gehani notes its availability in the text, and in the second edition only, documents mm(7) macros new to DWB 2.0. (Most of the new macros were to support `LT` and its relatives.) "Facilities for specifying business letters have recently been added to mm [DWB 1986b]." (p. 76) [Gehani, 2nd ed., 1987] [3] What is now referred to as "old mdoc" appeared in 4.3BSD-Reno (1990).[7] Per Ingo Schwarze, that is actually the _second_ version of the mdoc macros; the first apparently never made it into a CSRG distribution and is now thought to be lost. The mdoc macros with which people are familiar today are the third version, which first appeared in the CSRG Net/2 release (1991).[8] [4] https://cgit.git.savannah.gnu.org/cgit/groff.git/commit/?id=259929625b21595951ed3ef5dba9aaaea359b464 See generally groff@gnu mailing list traffic in December 2006 and January 2007. https://lists.gnu.org/archive/html/groff/2006-12/index.html https://lists.gnu.org/archive/html/groff/2007-01/index.html [5] https://www.dourish.com/goodies/jargon.html https://news.ycombinator.com/item?id=5269755 [6] https://lists.gnu.org/archive/html/info-groff/2026-02/msg00001.html [7] https://minnie.tuhs.org/cgi-bin/utree.pl?file=4.3BSD-Reno/share/tmac/tmac.doc [8] https://minnie.tuhs.org/cgi-bin/utree.pl?file=4.4BSD/usr/src/contrib/groff-1.08/tmac/notused/tmac.doc It appears that 4.4BSD settled on groff's implementation of mdoc, which was a close descendant of the "third version" of the Berkeley CSRG's mdoc package, which seems not to have made it into any major Berkeley release but surely exists in RCS/CVS history. groff author James Clark documented in comments some minor changes to mdoc but I have no evidence of any major revisions. I think it likely that when the descendants of BSD elected to purge their distributions of the GPL'ed groff (after 2010 or so, perhaps, when mdocml/mandoc(1) became available), they reverted to the CSRG's version, but I don't actually know. Werner Lemberg and Ruslan Ermilov massively revised groff's mdoc implementation in 2001, and added some extensions. Ruslan's email address at the time used a "FreeBSD.org" domain name, so I might be wrong about the reversion. Or perhaps not, and anti-GPL sentiment actually hardened in the *BSDs between 2001 and 2010 (in my experience, it was already hard enough in 1999!--but I've told that story before). Maybe in that interim a lot of *BSD hackers took jobs at Apple, which is notoriously GPL-hostile, and seems (to me) to be the source of the folk belief held widely among American software engineers that every tech company in Silicon Valley has an "anti-GPL" or "anti-GPLv3" policy. From my own employment history in the relevant period, I know first-hand that that isn't true. But because Apple stock's share price is widely held to be ultra-performant even among non-investors,[9] tech bros regard every action the company has taken as normative and presumptively binding upon the entire industry. ...except for that time they hired John Sculley. [9] https://uk.investing.com/news/stock-market-news/heres-how-much-forrest-gumps-theoretical-stake-in-apple-would-be-worth-today--and-how-much-you-could-have-made-since-movie-was-released-3072615
signature.asc
Description: PGP signature
