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 tool1.

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:

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!


  1. mandoc currently supports emitting ascii, html, man, markdown, pdf, ps, tree, and utf8

On the LV2 Stack, Dependencies, and Incrementalism

For quite a while now, I've been working on new major versions of the LV2 host stack (serd, sord, sratom, suil, and lilv) while maintaining the current stable versions. Mainly this is a task of trying to push as many changes back as I can, without actually breaking any APIs. Aside from the usual bug fixes and code improvements, this includes a lot of build system, tooling, and general quality control improvements. This keeps the divergence low, so it will be easier to go back and do maintenance on the old versions where necessary.

At this point, this process is almost done: everything uses meson now, has a consistent QC regime (high-coverage testing, multi-platform CI, strict compiler warnings, machine formatting, clean clang-tidy configurations, and so on), most long-standing issues are fixed, and I'm finally starting to run out of changes that I can do without finally breaking the APIs and releasing new major versions.

It recently occurred to me, though, that there's one more incremental thing I can do here before "ripping the band-aid off", so to speak. In typical low-level C hacker fashion, I have some things that I just copy around piecemeal from project to project as necessary. One of those is zix, a simple library of basic data structures and portability wrappers. This has existed for over a decade, but I have never released it as a "proper" library. More dependencies, more problems, but copy-paste code reuse certainly isn't without its own problems. In this case, I have three projects that use it: sord, lilv, and jalv (and some other developers have discovered this and taken bits for their own purposes as well). This has been troublesome from time to time when bugs need fixing, and depending on how pedantic you are, might technically be considered a violation of some distributions' policies (notably Debian's).

Meanwhile, the lack of a common lowest-level dependency for this kind of very boring and generic stuff (something like the role that glib plays in that ecosystem) has proven increasingly problematic. There is some sketchy code around that exists solely to work around this "missing" dependency, and still some questionable use of things to skirt around missing facilities (for example, jalv has no mutexes). With the new versions I have in the pipeline, this problem becomes more acute for several reasons, so I've decided to release zix and depend on it as a proper released and versioned library, like all the others.

This is something that can be done before the new versions though, and, like all of the above tooling/etc improvements, I think it's best to do as much as possible on the current versions before replacing them, because that process will be painful enough as it is. My thinking originally was to not add any more libraries until I can take advantage of the solid "subproject" abilities of meson and wrap everything up into a single "lv2kit" to decrease the maintenance and packaging burden, but now I'm realizing that this isn't very realistic. For one, it's weird, and weird is bad. For another, it wouldn't really reduce packaging overhead, since distributions would surely want to package the individual libraries separately anyway. The lv2kit idea is still a goal, but pragmatically, I think it's best to just continue on in the good old "shotgun blast of little libraries" way and deal with that later.

Concretely, that will look like this:

serd <--\--- sratom
         --- sord --- lilv --- jalv
zix  <--/------------/--------/

That is, zix will become a thing, and sord, lilv, and jalv will gain it as a dependency. This will let any issues with packaging or subprojects or whatever get ironed out, without changing any of the APIs that LV2 hosts use directly whatsoever.

... and that, I think, is the last non-trivial thing I can do without rocking the boat, before the fun part where I finally get to change whatever I want in these APIs I hastily banged out over a decade ago now, and never intended to live this long in the first place. The dependency tree may get a bit more complicated, but a whole bunch of other things are going to get wildly simplified in exchange, which seems like a pretty good deal to me.

I Was Told The Crowd Would Have Funding

I am, like many an obsessive nerd before me, terrible at self-promotion and living a healthy and sustainable life in general. However, as I sit here sick, burnt-out, and slowly going broke while I desperately dump what little energy I have into boring software that mostly benefits other people, it occurs to me that it might be smart to set up the usual channels for people to support this work, and mention them here (despite how embarrassing it is to do so).

