On Wed, Jan 15, 2025 at 06:03:42PM -0600, G. Branden Robinson wrote: > I've saved the worst for last. > > That is of course docbook-to-man. Ingo and I both find the quality of > its output to be execrable. It has been unmaintained for many years and > consistently seems to burn out and drive from FLOSS development anyone > who has gotten involved with it. Its brownfield status appears to be > widely if vaguely understood, and it is avoided--but only by its > would-be _maintainers_--like a toxic waste dump piled 100 meters deep > with burning tires, at the center of which a column of blue Cerenkov > light stabs the sky like a beacon of death. > > It is consequently extremely popular and has enjoyed wide adoption, and > continues to be thought of as a viable tool even as the luster of XML > doctypes and DocBook in particular has worn off. Notoriously, all the > Git man pages are produced via this means. This is entirely in keeping > with prototypical Linux kernel developer behavior: identify a good idea > (like having a single master documentation format from which others are > generated), select the shittiest implementation thereof available, and > nail oneself to it for all eternity. And why change? > > Yo, kernel hackers got better things to do than writing docs, bro. One > doesn't achieve world domination by telling other people how to do it.
Interestingly, in 2016 the Linux kernel switched from using DocBook to reStructedText[1]. So the flaws of ASCII doc were relatively well known as far back as eight years ago by the kernel community. [1] https://lwn.net/Articles/692704/ The problem seems to be that Sphinx is really not great for creating man pages, and very few people actually do roff these days. So the man pages in the kernel (for example, for the perf tool) and the git project are still implemented in AsciiDoc. That's probably because it's good enough for the users of docbook-to-man, even if it's a brownfield. (For example, X11 still works better for me because Wayland still has inconsistent support for cursor sizing across applications, sigh. >From windowing system and desktop developers' perspective, most probably wish X11 would die already, but users have these pesky requirements, like not having their cursor effectively disappear when it wanders into the wrong window if you are using a HiDPI display (at least, if you are using KDE; I don't know if GNOME is any better at this point, but GNOME has its own problems about listening to power users' requirements...) I'm sure that if someone wanted to help those consumers of DocBook to switch to something better, by *listening* to their requirements and then trying to meet them, and showing them how to do an automated job of converting of their man pages from one source format to another, most projects would be willing to switch. But that's a huge amount of work for any volunteer or volunteer community to take on, whether it's the git development community or some documentation tool community. - Ted
