#+TITLE: Dash layer

#+TAGS: layer|reader

[[file:img/dash.png]]

[[file:img/zeal.png]]

* Table of Contents                     :TOC_5_gh:noexport:
- [[#description][Description]]
  - [[#features][Features:]]
- [[#install][Install]]
  - [[#dash-macos][Dash (macOS)]]
    - [[#sqlite3][Sqlite3]]
  - [[#zeal-linux--windows][Zeal (Linux & Windows)]]
- [[#configuration][Configuration]]
- [[#word-at-point][Word at point]]
- [[#key-bindings][Key bindings]]

* Description
This layer integrates offline API browsers into Emacs. It provides one for macOS, Linux and Windows.

** Features:
- Searching for word at point in offline API browser's UI.
- Integration of offline API browser search results in Helm and Ivy.
- Support for [[https://kapeli.com/dash][dash]] offline API browser for macOS.
- Support for [[https://zealdocs.org/][zeal]] offline API browser for Linux.

* Install
To use this configuration layer, add it to your =~/.spacemacs=. You will need to
add =dash= to the existing =dotspacemacs-configuration-layers= list in this
file.

** Dash (macOS)
You have to install [[https://kapeli.com/dash][dash]] on your machine.

It is recommended to set the =HUD mode= in your Dash application preferences
when using this layer.

*** Sqlite3
Helm Dash [[https://github.com/areina/helm-dash#user-content-requirements][requires]] sqlite3 to be installed to function properly.

** Zeal (Linux & Windows)
You have to install [[https://zealdocs.org/][zeal]] on your machine.

Then install the docsets you use more frequently

* Configuration
By default, the dash layer will initialize all installed docsets to be active in
all buffers. To disable this and opt-in to specific docsets for specific buffers, set:

#+BEGIN_SRC emacs-lisp
  (dash :variables
        dash-autoload-common-docsets nil)
#+END_SRC

To change the location of the installed docsets, set:

#+BEGIN_SRC elisp
  (dash :variables
        helm-dash-docset-newpath "~/.docsets")
#+END_SRC

* Word at point
=dash-at-point= and =zeal-at-point= will search for the word at point in the respective offline API browser.
The result will be displayed in the offline browser's UI.

However having to leave emacs to have a look at the search results may be a bit awkward.
To help with this it is also possible to integrate the search results directly in =helm= or =ivy=
and show the details in a browser. To do so [[https://github.com/dash-docs-el/helm-dash][helm-dash]] can be used for =helm= and [[https://github.com/dash-docs-el/counsel-dash][counsel-dash]] for =ivy=.

To get them working it is necessary to set =dash-docs-docset-newpath= to the location of your docsets.

#+BEGIN_SRC elisp
  (dash :variables
        dash-docs-docset-newpath "~/.local/share/Zeal/Zeal/docsets")
#+END_SRC

For more details please check [[https://github.com/stanaka/dash-at-point#Usage][dash-at-point-usage]] or [[https://github.com/jinzhu/zeal-at-point][zeal-at-point]].

* Key bindings

| Key binding   | Description                                                     |
|---------------+-----------------------------------------------------------------|
| ~SPC a r z d~ | Lookup thing at point in Dash or Zeal                           |
| ~SPC a r z D~ | Lookup thing at point in Dash or Zeal within a specified Docset |
| ~SPC a r z h~ | Lookup thing at point in helm-dash or counsel-dash              |
| ~SPC a r z H~ | Lookup in helm-dash or counsel-dash within a specified Docset   |
