Hi Jonathan, At 2025-01-15T22:01:28+0000, Jonathan Dowland wrote: > On Wed Jan 15, 2025 at 9:42 PM GMT, G. Branden Robinson wrote: > > As someone who has a bit of a preoccupation with man pages > > You've reminded me that you presented 'Write the Fine Manual' in 2005, > (possibly at DebConf?).
I did! When I spent some time in a semi-conscious self-exile from Debian, I didn't look at it for many years. I stumbled across it again after getting involved with groff, and I'm pleased to say that the thing isn't _riddled_ with embarrassments. I would also admit that it has had zero measurable effect in improving man page composition practices. > I thought it was a really good slide-deck, but it's either unavailable > or at least hard to find now. Would you be prepared to put it back up > somewhere? I have a copy of the PDF (which I am happy to circulate) > but not the LaTeX source. I had a disgraceful episode of data loss, and cannot put my hands to it, or I'd share it. Only _almost_ happily, because I'd feel morally obliged to: 1. Bring it up to date, and 2. Rewrite it in groff, of course! ...moments later... Ah, the Internet Archive to the rescue! https://web.archive.org/web/20061206200701/http://people.debian.org/~branden/talks/wtfm/wtfm.tex Man, that page brings back memories. You'd think I'd have bothered to acquire an M1 helmet and a canteen cup by now. No microplastics! > (It's possible that modern tools to generate manpages from other > sources are better than they were in 2005, but I doubt it) More exist, and they are on the whole gradually getting better. However, improvement seems to happen _only_ when Ingo Schwarze (mandoc(1) maintainer) or I (or, God help them, both of us) show up on their web-based development sites to offer advice, usually in response to someone else's issue/MR/PR. As a rule, developers of these generation tools (a) do not subscribe to the groff mailing list, (b) do not file bug reports against groff, and (c) do not otherwise contact groff developers nor, as far as I can tell, experienced *roff users, to ask questions or seek guidance. In my assessment there exists a Big Four of man(7) generators, and one ignominious but noteworthy also-ran. The Big Four: 1. podlators/Pod::Man -- a proud exception to some of the generalizations above. First, it's been around probably longer than any of these others, maybe by a margin of decades. Second, it was initially developed by people who seemed to have a good grasp of the man(7) macro language and the underlying roff(7) one--in other words, old school Unix graybeards who knew their way around troff sufficiently to submit a USENIX paper. A dying breed. Third, the long-time maintainer is Russ Allbery, whom I trust needs no introduction to this list's readers; Russ has approached the groff@gnu list with questions when he's had them (a rare occurrence, because the guy seems to generally know what he's doing--somebody should nominate him for TC or something[1]). Ingo Schwarze--a difficult man to impress--and I agree that Pod::Man's output is probably best-of-breed among the Big Four. Downsides? Perl's sex appeal as an implementation language has fallen precipitously over the past 20 years--in fact I think I saw some "old and busted, seeking new hotness" sentiments expressed about it recently on this very list--and absolutely no one selects a new programming language on the basis of how well its support infrastructure can generate high-quality man(7) documents. Pod::Man also has some idiosyncrasies, like a smoldering hatred of adjusted text in paragraphs, which presents some minor difficulties when it collides with missing features in traditional troffs. But as a rule you have to go out of your way to produce _bad_ output with Pod::Man, and when it _is_ bad, it's likely bad in _all_ of its output formats. That's enough to keep irascible types like Ingo and me from griping very much. Example of pod2man/groff interaction: https://lists.gnu.org/archive/html/groff/2024-03/msg00078.html Russ is the only man(7)-generator maintainer who has presented me with a problem I haven't figured out how to solve nicely. I trust he knows I'll have my revenge. 2. Pandoc. Haskell developers are seldom short on ambition and that tendency shows up here. It's also an interesting case in that its mission seems not to be as restricted to support infrastructure for a programming language being promoted as the others are. It also tries harder to be a _bidirectional_ converter than our other specimens. If anyone can successfully come up with a metalanguage to characterize every documentation markup language in the world, it'll be a bunch of type theorists. Example of pandoc/groff/mandoc interaction: https://github.com/jgm/pandoc/issues/9020 3. Docutils. Python's documentation generator. Example of docutils/groff interaction: https://sourceforge.net/p/docutils/patches/205/ 4. Asiidoctor. Ruby's documentation generator. Example of asciidoctor/groff interaction: https://github.com/asciidoctor/asciidoctor/issues/4430 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. Regards, Branden [1] Yes, I know.
signature.asc
Description: PGP signature
