path: root/readme.org

#+TITLE: Evil Collection

[[https://travis-ci.org/jojojames/evil-collection][file:https://travis-ci.org/jojojames/evil-collection.svg?branch=master]]

This is a collection of [[https://github.com/emacs-evil/evil][Evil]] bindings for /the parts of Emacs/ that Evil does
not cover properly by default, such as ~help-mode~, ~M-x calendar~, Eshell and
more.

*Warning:* This project is still in an early development phase, expect
some default bindings to change in the future.



** Goals

1. Reduce context switching: As soon as "moving around" gets hardwired
   to ~<hjkl>~, it becomes frustratingly inefficient not to have it everywhere.

2. Community work: setting up bindings is tremendous work and joining force can
   only save hours for all of Evil users out there.  While not everyone may agree
   on the chosen bindings, it helps to have something to start with rather than
   nothing at all.  In the end, users are free to override a subset of the proposed
   bindings to best fit their needs.

3. Consistency: Having all bindings defined in one place allows for enforcing
   consistency across special modes and coordinating the community work to define a
   reference implementation.



** Installation

- Clone or download this repository.

- Modify your ~load-path~:

: (add-to-list 'load-path (expand-file-name "/path/to/evil-collection/" user-emacs-directory))

- Register the bindings, either all at once:

: (when (require 'evil-collection nil t)
:   (evil-collection-init))

or mode-by-mode, for instance:

: (with-eval-after-load 'calendar (require 'evil-collection-calendar) (evil-collection-calendar-setup))

The list of supported modes is simply the list of files.

If you want to enable Evil in the minibuffer, you'll have to turn it on
explicitly by customizing ~evil-collection-setup-minibuffer~ to ~t~. This is so
because many users find it confusing.

~use-package~ example:

: (use-package evil-collection
:   :custom (evil-collection-setup-minibuffer t)
:   :init (evil-collection-init))


** Guidelines

The following rules serve as guiding principles to define the set of standard
Evil bindings for various modes.  Since special modes are by definition
structurally incomparable, those rules cannot be expected to be applied
universally.

The rules are more-or-less sorted by priority.

0. [@0] Don't bind anything to ~:~ nor ~<escape>~.

1. Keep the movement keys when possible and sensible.

	- ~h~, ~j~, ~k~, ~l~
	- ~w~, ~W~, ~b~, ~B~, ~e~, ~E~, ~ge~, ~gE~
	- ~f~, ~F~, ~t~, ~T~, ~;~, =,=
	- ~gg~, ~G~
	- ~|~
	- ~(~, ~)~
	- ~{~, ~}~
	- ~%~
	- ~+~, ~-~, ~0~, ~^~, ~$~
	- ~C-i~, ~C-o~

2. Keep the yanking and register keys when possible and sensible.

	- ~y~, ~Y~
	- ="=

3. Keep the search keys when possible and sensible.

	- ~/~, ~?~
	- ~#~, ~*~

4. Keep the mark keys when possible and sensible.

	- ~m~
	- ='=, =~=

5. Keep the windowing keys when possible and sensible.

	- ~H~, ~L~, ~M~
	- ~C-e~, ~C-y~
	- ~C-f~, ~C-b~
	- ~C-d~, ~C-u~
	- ~C-w~-prefixed bindings.
	- Some ~z~-prefixed bindings (see below).

6. The following keys are free when insert state does not make sense in the
   current mode:

	- ~a~, ~A~, ~i~, ~I~
	- ~c~, ~C~, ~r~, ~R~, ~s~, ~S~
	- ~d~, ~D~, ~x~, ~X~
	- ~o~, ~O~
	- ~p~, ~P~
	- ~=~, ~<~, ~>~
	- ~J~
	- =~=

	Any of those keys can be set to be a prefix key.

7. Prefix keys: ~g~ and ~z~ are the ubiquitous prefix keys.

	- ~g~ generally stands for "go" and is best used for movements.
	- ~z~ is used for scrolling, folding, spell-checking and more.

8. Macro and action keys

	- ~@~, ~q~
	- ~.~



** Rationale (Work in progress)

Many special modes share the same set of similar actions.  Those actions should
share the same bindings across all modes whenever feasible.

*** Motion (~[~, ~]~, ~{~, ~}~, ~(~, ~)~, ~gj~, ~gk~, ~C-j~, ~C-k~)

- ~[~ and ~]~: Use ~[-~ and ~]-~ prefixed keys for navigation between sections.

  If the mode makes no difference between the end of a section and the beginning
  of the next, use ~[~ and ~]~.

- ~gj~ and ~gk~: synonym for ~[~ and ~]~.  That's what [[evil-magit][evil-magit]] does.

*Question:* Should ~gj~ / ~gk~ rather be synonyms for ~C-j~ / ~C-k~?  They cannot
emulate the behaviour of ~[]~ or ~][~.

- ~C-j~, ~C-k~: If there is granularity, i.e. subsections, use ~C-j~ and ~C-k~
  to browse them.  This reflects [[evil-magit][evil-magit]] and [[evil-mu4e][evil-mu4e]] default
  bindings.

- ~{~, ~}~: If there is no paragraph structure, ~{~ and ~}~ can be used for sub-sectioning.

- ~(~, ~)~: If there is no sentence structure, ~(~ and ~)~ can be used for sub-sectioning.

- ~HJKL~: ~hjkl~ can be used for atomic movements, but ~HJKL~ can usually not be used
  because ~H~, ~K~ and ~L~ are all universal (~J~ is ~evil-join~ and usually
  does not make sense in special modes).

- ~C-h~ should not be remapped: Since we have ~C-j~ and ~C-k~ for vertical motion, it would
  make sense to use ~C-h~ and ~C-l~ for horizontal motion.  There are some
  shortcomings though:

  - In Vim, ~C-h~ works as backspace, but Evil does not follow that behaviour.

  - In Emacs, it is a prefix key for all help-related commands, and so is ~<f1>~.

  - Most importantly, ~C-h~ is too widespread and ubiquitous to be replaced.
      So we don't.

- ~C-l~: As a consequence of the former point, ~C-l~ is available.

- ~M-<hjkl>~: Those keys are usually free in Evil but still bound to their Emacs
  default (e.g. ~M-l~ is ~downcase-word~).  Besides, if ~C-j~ and ~C-k~ are
  already used, having ~M-j~ and ~M-k~ might add up to the confusion.

*** Quitting (~q~, ~ZQ~, ~ZZ~)

In Vim, ~q~ is for recording macros.  Vim quits with ~ZZ~ or ~ZQ~.  In most
Emacs special modes, it stands for quitting while macros are recorded/played
with ~<f3>~ and ~<f4>~.

A good rule of thumb would be:

- Always bind ~ZZ~ and ~ZQ~ to the quitting function(s), ~evil-quit~ if nothing
  else makes sense.

- Bind ~q~ to ~evil-quit~ if macros don't make sense in current mode.

- If macros don't make sense in current mode, then ~@~ is available.

*** Refreshing / Reverting (~gr~)

- ~gr~ is used for refreshing in [[evil-magit][evil-magit]], [[evil-mu4e][evil-mu4e]], and some Spacemacs
  configurations (org-agenda and neotree among others).

~C-l~ is traditionally used to refresh the terminal screen.  Since there does
not seem to be any existing use of it, we leave the binding free for other uses.

*** Marking

Emacs inconsistently uses ~u~ and ~U~ to unmark.  Since in Vim those keys are
usually bound to "undo", they are probably best left to commands that undo
actions in the buffer and not undo marks.

~m~ defaults to ~evil-set-marker~ which might not be very useful in special
modes.  This is somewhat debatable though.

Suggested mark bindings:

- ~m~: Mark or toggle mark, depending on what the mode offers.

- =~=: Toggle all marks.  This mirrors the "invert-char" Vim command bound to =~=
by default.

- ~M~: Remove all marks.

- ~%~: Mark regexp.

- ~x~: Execute action on marks.  This mirrors Dired's binding of ~x~.

While ~m~ won't be available for setting marks (in the Vim sense), ~'~ can still
be used as it can jump to other buffers.

Optionally:

- ~*~: Mark all, because ~*~ is traditionally a wild card.

- ~#~: Remove mark.  This is useful when we want to unmark a region having both
marked and unmarked entries.  But ~M~ could also be made to remove all marks on
region, making this binding useless.

*** Selecting / Filtering / Narrowing / Searching

- ~s~ and ~S~ seem to be used in some places like [[mu4e][mu4e]].

  - ~s~: [s]elect/[s]earch/filter candidates according to a pattern.

  - ~S~: Remove filter and select all.

- ~=~ is usually free and its significance is obvious.  It's taken for zooming though.

- ~|~ is not free but the pipe symbolic is very tantalizing.

*** Sorting

- ~o~: Change the sort [o]rder.
- ~O~: Sort in reverse order.

~package-menu~ uses ~S~.

~M-x proced~ and Dired use ~s~.

~profiler~ uses ~A~ and ~D~.

[[mu4e][mu4e]] uses ~O~.

[[http://www.nongnu.org/ranger/][ranger]] uses ~o~, inspired from [[http://mutt.org][Mutt]].

*** Go to definition (~gd~, ~gD~)

- ~gd~: [g]o to [d]efinition.  This is mostly for programming modes.
  If there's a corresponding 'pop' action, use ~C-t~.

*** Go to current entity

- ~.~: go to current entity (day for calendar, playing track for [[EMMS][EMMS]]).
  Bind only if more relevant than ~evil-repeat~.

*** Open thing at point (~RET~, ~S-RET~, ~M-RET~, ~go~, ~gO~)

- ~RET~, ~S-RET~, ~M-RET~: Open thing at point in current window, open in other
  window and display in other window respectively.  The latter is like the
  former with the focus remaining on the current window.

- ~go~, ~gO~: When available, same as ~S-RET~ and ~M-RET~ respectively.  This is
  useful in terminals where ~S-RET~ and ~M-RET~ might not work.

*** Emacs-style jumping (~J~)

- ~J~: [[mu4e][mu4e]] has ~j~ and [[evil-mu4e][evil-mu4e]] uses ~J~, so we use ~J~ too.

Some special modes like [[mu4e][mu4e]] and ibuffer offer to to "jump" to a different
buffer.  This sometimes depends on the thing at point.

This is not related to Evil jumps like ~C-i~ and ~C-o~, nor to "go to
definition".

*** Browse URL (~gx~)

~gx~: go to URL.  This is a default Vim binding.

*** Help (~?~)

- ~g?~ : is the standard key for help related commands.
- ~?~ in places where backward search is not very useful.

*** History browsing (~C-n~, ~C-p~)

~C-n~ and ~C-p~ are standard bindings to browse the history elements.

*** Bookmarking

?

*** Zooming (~+~, ~-~, ~=~, ~0~)

- ~+~ and ~-~ have obvious meanings.

- ~0~ has a somewhat intuitive meaning, plus it is next to ~+~ and ~-~ on QWERTY.

- ~=~ is useful as a synonym for ~+~ because it is the unshifted key of ~+~ on QWERTY.


** Modes left behind

Some modes might still remain unsupported by this package.  Should you be
missing your ~<hjkl>~, feel free to file an issue or even a pull request.



** Third-party packages

Third-party packages are provided by several parties:

- [[evil-ediff][evil-ediff]]
- [[evil-magit][evil-magit]]
- [[evil-mu4e][evil-mu4e]]
- [[lispyville][lispyville]]
- Org-mode: https://github.com/GuiltyDolphin/org-evil or https://github.com/Somelauw/evil-org-mode

Should you know any suitable package not mentioned in this list, let us know and
file an issue.

Other references:

- [[https://github.com/syl20bnr/spacemacs/blob/master/doc/CONVENTIONS.org#key-bindings-conventions][Spacemacs]]
- [[https://github.com/hlissner/doom-emacs/blob/master/modules/private/hlissner/%2Bbindings.el][Doom Emacs]]

#+LINK: EMMS https://www.gnu.org/software/emms/
#+LINK: evil-ediff https://github.com/emacs-evil/evil-ediff
#+LINK: evil-magit https://github.com/emacs-evil/evil-magit
#+LINK: evil-mu4e https://github.com/JorisE/evil-mu4e
#+LINK: mu4e https://www.djcbsoftware.nl/code/mu/mu4e.html
#+LINK: lispyville https://github.com/noctuid/lispyville