Creating Dash docsets

Volume 4, Issue 25; 12 Apr 2020

Making a collection of XML specifications available for the “Dash” documentation browser.

Years ago, by which I mean “back in the ’90’s” not “back in February” which feels like it happened about a decade ago, I used to make “compiled help files” out of documents that I referenced frequently. The Microsoft help system provided some nice navigation features that weren’t (at the time) easily obtainable in the browser.

Documents in the browser today are a lot nicer, but they still have rather weak support for offline use (remember when there were airplanes?) and it’s not hard to imagine a “documentation browser” that works better (and more consistently across different sets of documentation) than a plain old browser.

Enter Dash, an “API Documentation Browser and Code Snippet Manager.” It’s really quite nice. It’s also Mac OS only so if that’s not your preferred platform, you’ve probably already started to lose interest in this post.

There are lots of useful documentation sets available for Dash. I’ve got CSS, Font Awesome, Gradle, Groovy, Haskell, HTML, Java, jQuery, Python 3, Sass, Scala, JavaScript, Emacs Lisp, Flask, LaTeX, and sbt sets installed. There are dozens, maybe hundreds of others.

You can also make your own documentation sets for Dash.

One of my favorite things about markup is how easily and flawlessly it can be transformed. If you’ve got a bunch of documents with a rational, logical structure that’s expressed using markup, you can do so much with them.

Making a Dash docset is pretty straight-forward: convert your documents to HTML, augment them with some special markup for the table of contents, extract out the “indexable” terms (sections, keywords, error codes, etc.), construct an sqlite3 index of those terms, sprinkle with metadata, package it all up in the required directory structure, and you’re good to go.

This is an obvious XProc 3.0 pipeline!I will publish the pipeline when it works, but I think I won’t expose y’all to the hackery in place at the moment. Except my XProc 3.0 processor has an ugly bug in p:viewport so it’s not actually at the moment. ☹

Nevertheless, I did convert the specifications for XProc and for XPath, XSLT, XQuery, and friends into docsets: Consider those “alpha” versions; it’s quite possible that I’ve made errors. Suggestions for improvements most welcome.

I’m working on a docset for DocBook: The Definitive Guide as well, but the current formatting doesn’t play nicely with some of the assumptions that Dash makes. I’ll publish it when I sort out those issues.

In the meantime, share and enjoy!