so

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: https://dash.nwalsh.com/.

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: https://github.com/dash-docs-el/! 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 ()
  (interactive)
  (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 ()
  (interactive)
  (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.

[Image]
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.

Comments

Hey!

As coauthor of dash-docs, thanks for a detailed description of how dash docs work in emacs, and for the bug report over there at github.

There were some issues with Macs at some point, glad it's now working fine

We might link your article from there also

Please provide your name and email address. Your email address will not be displayed and I won’t spam you, I promise. Your name and a link to your web address, if you provide one, will be displayed.

Your name:

Your email:

Homepage:

Do you comprehend the words on this page? (Please demonstrate that you aren't a mindless, screen-scraping robot.)

What is six times four?  (e.g. six plus two is 8)

Enter your comment in the box below. You may style your comment with the CommonMark flavor of Markdown.

All comments are moderated. I don’t promise to preserve all of your formatting and I reserve the right to remove comments for any reason.