Down to the Last Man, Doc!

While working through some remaining things in the build/documentation/packaging/infrastructure cleanup phase I've been going through lately, I noticed that some of the man pages hosted at this domain have become stale (there was a helpful ticket about one of them, but more or less all of them were out of date).

I'm still not entirely sure what to do about the general duplication between README files and the neglected home pages I still (barely) maintain here, but this part struck me as obviously needing to be automated.

Of course, now that my attention was drawn to them, I noticed that many of the man pages themselves were in a terrible state. In recent years I've become more enthusiastic about man pages, particularly after moving to mandoc. As a language, mdoc is dramatically better than the "traditional" man macros (the ones most often used on Linux), and includes meaningful semantic markup for more or less everything you'll need. It's still line noise to write, but you actually get something for it. Since it's semantic markup, it feels like a better investment to me: superficially ugly, perhaps, but with high fidelity as a portable source material. Converting from mandoc to just about anything, I imagine, could be done automatically easily enough, if it wasn't already supported by the tool¹.

In practice, I find that the language encourages/enables writing more consistent pages with better formatting, and mandoc, unlike groff, emits clean and simple HTML pages that can be easily styled with CSS. It's relatively pleasant to use in general, and emits sensible error messages that point directly to the problem when you screw something up. I've also come to appreciate the BSD style of man page more: the summary is actually a summary, it's less YELLEY, and there is a standard for sections and their order. I may spend most of my time in a GNU/Linux universe, but BSD got man pages right. That's not terribly surprising: BSD culture in general actually likes and cares about man pages. GNU treated them as an unfortunate legacy to prop up a failed successor (info). Of course the BSD tooling around man pages is much better. I tend towards BSD style for command line interfaces anyway, but you can document GNU-style long options in mdoc as well.

So! If I'm going to be putting energy into man pages, I might as well convert them to mdoc. I think good tooling is very important, and nice command-line tools with clear and articulate man pages are a part of that. Unfortunately, neither the LV2 tools themselves nor their documentation have frankly ever been of very high quality. Addressing this is one of the next themes of upcoming work, but for now, simply converting the existing content (with a few touch-ups along the way) is an easy step forward. It meshes nicely with the "bring all projects in line with a consistent set of 'modern' quality standards and automate everything" arc I've been on lately anyway.

The process of going through all of these has made me realize that I should prioritize the tool work, because the state of some of these tools is frankly embarrassing, but, uh, pay no attention to the man behind the curtain! It's a formats and infrastructure kind of day!

Having manually converted all the pages and checked them in the terminal, I needed a place to have them automatically updated, converted to HTML, and uploaded. The (not-really-existing) lv2kit project is the (not-really) parent of LV2 itself and all the "official" libraries, so I put it in CI there for the time being. I don't know what the best organization is for man pages under the LV2 umbrella in the grand scheme of things, but for now, this gets things automatically updated and online:

• lv2apply
• lv2bench
• lv2info
• lv2ls
• serdi
• sord_validate
• sordi

It's possible to build the documentation into a broader HTML page to integrate with toolbars and the like, but for now these are just complete pages straight out of mandoc. I did however write a simple stylesheet to adopt the same colours, fonts, spacing, typography-inspired minimalism, and infamous green links that I use everywhere, so things at least look reasonably coherent. I think it looks Good Enough™, anyway, but more relevantly, if you poke around in the document structure you'll see that the output is, for the most part, sensible semantic markup as well: lists are lists, sections are sections, different "sorts" of things are given classes, tables aren't abused, and so on. Everything here, from input to output, is reasonably clear and feels like it has obviously had some care put into it. The output looks like something a reasonable human might write themselves (if you run it through a formatter, anyway). I certainly can't say any of that about the equivalent groff-based monstrosity. In short, mandoc is good and you should use it.

As for these pages, the future of lv2kit as an "actual" released project is still unclear, but it is regularly updated (since the libraries rely on it for CI), so the man pages should never be stale again. I certainly wouldn't call these good yet, but not rotten is a start!