[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[elpa] externals/which-key 427c3f4 4/9: Clarify README's description of
From: |
Stefan Monnier |
Subject: |
[elpa] externals/which-key 427c3f4 4/9: Clarify README's description of keymap-based replacement |
Date: |
Mon, 15 Mar 2021 22:29:20 -0400 (EDT) |
branch: externals/which-key
commit 427c3f4a53fe70799b08ff49c23ddd41ab2376c6
Author: Justin Burkett <justin@burkett.cc>
Commit: Justin Burkett <justin@burkett.cc>
Clarify README's description of keymap-based replacement
---
README.org | 66 ++++++++++++++++++++++++++++++++------------------------------
1 file changed, 34 insertions(+), 32 deletions(-)
diff --git a/README.org b/README.org
index 92745ff..d2d375d 100644
--- a/README.org
+++ b/README.org
@@ -257,47 +257,49 @@
*** Custom String Replacement Options
#+NAME: #custom-string-replacement-options
You can customize the way the keys show in the buffer using three different
- replacement methods, each of which corresponds replacement alist. The basic
- idea of behind each alist is that you specify a selection string in the
- =car= of each cons cell and the replacement string in the =cdr=.
+ replacement methods. The first, keymap-based replacement, is preferred and
+ will take precedence over the others. The remaining methods are still
+ available, because they pre-date the first and are more flexible in what
+ they can accomplish.
-**** Automatic ("keymap-based") replacement
- A newer option is to set =which-key-enable-extended-define-key= which
- advises =define-key= to allow which-key to pre-process its arguments. With
- this option enabled, the statement
+**** Keymap-based replacement
+ Using this method, which-key can display a custom string for a key
+ definition in some keymap. There are two ways to define a keymap-based
+ replacement. The first is to use
+ =which-key-add-keymap-based-replacements=. The statement
#+BEGIN_SRC emacs-lisp
- (define-key some-map "f" '("foo" . command-foo))
+ (define-key some-map "f" 'long-command-name-foo)
+ (define-key some-map "b" some-prefix-map)
+ (which-key-add-keymap-based-replacements some-map
+ "f" '("foo" . long-command-name-foo)
+ ;; or
+ ;; "f" "foo" (see the docstring)
+ "b" '("bar-prefix")
+ ;; or
+ ;; "b" "bar-prefix" (see the docstring)
+ )
#+END_SRC
- will both bind the command =command-foo= to "f" in =some-map= and tell
- which-key to use the string "foo" for this command. This also works with
- naming prefixes if you use =nil= for the command. The following binds "b"
- to =nil= and names the binding as a prefix.
+ uses =define-key= to add two bindings and tells which-key to use the
string
+ "foo" in place of "command-foo" and the string "bar-prefix" for
+ some-prefix-map. Note that =which-key-add-keymap-based-replacements= will
+ not bind a command, so =define-key= must still be used.
- #+BEGIN_SRC emacs-lisp
- (define-key some-map "b" '("bar-prefix"))
- #+END_SRC
-
- If you do not want to enable the advise on =define-key=, you may also use
- =which-key-add-keymap-based-replacements=. The first example can be
- alternatively written as
+ Alternatively, you may set =which-key-enable-extended-define-key= to =t=
+ before loading which-key and accomplish the same effect using only
+ =define-key= as follows.
#+BEGIN_SRC emacs-lisp
- (define-key some-map "f" 'command-foo)
- (define-key some-map "b" some-prefix-map)
- (which-key-add-keymap-based-replacements some-map
- "f" '("foo" . long-name-for-command-foo)
- ;; or
- ;; "f" "foo"
- "b" '("bar-prefix")
- ;; or
- ;; "b" "bar-prefix"
- )
+ (define-key some-map "f" '("foo" . command-foo))
+ (define-key some-map "b" '("bar-prefix"))
#+END_SRC
- Note that =which-key-add-keymap-based-replacements= will not bind a
- command, so =define-key= must still be used.
+ The option =which-key-enable-extended-define-key= advises =define-key= to
+ allow which-key to use the =(NAME . COMMAND)= notation to simultaneously
+ define a command and give that command a name using =define-key=. Since
+ many key-binding utilities use =define-key= internally, this functionality
+ should be available with your favorite method of defining keys as well.
There are other methods of telling which-key to replace command names,
which are described next. The keymap-based replacements should be the most
@@ -306,7 +308,7 @@
replace text. They can be used simultaneously, but which-key will give
precedence to the keymap-based replacement when it exists.
-**** "Key-Based" replacement
+**** Key-Based replacement
Using this method, the description of a key is replaced using a string
that
you provide. Here's an example
- [elpa] externals/which-key updated (d794c4a -> c0608e8), Stefan Monnier, 2021/03/15
- [elpa] externals/which-key ae59b7e 3/9: Version 3.5.0, Stefan Monnier, 2021/03/15
- [elpa] externals/which-key 427c3f4 4/9: Clarify README's description of keymap-based replacement,
Stefan Monnier <=
- [elpa] externals/which-key a70fc16 1/9: Hide paging hint when prefix is help-char, Stefan Monnier, 2021/03/15
- [elpa] externals/which-key ca268fd 6/9: REAMDE code's Number of parentheses pairs (#270), Stefan Monnier, 2021/03/15
- [elpa] externals/which-key c0608e8 9/9: Version 3.5.1, Stefan Monnier, 2021/03/15
- [elpa] externals/which-key 5b37abc 2/9: Fix which-key--next-page-hint, Stefan Monnier, 2021/03/15
- [elpa] externals/which-key c011b26 5/9: Add tests for keymap-based-bindings, Stefan Monnier, 2021/03/15
- [elpa] externals/which-key 3908719 7/9: simplify pseudo key, Stefan Monnier, 2021/03/15
- [elpa] externals/which-key 428aedf 8/9: Further simplify which-key--pseudo-key, Stefan Monnier, 2021/03/15