spacemacs/layers/+readers/dash/README.org

#+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   |
Fix some documentation bugs - CSS links - GIFS in published version - Unify layer doc titles - Change emoji layer emojis to an image 2015-12-02 14:23:39 +00:00			`#+TITLE: Dash layer`
Documentation update - Add #+HTML_HEAD_EXTRA options to all org files - HTMLize published documentation via CSS 2015-11-08 18:04:44 +00:00
Add more tags 2019-05-02 21:49:30 +00:00			`#+TAGS: layer\|reader`

Org conversion of all READMEs ! 2015-06-10 16:44:30 +00:00			`[[file:img/dash.png]]`

Use `zeal-at-point` package instead of helm-dash. But also keep the helm-dash package just in case. 2015-06-12 20:59:07 +00:00			`[[file:img/zeal.png]]`

Switch to the new layers generator 2019-05-07 20:05:06 +00:00			`* Table of Contents :TOC_5_gh:noexport:`
update docs to the new toc-org format 2017-05-22 14:16:12 +00:00			`- [[#description][Description]]`
Fix doc for nim, fsharp, forth, dash and fasd layer 2018-01-07 22:26:54 +00:00			`- [[#features][Features:]]`
update docs to the new toc-org format 2017-05-22 14:16:12 +00:00			`- [[#install][Install]]`
Update references to macOS Apple renamed "Mac OS X" to "OS X" in 2012 and then to "macOS" in 2016. Update references to use the current name. 2019-10-13 05:27:17 +00:00			`- [[#dash-macos][Dash (macOS)]]`
Fix doc for nim, fsharp, forth, dash and fasd layer 2018-01-07 22:26:54 +00:00			`- [[#sqlite3][Sqlite3]]`
update docs to the new toc-org format 2017-05-22 14:16:12 +00:00			`- [[#zeal-linux--windows][Zeal (Linux & Windows)]]`
dash: provide config option to skip auto-load of all docsets In the upstream dash-docs and helm-dash documentation, they suggest a workflow where users leave relatively little in `dash-common-docsets`, and instead add per-mode hooks to enable specific docsets, since a user is unlikely to want Python documentation while in a C++ buffer and vice versa. Currently, the spacemacs dash layer will automatically discover all installed docsets and add them to `dash-common-docsets`. This commit adds a config option `dash-autoload-common-docsets` that can be set to nil to skip the auto-loading and allow users to opt-in. Co-Authored-By: duianto <otnaiud@gmail.com> 2019-06-30 20:44:39 +00:00			`- [[#configuration][Configuration]]`
Fix doc for nim, fsharp, forth, dash and fasd layer 2018-01-07 22:26:54 +00:00			`- [[#word-at-point][Word at point]]`
update docs to the new toc-org format 2017-05-22 14:16:12 +00:00			`- [[#key-bindings][Key bindings]]`
Org conversion of all READMEs ! 2015-06-10 16:44:30 +00:00
			`* Description`
Various documentation copy-edits Follow up the changes in the previous commit with some minor improvements to formatting, grammar, spelling, and wording. * layers/+distributions/spacemacs-docker/README.org: Replace "+" with "and". * layers/+email/mu4e/README.org: Use full sentences in the comments in the mu4e-alert example. * layers/+intl/japanese/README.org: Use verbatim markers for names of files, functions, packages, and variables. Capitalize "Linux". * layers/+os/osx/README.org: Capitalize "Emacs", "Vim", and "Evil". * layers/+os/osx/config.el (osx-command-as, osx-use-dictionary-app): * layers/+os/osx/keybindings.el (spacemacs/system-is-mac): Improve docstrings. * layers/+readers/dash/README.org: Capitalize "API", "Helm", and "Ivy". * layers/+spacemacs/spacemacs-defaults/config.el (delete-by-moving-to-trash): Use full sentences in comment. * layers/+spacemacs/spacemacs-defaults/funcs.el (spacemacs/toggle-frame-fullscreen-non-native): Improve docstrings. 2019-10-13 06:03:09 +00:00			`This layer integrates offline API browsers into Emacs. It provides one for macOS, Linux and Windows.`
Use `zeal-at-point` package instead of helm-dash. But also keep the helm-dash package just in case. 2015-06-12 20:59:07 +00:00
Fix doc for nim, fsharp, forth, dash and fasd layer 2018-01-07 22:26:54 +00:00			`** Features:`
Various documentation copy-edits Follow up the changes in the previous commit with some minor improvements to formatting, grammar, spelling, and wording. * layers/+distributions/spacemacs-docker/README.org: Replace "+" with "and". * layers/+email/mu4e/README.org: Use full sentences in the comments in the mu4e-alert example. * layers/+intl/japanese/README.org: Use verbatim markers for names of files, functions, packages, and variables. Capitalize "Linux". * layers/+os/osx/README.org: Capitalize "Emacs", "Vim", and "Evil". * layers/+os/osx/config.el (osx-command-as, osx-use-dictionary-app): * layers/+os/osx/keybindings.el (spacemacs/system-is-mac): Improve docstrings. * layers/+readers/dash/README.org: Capitalize "API", "Helm", and "Ivy". * layers/+spacemacs/spacemacs-defaults/config.el (delete-by-moving-to-trash): Use full sentences in comment. * layers/+spacemacs/spacemacs-defaults/funcs.el (spacemacs/toggle-frame-fullscreen-non-native): Improve docstrings. 2019-10-13 06:03:09 +00:00			`- 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.`
Org conversion of all READMEs ! 2015-06-10 16:44:30 +00:00
			`* Install`
