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

--c7us4whjzhz2xtka
Content-Type: text/plain; protected-headers=v1; charset=us-ascii
Content-Disposition: inline
Content-Transfer-Encoding: quoted-printable
Subject: Re: 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-03T14:44:55+0000, Joseph Myers wrote:
> On Mon, 3 Aug 2026, G. Branden Robinson wrote:
>=20
> > On the bright side, I wager that a domain-specific translator to get
> > from 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.
>=20
> We do in fact have such translation for GCC and binutils; parts of the=20
> Texinfo manuals are marked up for extraction with a script texi2pod.pl=20
> with the results then going through pod2man (as shipped with perl). =20

Now that you mention it, that does ring a bell.  I probably didn't think
of it because you're using POD as an intermediate format.  That
forecloses some possibilities, but mandoc(1) maintainer Ingo Schwarze
and I share the opinion that it is the best-of-breed man(7) generator.
I reiterate, though...you give some things up with POD, like tables.

> (Being intended for converting instructions for invoking a
> command-line program, rather than documentation for library functions,
> no doubt significant changes would be needed to be useful for glibc;

I agree.  Every time I've looked (cursorily) at a problem with this
shape, I've thought, "mmmm...tricky", and moved on.

> also, the glibc manual documents lots of things outside of the
> individual function descriptions, and that information wouldn't end up
> in such generated man pages because it's not suitably structured to
> put in them.)

Yes.  Every few years someone asks the groff list why we haven't just up
and converted our Texinfo manual to man pages yet.

Structure.  The biggest impedance mismatch is structure.  Steve Summit
raised the famous old point about a "reference, not a tutorial", and I
don't know if I'll work up the steam to reply to him more fully, but
that proves a tough boundary to police.

There are people who will read _only_ man pages and never anything else.
Those people release a horde of Hyrum's Law gerbils into your system.

Regards,
Branden

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

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

iQIzBAABCAAdFiEEh3PWHWjjDgcrENwa0Z6cfXEmbc4FAmpwsSIACgkQ0Z6cfXEm
bc6mFQ/+N5GSfUPmixxq80iWjEqC5ciUJHz55DSHaSyXf7NMXTSr3nRuGuN8LSBY
8jl7+x6YDkY9Ozodg2lndm57KjxMpUR0SUhueHnSaBn2oJKONGMuOCiBMu7tdCkn
f9VKgt4TMTFAo3uvGO6AA3736edHgaZTXqRd76EYu04SxOEQcnBLAn9IQGsnx0T1
KHxaf32DjDz2faQHvPTx/u7uGZBG5tHgBlU6uWiHzKuCDcgDZOZMHRE17lfX7OVu
t6zocMKwwBDZtCCNLguZpdHd97jB7npk0VYZ99Rl1GhrrzTBk5tGin96mhZMxkeX
UpVH6JA+EFRtYOlnlMwdrbguQkqzMgmlSSp3f4L+tVLieRFkSycZjx1psow/rLQc
KGoMldvSFSkZmQiDOxZAtGyAT2nRLFuEf2a42Ka8gVIsUDo/bQ77dV8QGoR75nPK
/UX8uUQjNOBqKV7fIlkHNLDvZbr76tFGhZdjQ21WifcRuE9oiiK7W6sRW0FqIUpX
rmishNxpCkYdIVZL/i02fkp/JUeow+nCtc7oLddf7Z/Nvjz1zQa8X34+2OMxBXpB
Bo57+4UH3McPipVHivhphFsSqBmuIj9VYaKlDJgpBVNA8v6IvTYfsZ0pxcJSCj/U
7RolzN//zx11qdWDRnRZq+a+jB+PkxyxV8czmpbrc9eqJq/qXTQ=
=LR7w
-----END PGP SIGNATURE-----

--c7us4whjzhz2xtka--