Dash docset updates

Volume 4, Issue 26; 18 Apr 2020

Updates and additions to the Dash docsets I mentioned recently.

A week ago or so, I described some work I’d done to make the XML specifications that I use frequently available in Dash.

Since then, I’ve been tinkering in the evenings, mostly in the time between what would reasonably be considered the end of the day and the beginning of my next meeting. (California, as I observed, is a lot of hours west.)

The latest updates are in the same place:

What’s changed?

  1. I decided to “chunk” the files. Dash is designed to be an API inspector, not a general purpose document reader. Mostly, I think that means it works best for targeted searches: how does the p:cast-content-type step work?; what goes in the picture string for fn:format-dateTime()?, etc. To that end, smaller faster pages seemed better.
  2. I stripped out script tags and a few navigation links that don’t make sense in this context.
  3. I added an “Annotation” index entry that includes details about the Dash conversion, including the version of the document. It’s weird that Dash doesn’t seem to have a standard place for version information in the docset.
  4. I sorted out the formatting issues with DocBook and added DocBook 5.2: The Definitive Guide.
  5. I added a few new XML specifications (XML 1.0, Namespaces 1.0, XML Base, XInclude, and XML Schema parts 1 and 2).
  6. I renamed the .tgz files to .docset.tgz because apparently that makes one of the Windows Dash clients happier.
  7. I’ve tried to make good use of index entry types. This works better in some specifications than others. I haven’t tracked down and identified every single anchor as an index entry. That said, if you think I missed a useful one, let me know.

Please try them out and report problems you encounter. I have one report of the XML Schema docsets not working correctly in the Windows client, but they look fine to me. Someone also asked about contributing these to the Dash. Yes, I’m happy to do that, but I’d like to wait a bit and see if any bugs are reported.

In other news…

I was delighted to discover an Emacs integrationThe dash-docs repository suggests that it doesn’t work on MacOS, but it works just fine for me with Emacs 27.0.91. (I had to build my own Emacs to get SVG support and I figured I’d go ahead and move up to 27.) for Dash:! Here’s my current config:

(use-package dash-docs)
(use-package helm-dash)
(require 'dash-docs)
(require 'helm-dash)
(setq browse-url-browser-function 'eww-browse-url)

(defun xml-doc ()
  (setq-local dash-docs-docsets
              '("defguide52" "file-30" "mail-30" "os-30" "paged-media-30"
                "rdf-30" "steps-30" "text-30" "validation-30" "xinclude"
                "xml5e" "xmlbase" "xmlns" "xmlschema11-1" "xmlschema11-2"
                "xpath-31" "xpath-datamodel-31" "xpath-functions-31"
                "xproc-30" "xquery-31" "xslt-30"
                "xslt-xquery-serialization-31" "xvrl")))
(add-hook 'nxml-mode-hook 'xml-doc)

(defun python-doc ()
  (setq-local dash-docs-docsets '("Python_3")))
(add-hook 'python-mode-hook 'python-doc)

;; etc.

It works really well!

At any point, I can hit my “dash docs” key binding, enter the first few characters of the API I’m interested in, and quickly get a menu of links to relevant docs.

Dash Docs

If I’m editing XML, the doc choices come from the XML docsets. If I’m editing Python, the doc choices come from the Python docs, etc.

Unfortunately, it looks like Dash has started saving the actual web pages in a compressed archive (a tarix.tgz file) so newer docsets don’t work in Emacs. Emacs could be made to support that, but it’s not going to make its way onto my todo list. I did quick experiment and it seems like unpacking the archive also works, so I’ll probably just do that.