Why we're stuck with man(7) (was: man/man8/ldconfig.8: document system-wide tunables)

"G. Branden Robinson" <[email protected]> Fri, 10 Jul 2026 14:58:54 -0500
Newsgroups	org.kernel.vger.linux-man
Message-ID	<20260710195854.ud4riftmhrfzu54d@illithid>
Hi DJ,

At 2026-07-10T14:12:10-0400, DJ Delorie wrote:
> Alejandro Colomar <[email protected]> writes:
> > 	mandoc: .tmp/man/man8/ldconfig.8:250:2: WARNING: skipping paragraph macro: PP empty
> > 	mandoc: .tmp/man/man8/ldconfig.8:270:2: WARNING: skipping paragraph macro: PP empty
> 
> Fixed.  I think.  We need a better language for this ;-)

21 years ago I figured we'd get one that would conquer the world.  We
haven't.  Too bad.  I could have started working on groff back then.

Here's a summary of how we got here.

* man(7) (Bell Labs CSRC, 1979) was "good enough" ("worse is better").
  At least one generation of Unix people came up venerating the
  documents written using it.
* Many, many programmers don't want to _write_ documentation at all.
* Many programmers' managers regard documentation as an unwelcome
  friction slowing down the launch of a Minimum Viable Product.
* Many of the programmers who _do_ want to write documentation don't
  want to compose it in anything more complex than Markdown.
* Markdown can't do semantics.
∴ Goodbye, "semantic Web".

* People who did want a semantic Web ran into problems.
* XML overpromised and underdelivered.
* DocBook-XML was lexically overcomplicated--meaning hard to learn--with
  something like 400 elements.  A part-time practitioner, such as a
  person writing in a "real" programming language, could not retain the
  markup language in their head between periods of exile to
  Documentation Land.  Further, its toolchain, involving stuff like jade
  and opensp, was heavyweight and difficult to work with.  And also
  written in Java because Java was going to be the One Language to Rule
  them All, with C and C++ forgotten, by 2005 or so.
∴ "Semantics" got a bad rap because everyone with a fat wallet who
  backed it bet on a losing horse for the delivery of said semantics.
  They spent 10+ years telling the world that XML was the _only way to
  do semantics_.  And because venture capitalists and tech bros are
  infallible geniuses in black turtlenecks, everybody believed them.

* There's mdoc(7), which one might uncharitably say brought you the
  worst of all worlds.  Semantics?  Yes!  But many element types.  (Only
  about 1/4th as bloated as DocBook, though.  And Ingo Schwarze insists
  you can get by with much less than that.  Until you guess wrong and he
  reviews your document.  ;-) )  And if you don't like *roff as a macro
  system, wait until you discover mdoc!  It implements a macro processor
  on top of your macro processor!  And mdoc(7) was only created in the
  first place because AT&T were such jerks about the licensing of troff
  (and Unix generally).  So the Berkeley CSRG's mandate, I infer, was to
  spec out a macro system that could eventually be ripped free of troff
  and set down on top of something else.
* That decision, taken in maybe 1987 or 1988, predated by only one year
  the advent of James Clark's "groff", which BSD promptly shipped in
  Net/2 and later 4.4BSD.  (Later, its descendants ripped it out
  again, because GPL and C++ bad.  BAD!)
* That "other" macro system didn't arrive until about 2010, in the shape
  of mdocml(1)--now known as mandoc(1)--which, because man(7) documents
  had not had the decency to shrink below 90-95% of man pages on all
  systems, ended up reimplementing huge chunks of...troff.
∴ Almost the only people writing mdoc(7) are strident BSD partisans.
  You can write your man page in mdoc(7), but sooner or later you'll be
  asked why you aren't running *BSD, and you'll get treated like an
  idiot if you don't.  You will then understand how *BSD is a refuge
  from the evangelicalism of GNU people.[1]  ;-)

* In my estimation, TeX could have conquered this space too.  It was
  pristinely engineered (if idiosyncratically implemented), had tons of
  momentum, oodles of capable practitioners, and a benign, deific,
  universally esteemed figure behind it.
* TeX's holy mission is beautiful typography, and it's good at it.
* People read man pages on terminals 90%+ of the time.
* You can't do beautiful typography on terminals.
* Terminals can **** off.
∴ TeX ceded this ground without ever contesting it.

I've ventured my own proposal for the addition of a flexible semantic
system to man(7) with backwards compatibility, at the cost of only two
additional macro names.[2]  Literally no one has expressed interest.

So it goes.

Regards,
Branden

[1] mdoc(7) is fine.  It has some nice features, and insofar as I have
    a command of it, I'm happy to help people draft or improve their man
    pages that use it.  What it is not, is easier than man(7).

[2] https://lists.gnu.org/archive/html/groff/2022-12/msg00075.html
signature.asc (application/pgp-signature, 833 B)