readme.org: Init

1 files changed, 309 insertions, 0 deletions

diff --git a/readme.org b/readme.org
new file mode 100644
index 0000000..a502aaa
--- /dev/null
+++ b/readme.org
@@ -0,0 +1,309 @@
+#+TITLE: Evil Collection
+
+This is a collection of [[https://github.com/emacs-evil/evil][Evil]] bindings for
+/the rest of Emacs/ that Evil does not cover by default, such as ~help-mode~,
+~M-x calendar~, Eshell and more.
+
+*Warning:* This project is still in an early development phase, expect
+the 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-special-modes/" user-emacs-directory))
+
+- Register the bindings, either all at once:
+
+: (when (require 'evil-special-modes nil t)
+:   (evil-special-modes-init))
+
+or mode-by-mode, for instance:
+
+: (with-eval-after-load 'calendar (require 'evil-calendar) (evil-calendar-set-keys))
+
+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.  This is so because many users find it confusing.
+
+: (require 'evil-minibuffer)
+: (evil-minibuffer-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-mode 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 (~[~, ~]~, ~{~, ~}~, ~(~, ~)~, ~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 ~]~.
+
+- ~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.
+
+- 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 reverting 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.
+
+*** 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 mark.  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.
+
+*** 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 also free and its significance is obvious.
+
+- ~|~ 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~.
+
+*** Jumping / Interactive "goto" (~gd~ and ~.~)
+
+- ~gd~: [g]o to [d]efinition.
+
+- ~.~: go to current entity (day for calendar, playing track for [[EMMS][EMMS]]).
+Bind only if more relevant than ~evil-repeat~.
+
+mu4e has ~j~ in Emacs, ~J~ in Evil.
+
+*** Browse URL (~gx~)
+
+~gx~: go to URL.  This is a default Vim binding.
+
+*** Help (~?~)
+
+If searching makes sense, keep ~?~ for backward search.
+If not, it can be used to display help.
+
+*** History browsing (~C-n~, ~C-p~)
+
+~C-n~ and ~C-p~ are standard bindings to browse the history elements.
+
+*** Bookmarking
+
+?
+
+
+
+** 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]]
+- 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:
+
+- [[http://spacemacs.org][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