It's pretty well-known these days how brutal and thankless it can be to maintain Open Source infrastructure. While I enjoy what I do around here in a way, truth be told, I'm not sure I can do it much longer. In an ideal sense, my grand plan (as described in some earlier posts) is to get the foundation solid and increase the LV2 "bus factor" so I can return to building user-facing things and tackle some new problems which tends to be more rewarding. Realistically, though, I may just be cleaning things up and minimizing the maintenance overhead so that I can hand them off or simply abandon them without feeling too bad about it. Time will tell, but if any of this helped at all with surviving the ever-skyrocketing cost of living... well, it certainly wouldn't hurt my motivation.

So! In addition to the old direct donation and subscription links on my donation page, I've set up Github Sponsor and Patreon accounts. If you're reading this, presumably you know about the various projects I author, maintain, or contribute to. If you use or benefit from any of that and can spare a few bucks, I'd appreciate any support. Every little bit really does help.

Patchage 1.0.10

Patchage 1.0.10 has been released. Patchage is a modular patch bay for Jack and ALSA based audio/MIDI systems.

Changes:

  • Add German translation
  • Add Korean translation from Junghee Lee
  • Add i18n support
  • Replace boost with standard C++17 facilities
  • Upgrade to fmt 9.0.0

Jalv 1.6.8

Jalv 1.6.8 has been released. Jalv (JAck LV2) is a simple host for LV2 plugins. It runs a plugin, and exposes the plugin ports to the system, essentially making the plugin an application. For more information, see http://drobilla.net/software/jalv.

Changes:

  • Add Gtk plugin selector UI and desktop file
  • Add missing option in console help output
  • Add version option to console executable
  • Build Qt interface as C++14
  • Change no-menu short option to m to avoid clash with jack-name
  • Clean up and modernize code
  • Fix "preset" console command when "presets" hasn't been called
  • Fix MSVC build
  • Fix atom buffer alignment
  • Fix crash when running jalv without arguments
  • Fix man page headers
  • Fix memory leaks
  • Fix outdated man pages
  • Fix spurious transport messages
  • Fix thread-safety of plugin/UI communication rings
  • Flush stdout after printing control values in console interface
  • Print status information consistently to stdout
  • Propagate worker errors to the scheduler when possible
  • Remove Gtkmm interface
  • Remove Qt4 support
  • Support both rdfs:label and lv2:name for port group labels
  • Switch to meson build system

Sratom 0.6.14

Sratom 0.6.14 has been released. Sratom is a small library for serializing LV2 atoms. Sratom reads/writes atoms from/to RDF, allowing them to be converted between binary and text or stored in a model. For more information, see http://drobilla.net/software/sratom.

Changes:

  • Add project metadata
  • Adopt REUSE machine-readable licensing standard

Suil 0.10.18

Suil 0.10.18 has been released. Suil is a library for loading and wrapping LV2 plugin UIs. For more information, see http://drobilla.net/software/suil.

Changes:

  • Add project metadata
  • Adopt REUSE machine-readable licensing standard
  • Fix MacOS build when Gtk3 and Qt5 are present without X11
  • Fix opening wrapped UIs multiple times in Gtk

Lilv 0.24.20

Lilv 0.24.20 has been released. Lilv is a C library to make the use of LV2 plugins as simple as possible for applications. For more information, see http://drobilla.net/software/lilv.

Changes:

  • Adopt REUSE machine-readable licensing standard
  • Update project metadata

Sord 0.16.14

Sord 0.16.14 has been released. Sord is a lightweight C library for storing RDF statements in memory. For more information, see http://drobilla.net/software/sord.

Changes:

  • Adopt REUSE machine-readable licensing standard
  • Allow programs to be used from subproject
  • Fix accidentally exposed internal zix symbols

Serd 0.30.16

Serd 0.30.16 has been released. Serd is a lightweight C library for working with RDF data.

Changes:

  • Add SERD_STATIC to pkg-config Cflags for static-only builds
  • Adopt REUSE machine-readable licensing standard
  • Allow programs to be used from subproject
  • Fix spelling mistake in serdi man page

Page 1 / 14 »