Update install layer section in REAMDE.org files 2016-01-06 05:21:55 +00:00			`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`
Remove trailing whitespace from all files 2016-11-21 23:32:00 +00:00			`file.`
Org conversion of all READMEs ! 2015-06-10 16:44:30 +00:00
Update references to macOS Apple renamed "Mac OS X" to "OS X" in 2012 and then to "macOS" in 2016. Update references to use the current name. 2019-10-13 05:27:17 +00:00			`** Dash (macOS)`
Format and cleanup docs. Fix links. 2017-04-25 15:42:58 +00:00			`You have to install [[https://kapeli.com/dash][dash]] on your machine.`
Org conversion of all READMEs ! 2015-06-10 16:44:30 +00:00
			`It is recommended to set the =HUD mode= in your Dash application preferences`
Format documenation files with doc-fmt tool 2016-04-13 03:31:38 +00:00			`when using this layer.`
Org conversion of all READMEs ! 2015-06-10 16:44:30 +00:00
Fix doc for nim, fsharp, forth, dash and fasd layer 2018-01-07 22:26:54 +00:00			`*** Sqlite3`
Format and cleanup docs. Fix links. 2017-04-25 15:42:58 +00:00			`Helm Dash [[https://github.com/areina/helm-dash#user-content-requirements][requires]] sqlite3 to be installed to function properly.`
Added sqlite3 requirement 2016-10-20 16:36:39 +00:00
Use `zeal-at-point` package instead of helm-dash. But also keep the helm-dash package just in case. 2015-06-12 20:59:07 +00:00			`** Zeal (Linux & Windows)`
Format and cleanup docs. Fix links. 2017-04-25 15:42:58 +00:00			`You have to install [[https://zealdocs.org/][zeal]] on your machine.`
Use `zeal-at-point` package instead of helm-dash. But also keep the helm-dash package just in case. 2015-06-12 20:59:07 +00:00
			`Then install the docsets you use more frequently`

dash: provide config option to skip auto-load of all docsets In the upstream dash-docs and helm-dash documentation, they suggest a workflow where users leave relatively little in `dash-common-docsets`, and instead add per-mode hooks to enable specific docsets, since a user is unlikely to want Python documentation while in a C++ buffer and vice versa. Currently, the spacemacs dash layer will automatically discover all installed docsets and add them to `dash-common-docsets`. This commit adds a config option `dash-autoload-common-docsets` that can be set to nil to skip the auto-loading and allow users to opt-in. Co-Authored-By: duianto <otnaiud@gmail.com> 2019-06-30 20:44:39 +00:00			`* 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:`
documentation formatting: Wed Jul 3 08:44:16 UTC 2019 2019-07-03 08:44:16 +00:00
dash: provide config option to skip auto-load of all docsets In the upstream dash-docs and helm-dash documentation, they suggest a workflow where users leave relatively little in `dash-common-docsets`, and instead add per-mode hooks to enable specific docsets, since a user is unlikely to want Python documentation while in a C++ buffer and vice versa. Currently, the spacemacs dash layer will automatically discover all installed docsets and add them to `dash-common-docsets`. This commit adds a config option `dash-autoload-common-docsets` that can be set to nil to skip the auto-loading and allow users to opt-in. Co-Authored-By: duianto <otnaiud@gmail.com> 2019-06-30 20:44:39 +00:00			`#+BEGIN_SRC emacs-lisp`
documentation formatting: Wed Jul 3 08:44:16 UTC 2019 2019-07-03 08:44:16 +00:00			`(dash :variables`
			`dash-autoload-common-docsets nil)`
