miércoles, 15 de enero de 2014

ANN: Helm-dash, the documentation browser for emacs

This post is the official announcement of a minor mode Toni and myself have developed which allows you to browse documentation for many languages using helm machinery to drive the find-as-you-type. It's called helm-dash

Intro


Helm is gaining lots of traction lately in the emacs environment (there are over 50 helm-* packages is the melpa now). It's a find-as-yo-type helper which provides an easy way to act on the selections. 

Dash is a mac osX app which lets you browse what they call docsets. Docsets contain an sqlite db and some html with the documentation of a given topic.

helm-dash


The basic usage is pretty simple:
  • helm-dash-install-package will give you the available docsets in the official repo (we'll choose Redis for testing).
  • Add the docset to either the global variable helm-dash-common-docsets. 
     (setq helm-dash-common-docsets '("Redis")) 
  • execute the interactive command helm-dash
  • Type some letters that match a redis command you want to look for (push, for example)
  • Press RET when you are on the command you want. Your favourite browser should open pointing to the documentation.

buffer-local docsets


For further configuration, we allow per-buffer sets of docsets. Let's say you want the GoLang docset available, but just in go-mode buffers. Install Go docset, and evaluate the following elisp:

(defun go-doc ()
  (interactive)
  (setq-local helm-dash-docsets '("Go")))

(add-hook 'go-mode-hook 'go-doc)

Then, when you open a go buffer, helm-dash will search both Redis and Go.

Here's a demo of the basic usage. (Mind that the video is not setting the variables accordingly because they were already set)

Try it, patch it, or talk about it, we'd love to hear your comments and improve it. 

The package has been developed and tested under linux.It should work on Mac OSX but it hasn't been tested there.If you find any issue on Mac, please, Pull Request :)

5 comentarios:

Amit dijo...

Cool! It uses browse-url to open in an external browser on my emacs; I'm going to try modifying this to use an internal browser.

BalticPasta dijo...

To open in another browser, you can use:


(eval-after-load "helm-dash"
'(defun helm-dash-actions (actions doc-item) `(("Go to doc" . eww)))
)

Raimon Grau dijo...

Thanks!!

Yeah!
That's the idea, I also use it with eww. but we didn't want to lock it because eww is not shipped with the official stable emacs (yet).

I have a pretty complex setup regarding opening urls.
Depending on the url, emacs opens one browser or another (eww/w3m for text friendly webs, and firefox/chrome/conkeror for js heavy ones).

Also, it choses among firefox/conkeror/chrome based on if any of them is already opened, it uses it, else it opens conkeror.

If you're interested in that setup I can explain it a bit more in a future post.

Dylan Conlin dijo...

If you don't mind, I'd like to see your setup for opening urls in firefox.

Raimon Grau dijo...

I just use browse-url-firefox. Browse the help on this function to see the thousand ways of configuring it :)