Hi Joseph, At 2026-08-03T14:44:55+0000, Joseph Myers wrote: > On Mon, 3 Aug 2026, G. Branden Robinson wrote: > > > 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. > > We do in fact have such translation for GCC and binutils; parts of the > Texinfo manuals are marked up for extraction with a script texi2pod.pl > with the results then going through pod2man (as shipped with perl).
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
signature.asc
Description: PGP signature