dash: provide config option to skip auto-load of all docsets In the upstream dash-docs and helm-dash documentation, they suggest a workflow where users leave relatively little in `dash-common-docsets`, and instead add per-mode hooks to enable specific docsets, since a user is unlikely to want Python documentation while in a C++ buffer and vice versa. Currently, the spacemacs dash layer will automatically discover all installed docsets and add them to `dash-common-docsets`. This commit adds a config option `dash-autoload-common-docsets` that can be set to nil to skip the auto-loading and allow users to opt-in. Co-Authored-By: duianto <otnaiud@gmail.com> 2019-06-30 20:44:39 +00:00			`#+END_SRC`

			`To change the location of the installed docsets, set:`
documentation formatting: Wed Jul 3 08:44:16 UTC 2019 2019-07-03 08:44:16 +00:00
dash: provide config option to skip auto-load of all docsets In the upstream dash-docs and helm-dash documentation, they suggest a workflow where users leave relatively little in `dash-common-docsets`, and instead add per-mode hooks to enable specific docsets, since a user is unlikely to want Python documentation while in a C++ buffer and vice versa. Currently, the spacemacs dash layer will automatically discover all installed docsets and add them to `dash-common-docsets`. This commit adds a config option `dash-autoload-common-docsets` that can be set to nil to skip the auto-loading and allow users to opt-in. Co-Authored-By: duianto <otnaiud@gmail.com> 2019-06-30 20:44:39 +00:00			`#+BEGIN_SRC elisp`
documentation formatting: Wed Jul 3 08:44:16 UTC 2019 2019-07-03 08:44:16 +00:00			`(dash :variables`
			`helm-dash-docset-newpath "~/.docsets")`
dash: provide config option to skip auto-load of all docsets In the upstream dash-docs and helm-dash documentation, they suggest a workflow where users leave relatively little in `dash-common-docsets`, and instead add per-mode hooks to enable specific docsets, since a user is unlikely to want Python documentation while in a C++ buffer and vice versa. Currently, the spacemacs dash layer will automatically discover all installed docsets and add them to `dash-common-docsets`. This commit adds a config option `dash-autoload-common-docsets` that can be set to nil to skip the auto-loading and allow users to opt-in. Co-Authored-By: duianto <otnaiud@gmail.com> 2019-06-30 20:44:39 +00:00			`#+END_SRC`

Fix doc for nim, fsharp, forth, dash and fasd layer 2018-01-07 22:26:54 +00:00			`* Word at point`
Various documentation copy-edits Follow up the changes in the previous commit with some minor improvements to formatting, grammar, spelling, and wording. * layers/+distributions/spacemacs-docker/README.org: Replace "+" with "and". * layers/+email/mu4e/README.org: Use full sentences in the comments in the mu4e-alert example. * layers/+intl/japanese/README.org: Use verbatim markers for names of files, functions, packages, and variables. Capitalize "Linux". * layers/+os/osx/README.org: Capitalize "Emacs", "Vim", and "Evil". * layers/+os/osx/config.el (osx-command-as, osx-use-dictionary-app): * layers/+os/osx/keybindings.el (spacemacs/system-is-mac): Improve docstrings. * layers/+readers/dash/README.org: Capitalize "API", "Helm", and "Ivy". * layers/+spacemacs/spacemacs-defaults/config.el (delete-by-moving-to-trash): Use full sentences in comment. * layers/+spacemacs/spacemacs-defaults/funcs.el (spacemacs/toggle-frame-fullscreen-non-native): Improve docstrings. 2019-10-13 06:03:09 +00:00			`=dash-at-point= and =zeal-at-point= will search for the word at point in the respective offline API browser.`
documentation formatting: Sun May 26 20:58:52 UTC 2019 2019-05-26 20:58:52 +00:00			`The result will be displayed in the offline browser's UI.`
Fix doc for nim, fsharp, forth, dash and fasd layer 2018-01-07 22:26:54 +00:00
			`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=`
Update dash layer to reflect dash-docs merge 2019-05-16 15:53:58 +00:00			`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`
Fix doc for nim, fsharp, forth, dash and fasd layer 2018-01-07 22:26:54 +00:00
			`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]].`
Org conversion of all READMEs ! 2015-06-10 16:44:30 +00:00
			`* Key bindings`

[applications] refactor key bindings to layer categories refactor key bindings for applications to provide additional room for applications and use lower case characters. Move calc-dispatch to `SPC a *` Relates to #13503 2020-06-28 21:25:04 +00:00			`\| 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 \|`