Jutting Bytes

Digressions of a research engineer

Helm-Dash Makes You Efficient

| Comments

Every coder will say so: when learning a new language or using a new toolkit or library, a great documentation makes the difference. It is however usually really boring to browse when it comes as a pdf, or in html format.

Documentation engines, including doxygen, qdoc, appledoc among many great others, provide indexation and allow their authors to generate databases for fast queries of symbols. This is where IDEs come, as the documentation lookup becomes part of the code writing experience.

They however present many disadvantages: they are usually bound to a language and a small set of libraries. Also, they hide many aspects of the development life cycle: managing dependencies, hiding linking and post build phases. I won’t argue on why these are drawbacks, but ail those reasons make me use a single editor for all languages I’m coding with, all tools I’m using in a development cycle: Emacs.

I’ve been using macs for many years now, but I happen to hack on other operating systems as well. There is one software that made me love coding on the mac: Dash. It is an API documentation browser that pops up with a key sequence and disappears when it looses focus. It hosts and downloads more than 130 famous docsets and provide very fast searching and a nice browsing experience. Also, its author, Bogdan Popescu is a very nice person, easy to talk with and is very open when it comes to contributing to Dash, see this post.

Helm is an emacs incremental completion and selection narrowing framework, a fork of the well known anything.el, that is currently very popular for many developers are using it as a frontend for their own packages.

Here comes Helm-Dash, a wonderful emacs packages, available on Melpa that uses Dash docsets inside emacs to browse documentation. Note that is does not require the Dash app, and so, works on any platform, just as Emacs !

The installation is quite straight forward, you’ll need to install sqlite, then either clone the repository to get helm-dash.el or use MELPA with M-x package-install helm-dash. M-x helm-dash-install-docset will display a list of available docsets, once downloaded, activate it using M-x helm-dash-activate-docset, then start a query using M-x helm-dash.

I’ll focus on my setup, which deviates from Helm-Dash’s intended use, as I want my docsets to be retrieved whenever I clone my Prelude. Note that the author were very reactive when I filled these issues.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
;;; prelude-dash.el ---
;;
;; Author: Julien Wintz
;; Created: Mon Feb  3 10:11:18 2014 (+0100)
;; Version:
;; Last-Updated:
;;           By:
;;     Update #: 252
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;
;;; Change Log:
;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

;; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; Download additional MELPA packages
;; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

(prelude-require-packages '(esqlite pcsv helm helm-dash))

;; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

(require 'helm-dash)

;; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; Helper functions
;; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

(defun jwintz/dash-path (docset)
  (if (string= docset "OpenGL_2")
      (concat (concat helm-dash-docsets-path "/") "OpenGL2.docset")
    (if (string= docset "OpenGL_3")
        (concat (concat helm-dash-docsets-path "/") "OpenGL3.docset")
      (if (string= docset "OpenGL_4")
          (concat (concat helm-dash-docsets-path "/") "OpenGL4.docset")
        (if (string= docset "Emacs_Lisp")
            (concat (concat helm-dash-docsets-path "/") "Emacs Lisp.docset")
          (concat
            (concat
             (concat
              (concat helm-dash-docsets-path "/")
              (nth 0 (split-string docset "_")))) ".docset"))))))

(defun jwintz/dash-install (docset)
  (unless (file-exists-p (jwintz/dash-path docset))
    (helm-dash-install-docset docset)))

(defun jwintz/dash-hook ()
  (local-set-key "\C-h\C-df" 'helm-dash)
  (local-set-key "\C-h\C-dg" 'helm-dash-at-point)
  (local-set-key "\C-h\C-dh" 'helm-dash-reset-connections))

(defun jwintz/dash-hook-java ()
  (interactive)
  (setq-local helm-dash-docsets '("Java_SE8")))

;; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; Setup
;; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

(setq helm-dash-docsets-path (format "%s/.emacs.d/docsets" (getenv "HOME")))

(jwintz/dash-install "Android")
(jwintz/dash-install "Bash")
(jwintz/dash-install "C")
(jwintz/dash-install "C++")
(jwintz/dash-install "Emacs_Lisp")
(jwintz/dash-install "Java_SE8")
(jwintz/dash-install "JavaScript")
(jwintz/dash-install "Markdown")
(jwintz/dash-install "OpenGL_2")
(jwintz/dash-install "OpenGL_3")
(jwintz/dash-install "OpenGL_4")
(jwintz/dash-install "Qt_5")
(jwintz/dash-install "Ruby_2")

(setq helm-dash-common-docsets '("C" "C++" "Qt"))
(setq helm-dash-min-length 2)

(add-hook 'prog-mode-hook 'jwintz/dash-hook)
(add-hook 'java-mode-hook 'jwintz/dash-hook-java)

This setup defines some helper functions:

  • jwintz/dash-path (docset) provides the installation path for a docset
  • jwintz/dash-install (docset) installs a docset only if it is not already installed, i.e. if the path returned by the previous function does not exists
  • jwintz/dash-hook* sets some shortcuts to use dash

By default, Helm-Dash uses emacs’ browse-url builtin to display the queried token documentation in your default browser. For me, it then launches Safari every-time I look up one definition. However, I like to stay within Emacs, so it minimizes my keystrokes and does not force me to use the mouse.

There are many web browsers for Emacs, I will cite two of them: eww is the newcomer that is EmacsLisp only,and is probably gonna be the way to go any time soon, I have however chosen emacs-w3m, even if it requires the installation of a third party binary, namely w3m (brew install does the job just fine).

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
;;; prelude-w3m.el ---
;;
;; Author: Julien Wintz
;; Created: Tue Feb 11 12:28:14 2014 (+0100)
;; Version:
;; Last-Updated:
;;           By:
;;     Update #: 18
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;
;;; Change Log:
;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

(prelude-require-packages '(w3m))

;; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

(require 'w3m)

(setq w3m-home-page "http://emacs-w3m.namazu.org/info/")

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

(setq browse-url-browser-function 'w3m-browse-url)

There you go !


Comments