Re: Inconsistent macro notation in manual pages.

"G. Branden Robinson" <[email protected]> Sat, 21 Feb 2026 14:28:41 -0600

Newsgroups	gmane.comp.printing.groff.general
Message-ID	<20260221202841.qlzhm26lpyrrxuwp@illithid>

[another self-follow-up]

At 2026-02-21T13:01:02-0600, G. Branden Robinson wrote:
>     The availability of groff, which included from early days not just
>     a reimplementation of man(7) but of its SunOS 4 variant, widely
>     considered by Berkeley acolytes to be the best realization of the
>     BSD system.  (And just LOOK at how much money Bill Joy was
>     making!)

I managed to not properly construct the first sentence.  I'll recast.

Much of mdoc(7)'s reason for being was immediately undercut by the
availability of groff, which included from early days not just a
reimplementation of man(7) but of its SunOS 4 variant, widely considered
by Berkeley acolytes to be the best realization of the BSD system.  (And
just LOOK at how much money Bill Joy was making!)

Incidentally, this is why mdoc(7) partisans carry on at high volume and
great length about its superiority to man(7)--because it has "semantic"
macros.  That's the only advantage it's retained since Net/2 in 1991.

Unfortunately (or not), it has many such macros, which lengthens the
learning process and discourages adoption.

Documentation writers too often seem to adopt an attitude of
indifference to semantic markup, which might explain man(7)'s persistent
popularity, mdoc(7)'s relative lack of it, and the silence that has
faced my proposals to extend the man(7) package--backwards-compatibly,
even!--to embrace them.

https://lists.gnu.org/archive/html/groff/2023-10/msg00034.html

No matter what the environs, a horse that isn't thirsty won't drink.

The wide popularity of non-semantic markup languages like Markdown and
reStructured Text hints at a darker possibility: a lot of implementors
suck at documenting their systems with semantic tools because thinking
carefully about the semantics of their systems freezes them up.

Regards,
Branden

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