#+TITLE: helpful layer

#+TAGS: emacs|layer

* Table of Contents                     :TOC_5_gh:noexport:
- [[#description][Description]]
  - [[#features][Features:]]
- [[#install][Install]]
- [[#key-bindings][Key bindings]]
  - [[#global-bindings][Global bindings]]
  - [[#helpful-mode-bindings][Helpful mode bindings]]

* Description
This layer replaces the existing emacs related help buffers with more detailed ones.

** Features:
- Better help buffers with [[https://github.com/Wilfred/helpful][helpful]] for emacs related buffers
- Source code shown implicitly in help buffer for all lisp objects
- More detailed descriptions in the emacs specific function, variable and key help buffers
- Better formatted elisp docstrings

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

* Key bindings
** Global bindings
This layer aims to silently replace the standard emacs help key bindings
with improved versions. So it does not introduce new bindings.
For the sake of completion you can find below all keys which are replaced
by this layer.

| Key binding | Description                                            |
|-------------+--------------------------------------------------------|
| =SPC m h h= | Open helpful buffer for item under point in elisp mode |
| =SPC h d k= | Open helpful buffer for key binding                    |
| =SPC h d f= | Open helpful buffer for any callable object            |
| =SPC h h v= | Open helpful buffer for variable                       |

** Helpful mode bindings
Additional key bindings available in the helpful-mode buffers.

| Key binding | Description                                        |
|-------------+----------------------------------------------------|
| =SPC m q=   | Close all helpful-mode buffers                     |
| =gr=        | Reload the buffer (e.g. to see new variable value) |
| =o=         | Open link with Avy                                 |
| =q=         | Close window (buffer is kept in background)        |