Introduction

This package provides an Elisp interface to query and show documentation using Dash docsets.

It doesn’t require Dash app, we rely on any html file browser, however eww is recommended!

Version

• Alpha 0.0.3

Requirements

• SQLite3

Dependencies

• xml
• url
• url-http
• mm-decode
• json
• cl-macs

Tested on

Emacs	27.1	28.0
FreeBSD	12.1
OpenBSD	6.8

Installation

Manually

Clone ddoc-el repository to an arbitrary location:

$ git clone https://github.com/lambdart/ddoc-el ~/.emacs.d/site-elisp/ddoc

Add Dash-docs directory to load-path in your Emacs initialization file (init.el) and load it.

;; add to load-path
(add-to-list 'load-path "/replace/me/to/ddoc/full/path")

;; load ddoc feature
(require 'ddoc nil t)

• Note: For a more dynamic approach:
  • M-x load-file RET
  • M-x load-library RET ddoc RET

Compile

• Note: Optional (recommended).

To compile the files to the Elisp byte-compiled representation:

[at-ddoc-root-directory]$ make

Docsets

Dash-docs uses the same docsets as Dash.

You can install them with M-x ddoc-install-docset for the official docsets or M-x ddoc-install-user-docset for user contributed docsets (experimental).

To install a docset from a file in your drive you can use M-x ddoc-install-docset-from-file.

That function takes as input a tgz file that you obtained, starting from a folder named <docset-name>.docset, with the command:

tar --exclude='.DS_Store' -cvzf <docset-name>.tgz <docset-name>.docset

as explained here.

Customize

ddoc-docsets-path

is the prefix for your docsets, defaults to ~/.docsets.

ddoc-min-length

tells ddoc from which length to start searching, defaults to 3.

ddoc-browser-func

is a function to encapsulate the way to browse Dash’ docsets, defaults to browse-url. For example, if you want to use eww to browse your docsets, you can do: (setq ddoc-browser-func 'eww).

When ddoc-enable-debugging is non-nil stderr from sqlite queries is captured and displayed in a buffer. The default value is t. Setting this to nil may speed up queries on some machines (capturing stderr requires the creation and deletion of a temporary file for each query).

Variables

Common

ddoc-common-docsets

is a list that should contain the docsets to be active always. In all buffers.

Local

Different subsets of docsets can be activated depending on the buffer. For the moment (it may change in the future) we decided it’s a plain local variable you should setup for every different file type.

This way you can also do fancier things like project-wise docsets sets.

(defun go-set-docset ()
  (interactive)
  (setq-local ddoc-docsets '("Go")))

;; add hook
(add-hook 'go-mode-hook 'go-set-docset)

FAQ

• Does it works in MacOS/Windows? Duno…
• Does it works in Linux/BSDs? Yeap!
• When selecting an item in ddoc, no browser lookup occurs with Firefox and Emacs >= 24.4:
  

  Try:
  

  ;; customize function to display the current
  ;; buffer in a ww browser
  (customize-set-variable 'browse-url-browser-function 'browse-url-generic)
  
  ;; customize the name of the browser program used
  ;; by `browse-url-generic'
  (customize-set-variable 'browse-url-generic-program "/path/to/firefox")
  
  ;; customize default function to browse Dash’s docsets
  (customize-set-variable 'ddoc-browser-func 'browse-url-generic)
      

References

1. https://kapeli.com/dash
2. https://github.com/dash-docs-el/dash-docs
3. https://www.gnu.org/software/emacs/manual/html_node/elisp/index.html

LICENSE

MIT

EOF

Computer science is no more about computers
than astronomy is about telescopes.

Edsger Dijkstra