readme.org -> README.org
This commit is contained in:
parent
63c6fd00c2
commit
a075a4e439
|
@ -59,10 +59,10 @@ more.
|
|||
|
||||
The list of supported modes is configured by ~evil-collection-mode-list~.
|
||||
|
||||
~evil-collection~ assumes ~evil-want-keybinding~ is set to nil and
|
||||
~evil-want-integration~ is set to t before loading ~evil~ and
|
||||
~evil-collection.~ Note some other packages may load evil (e.g. evil-leader)
|
||||
so bear that in mind when determining when to set the variables.
|
||||
~evil-collection~ assumes ~evil-want-keybinding~ is set to ~nil~ and
|
||||
~evil-want-integration~ is set to ~t~ before loading ~evil~ and
|
||||
~evil-collection~. Note some other packages may load evil (e.g. evil-leader) so
|
||||
bear that in mind when determining when to set the variables.
|
||||
|
||||
See https://github.com/emacs-evil/evil-collection/issues/60 and https://github.com/emacs-evil/evil/pull/1087
|
||||
for more details.
|
||||
|
@ -197,7 +197,6 @@ The rules are more-or-less sorted by priority.
|
|||
- ~.~
|
||||
|
||||
10. Ensure terminal compatibility without sacrificing GUI key bindings.
|
||||
|
||||
- Tab key
|
||||
- Tab key is recognized as ~<tab>~ in GUI and ~TAB~ in terminal.
|
||||
~TAB~ equals ~C-i~.
|
||||
|
@ -269,11 +268,8 @@ with ~<f3>~ and ~<f4>~.
|
|||
A good rule of thumb would be:
|
||||
|
||||
- Always bind ~q~, ~ZZ~ and ~ZQ~ to the mode specific quitting functions. If there is none,
|
||||
|
||||
- Bind ~q~ and ~ZZ~ to ~quit-window~
|
||||
|
||||
- Bind ~ZQ~ to ~evil-quit~
|
||||
|
||||
- If macros don't make sense in current mode, then ~@~ is available.
|
||||
|
||||
*** Refreshing / Reverting (~gr~)
|
||||
|
@ -281,8 +277,9 @@ A good rule of thumb would be:
|
|||
- ~gr~ is used for refreshing in [[evilmagit][evil-magit]], [[evilmu4e][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.
|
||||
- ~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
|
||||
|
||||
|
@ -290,9 +287,9 @@ A good rule of thumb would be:
|
|||
modes.
|
||||
='= can still be used as it can jump to other buffers.
|
||||
|
||||
- ~m~: Mark or toggle mark, depending on what the mode offers.
|
||||
In visual mode, always mark.
|
||||
With a numeric argument, toggle mark on that many following lines.
|
||||
- ~m~: Mark or toggle mark, depending on what the mode offers. In visual mode,
|
||||
always mark. With a numeric argument, toggle mark on that many following
|
||||
lines.
|
||||
|
||||
- ~u~: Unmark current selection.
|
||||
|
||||
|
@ -318,7 +315,6 @@ modes.
|
|||
- ~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.
|
||||
|
@ -400,15 +396,17 @@ When ~evil-collection-want-find-usages-bindings~ is set to t:
|
|||
?
|
||||
|
||||
*** REPL (~gz~)
|
||||
|
||||
If the mode has a Go To REPL-type command, set it to ~gz~.
|
||||
|
||||
*** 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.
|
||||
|
||||
*** Debugging
|
||||
|
||||
When debugging is on, debugger keys takes the most precedence.
|
||||
|
||||
These keys will be set when there's an available command for them.
|
||||
|
@ -440,7 +438,9 @@ These keys will be set when there's an available command for them.
|
|||
- ~f10~ Step Over
|
||||
- ~f11~ Step Into
|
||||
- ~S-f11~ Step Out
|
||||
|
||||
*** Editable Buffers
|
||||
|
||||
For buffers where insert-state doesn't make sense but buffer can be edited,
|
||||
(e.g. wdired or wgrep), pressing ~i~ will change into editable state.
|
||||
|
||||
|
@ -449,9 +449,13 @@ When this editable state is turned on,
|
|||
~ZQ~ will abort and clear any changes.
|
||||
~ZZ~ will finish and save any changes.
|
||||
~ESC~ will exit editable state.
|
||||
|
||||
*** :q/:wq/etc
|
||||
|
||||
Modes with commands that can be bound to :q/:wq/etc will have those keys remapped.
|
||||
|
||||
** Key Translation
|
||||
|
||||
~evil-collection-translate-key~ allows binding a key to the definition of
|
||||
another key in the same keymap (comparable to how Vim's keybindings work). Its
|
||||
arguments are the ~states~ and ~keymaps~ to bind/look up the key(s) in followed
|
||||
|
@ -464,6 +468,7 @@ someone who uses an alternate keyboard layout may want to retain the ~hjkl~
|
|||
positions for directional movement in dired, the calendar, etc.
|
||||
|
||||
Here's an example for Colemak of making swaps in a single keymap:
|
||||
|
||||
#+begin_src emacs-lisp
|
||||
(evil-collection-translate-key nil 'evil-motion-state-map
|
||||
;; colemak hnei is qwerty hjkl
|
||||
|
@ -478,6 +483,7 @@ Here's an example for Colemak of making swaps in a single keymap:
|
|||
|
||||
Here's an example of using ~evil-collection-setup-hook~ to cycle the keys for
|
||||
all modes in ~evil-collection-mode-list~:
|
||||
|
||||
#+begin_src emacs-lisp
|
||||
(defun my-hjkl-rotation (_mode mode-keymaps &rest _rest)
|
||||
(evil-collection-translate-key 'normal mode-keymaps
|
||||
|
@ -501,6 +507,7 @@ keys that you never want to be overridden, you'll want to give them higher
|
|||
priority than other evil keybindings (e.g. those made by ~(evil-define-key
|
||||
'normal some-map ...)~). To do this, you can create an "intercept" map and bind
|
||||
your prefix keys in it instead of in ~evil-normal-state-map~:
|
||||
|
||||
#+begin_src emacs-lisp
|
||||
(defvar my-intercept-mode-map (make-sparse-keymap)
|
||||
"High precedence keymap.")
|
||||
|
@ -523,6 +530,7 @@ your prefix keys in it instead of in ~evil-normal-state-map~:
|
|||
#+end_src
|
||||
|
||||
You can then define replacement keys:
|
||||
|
||||
#+begin_src emacs-lisp
|
||||
(defun my-prefix-translations (_mode mode-keymaps &rest _rest)
|
||||
(evil-collection-translate-key 'normal mode-keymaps
|
||||
|
@ -558,6 +566,7 @@ another key that was defined after the first ~evil-collection-translate-key~, so
|
|||
|
||||
~evil-collection-swap-key~ is also provided as a wrapper around
|
||||
~evil-collection-translate-key~ that allows swapping keys:
|
||||
|
||||
#+begin_src emacs-lisp
|
||||
(evil-collection-swap-key nil 'evil-motion-state-map
|
||||
";" ":")
|
||||
|
@ -595,10 +604,14 @@ Third-party packages are provided by several parties:
|
|||
|
||||
| Major mode | Evil bindings |
|
||||
|------------+--------------------------|
|
||||
| ledger | [[https://github.com/atheriel/evil-ledger][evil-ledger]] |
|
||||
| lispy | [[https://github.com/noctuid/lispyville][lispyville]] or [[https://github.com/sp3ctum/evil-lispy][evil-lispy]] |
|
||||
| org | [[https://github.com/GuiltyDolphin/org-evil][org-evil]] or [[https://github.com/Somelauw/evil-org-mode][evil-org]] |
|
||||
| markdown | [[https://github.com/Somelauw/evil-markdown][evil-markdown]] |
|
||||
| ledger | [[https://github.com/atheriel/evil-ledger][evil-ledger]] |
|
||||
|
||||
Also ~evil-collection~ has minimal support (~TAB~, ~S-TAB~ and
|
||||
sentence/paragraph forwarding) for ~markdown~ and ~org~ if you prefer less
|
||||
packages installed.
|
||||
|
||||
Should you know any suitable package not mentioned in this list, let us know and
|
||||
file an issue.
|
||||
|
@ -609,10 +622,11 @@ Other references:
|
|||
- [[https://github.com/hlissner/doom-emacs/tree/develop/modules/editor/evil][Doom Emacs]]
|
||||
|
||||
** FAQ
|
||||
- Making SPC work similarly to [[https://github.com/syl20bnr/spacemacs][spacemacs]].
|
||||
|
||||
~evil-collection~ binds over SPC in many packages. To use SPC as a leader
|
||||
key with the [[https://github.com/noctuid/general.el][general]] library:
|
||||
*** Making SPC work similarly to [[https://github.com/syl20bnr/spacemacs][spacemacs]].
|
||||
|
||||
~evil-collection~ binds over SPC in many packages. To use SPC as a leader key
|
||||
with the [[https://github.com/noctuid/general.el][general]] library:
|
||||
|
||||
#+begin_src emacs-lisp :tangle yes
|
||||
(use-package general
|
||||
|
@ -639,8 +653,8 @@ Other references:
|
|||
- Unintialized mode maps in ~evil-collection-setup-hook~.
|
||||
~evil-collection-setup-hook~ is ran with a list of keymaps passed into it.
|
||||
Some misconfigured modes may not have yet initialized their keymap at this
|
||||
time so the value of the variable may be nil. In that case, an alternative
|
||||
is to use a mode-hook to do any custom settings.
|
||||
time so the value of the variable may be nil. In that case, an alternative is
|
||||
to use a mode-hook to do any custom settings.
|
||||
|
||||
#+begin_src emacs-lisp :tangle yes
|
||||
(add-hook 'evil-collection-setup-hook
|
||||
|
@ -649,12 +663,16 @@ Other references:
|
|||
(lambda ()
|
||||
(... keymaps ...)))))
|
||||
#+end_src
|
||||
|
||||
View [[https://github.com/emacs-evil/evil-collection/issues/196][196]] for more info.
|
||||
|
||||
** Modes left behind
|
||||
Some modes might still remain unsupported by this package. Should you be
|
||||
missing your ~<hjkl>~, please feel free to do a pull request.
|
||||
** Writing a new binding
|
||||
*** Modes left behind
|
||||
|
||||
Some modes might still remain unsupported by this package. Should you be missing
|
||||
your ~<hjkl>~, please feel free to do a pull request.
|
||||
|
||||
*** Writing a new binding
|
||||
|
||||
This [[template][yasnippet template]] can be used to bootstrap a new binding.
|
||||
|
||||
For example, if we were to want to add ~evil-collection~ support to ~eldoc~.
|
||||
|
@ -664,10 +682,10 @@ For example, if we were to want to add ~evil-collection~ support to ~eldoc~.
|
|||
(provide 'eldoc)
|
||||
#+end_src
|
||||
|
||||
Create a directory named eldoc under [[modes-directory][modes/]].
|
||||
Create a file named evil-collection-eldoc.el under the newly created eldoc directory.
|
||||
Then use the above template as an example or, using [[yasnippet][yasnippet]],
|
||||
~yas-expand~ the above template which will result in something like below:
|
||||
Create a directory named eldoc under [[modes-directory][modes/]]. Create a file named
|
||||
evil-collection-eldoc.el under the newly created eldoc directory. Then use the
|
||||
above template as an example or, using [[yasnippet][yasnippet]], ~yas-expand~ the above
|
||||
template which will result in something like below:
|
||||
|
||||
#+begin_src emacs-lisp :tangle yes
|
||||
;;; evil-collection-eldoc.el --- Bindings for `eldoc'. -*- lexical-binding: t -*-
|
||||
|
@ -726,12 +744,13 @@ Finally, add ~eldoc~ to ~evil-collection--supported-modes~.
|
|||
either target mode symbols or lists which `car' is the mode
|
||||
symbol and `cdr' the packages to register.")
|
||||
#+end_src
|
||||
|
||||
** Contributing
|
||||
|
||||
We welcome any additional modes that are not already supported.
|
||||
|
||||
All bindings in ~evil-collection~ are open to change so if there's
|
||||
a better or more consistent binding, please [[https://github.com/emacs-evil/evil-collection/issues][open an issue]] or
|
||||
[[https://github.com/emacs-evil/evil-collection/pulls][submit a pull request]].
|
||||
All bindings in ~evil-collection~ are open to change so if there's a better or
|
||||
more consistent binding, please [[https://github.com/emacs-evil/evil-collection/issues][open an issue]] or [[https://github.com/emacs-evil/evil-collection/pulls][submit a pull request]].
|
||||
|
||||
Follow [[https://github.com/bbatsov/emacs-lisp-style-guide/][The Emacs Lisp Style Guide]] for coding conventions.
|
||||
|
Loading…
Reference in New Issue