Re: Inconsistent macro notation in manual pages.

"G. Branden Robinson" <[email protected]> Sun, 22 Feb 2026 11:00:37 -0600

Newsgroups	gmane.comp.printing.groff.general
Message-ID	<20260222170037.nhv3gxbt34pzueis@illithid>

At 2026-02-22T13:09:24+0100, Morten Bo Johansen wrote:
> On 2026-02-22 dvalin--- via GNU roff typesetting system discussion wrote:
> > Excessive consistency can sometimes reduce utility, in my experience.

> But the bottom line here is that the macro description for e.g. the .AU
> macro in groff_ms looks like this:
> 
>     .AU    Specify an author’s name.  ms collects text on input lines (...)
> 
> and in groff_mm, for an identically named macro, it looks like this:
> 
>      AU [name [initials [loc [dept [ext [room [arg1 [arg2 [arg3]]]]]]]]]
>              Specify author
>              
> This is just plain inconsistent in a non-excusable way.

I largely agree.  I'm not happy with it.

But I'd resolve the inconsistency in the opposite direction from your
preference, and leave groff_man*(7) inconsistent with the new norm on
purpose, because so many authors of man(7) documents read and learn
nothing else about *roff and, inasmuch as they don't learn it, they
really shouldn't be undertaking macro definition on their own.  Let
alone renaming, removing, appending to, or aliasing macros.  Those
operations demand more than a superficial understanding of the
formatter's language.  (You can get away with cargo-culting until a
crate explodes...)

In my previous response I sketched a medium- to long-term solution for
improving search operations on man page contents.

Regards,
Branden

signature.asc (application/pgp-signature, 833 B)