on glibc forking/reclaiming its man pages (was: on the irresponsibility of pursuing C language reform)

--bdyw23mt5wvqvtua
Content-Type: text/plain; protected-headers=v1; charset=us-ascii
Content-Disposition: inline
Content-Transfer-Encoding: quoted-printable
Subject: on glibc forking/reclaiming its man pages (was: on the
 irresponsibility of pursuing C language reform)
MIME-Version: 1.0

Hi Joseph,

At 2026-08-03T13:42:31+0000, Joseph Myers wrote:
> I suggest we need to figure out how to generate man pages from the
> glibc manual so that people who prefer documentation in that format
> can have documentation of glibc interfaces that's maintained by a
> proper consensual process rather than following one person's opinion.

I speculate that Richard Stallman expected that this sort of thing would
be soon implemented and accomplished...in 1989.  Or earlier.

Official GNU documentation continues to suggest that (Tex)Info shall
prevail and that man pages are destined to wither away, as Engels
predicted of the State.

https://www.gnu.org/prep/standards/html_node/Man-Pages.html

Speaking from experience as a GNU maintainer and from observation of
others, I assess the task you outline as anything but easy.  Chet Ramey
has been maintaining Bash documentation in parallel man(7) and Texinfo
forms for decades.

https://lists.gnu.org/r/coreutils/2026-05/msg00044.html

In groff, I maintain a ~300 page Texinfo manual alongside ~400 pages of
man pages.  Overlap is only partial; the Texinfo manual focuses much
more on specifying the formatter's behavior in exhaustive detail, in
about 180 pages of the total length--much more than half when you
consider that about 60 pages are given over to indices and the GNU FDL
license text.  The man pages document groff's preprocessors, output
drivers, utilities, wrappers, macro packages, and so forth.

https://www.gnu.org/software/groff/manual/

(groff's Texinfo manual will look much nicer, and additional manuals in
PDF format will be available, in a couple of weeks when I release groff
1.25.0 final--knock wood.)

At the same time there _is_ substantial overlap between a few of our man
pages and groff's Texinfo manual.  You can find comments in the source
documents referring to "keeping sync".

I perform such synchronization by hand, and not perfectly.

Even after years of experience doing this, I've found that nailing down
the parameters of what would be required to automate such
synchronization is tough.  Autogeneration of one format from the other
would, I think, be a closely related problem.

If the task were easy, someone would have done it by 1990.

If the task were of medium difficulty, I suspect the Pandoc project
would have solved it with a Texinfo reader by now.

https://pandoc.org/MANUAL.html

They haven't, so far.

On the bright side, I wager that a domain-specific translator to get
=66rom a specific Texinfo manual--likely one that imposed special rules on
its maintainers to enable extraction of data necessary for man page
production--could be written.  The job will demand someone with solid
domain expertise in both formats.  Better, such people actually exist.

I'm available for consulting work.  Do you have budgetary authority?

Or, you know, there are LLM coding agents...

As a third option, we could lower the temperature just a little bit.  In
an email on project management that I'm still drafting, I implicitly
suggest that Alex do the same.

Regards,
Branden

--bdyw23mt5wvqvtua
Content-Type: application/pgp-signature; name="signature.asc"

-----BEGIN PGP SIGNATURE-----

iQIzBAABCAAdFiEEh3PWHWjjDgcrENwa0Z6cfXEmbc4FAmpwp9EACgkQ0Z6cfXEm
bc46vw//Uy4oP4rhXtBMH2OyscJfNAy/aSRS0DAbucPfrFWvPIUxJ/6ckw8eBVgt
yocwLFOcjtghAqcfwGh04VvHROSSw+jl07vrM0T5dj0PnEhzrjSFJ9EZPSsn22vv
iuJ4JEhP71ikh2PFf6GbVMJpcmDX6eVmuiTZQ1v2LvP4nZQZGepIj3gbKTJVg0Nf
6lTfb9No15O+LFvc+KU5wvOMu5xDA1dOL/K5uI7JWqeNH+bNAtJ0vDrYU4wwuJz9
v9qa96ZqfWhEBPYEt+jz/pm5WkoGGv82eJSPq/BVzi2TGEnynfSZLR8Impg9pt/g
y/qlhJOQLVQezmiDQPTm9LwHNarROQa2dvNE3zRRaE2H8veX379XGqbBlBJmD3XS
kp4EnA/DrgtpQvXh02dKnZ17vesnm00kbc3C7R0slwRXLfoP/zbSpPvHeR6Z3AR1
/9zan0MIxMUxYjf+wYM5sigQrDlHP2MWVtVekhiIMzJASSn6Z8Qk5UXmZZp+F3Zv
nFmysfOJMjCUKQzl8Y8g6Wm3fx7MKSSdtE9B8/bYNL+PWzBzJAPU/84I6VoE99An
Yp7J+SAvImijNsEhzMvSS9Kon3jHFJ5566AcKlZwTjl270Q0oUmfc0/ks7ceb8Oe
yLXFua6VgtvP1rCKbQEjkaQcSmFYFUwx2ZGBWWl6BIisCzw6xLc=
=/AdK
-----END PGP SIGNATURE-----

--bdyw23mt5wvqvtua--