Re: .OP macro in man macro package

"G. Branden Robinson" <[email protected]> Tue, 24 Feb 2026 11:14:02 -0600
Newsgroups	gmane.comp.printing.groff.general
Message-ID	<20260224171402.2twjr67tcbaliasy@illithid>
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 (application/pgp-signature, 833 B)