branch: externals/which-key
commit cd0c48cda2e7cc1d3bc93d3611e267a7d022de8a
Author: Justin Burkett <jus...@burkett.cc>
Commit: Justin Burkett <jus...@burkett.cc>
Clarify usage of keymap replacements in docstrings and README
---
README.org | 43 ++++++++++++++++++++++---------------------
which-key.el | 28 ++++++++++------------------
2 files changed, 32 insertions(+), 39 deletions(-)
diff --git a/README.org b/README.org
index 2280f70..37c742e 100644
--- a/README.org
+++ b/README.org
@@ -271,37 +271,38 @@
**** 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
+ replacement. The preferred way is to use =define-key= (or a command that
+ uses =define-key= internally) with a cons cell as the definition. For
+ example,
+
+ #+BEGIN_SRC emacs-lisp
+ (define-key some-map "f" '("foo" . command-foo))
+ (define-key some-map "b" '("bar-prefix" . (keymap)))
+ #+END_SRC
+
+ binds =command-foo= to =f= in =some-map=, but also stores the string "foo"
+ which which-key will extract to use to describe this command. The second
+ example binds an empty keymap to =b= in =some-map= and uses "bar-prefix"
to
+ describe it. These bindings are accepted by =define-key= natively (i.e.,
+ with or without which-key being loaded). Since many key-binding utilities
+ use =define-key= internally, this functionality should be available with
+ your favorite method of defining keys as well.
+
+ The second method is to use =which-key-add-keymap-based-replacements=. The
+ statement
#+BEGIN_SRC emacs-lisp
(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" . (keymap))
- ;; or
- ;; "b" "bar-prefix" (see the docstring)
- )
+ "b" '("bar-prefix" . (keymap)))
#+END_SRC
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 an empty
- prefix map. =which-key-add-keymap-based-replacements= uses =define-key= to
- bind (or rebind) the command, and you may also use =define-key= directly
as
- follows.
-
- #+BEGIN_SRC emacs-lisp
- (define-key some-map "f" '("foo" . command-foo))
- (define-key some-map "b" '("bar-prefix" . (keymap)))
- #+END_SRC
-
- Here =define-key= uses the natively supported =(NAME . COMMAND)= notation
- to simultaneously define a command and give that command a name. Since
many
- key-binding utilities use =define-key= internally, this functionality
- should be available with your favorite method of defining keys as well.
+ prefix map. =which-key-add-keymap-based-replacements= just uses
+ =define-key= to bind (or rebind) the command.
There are other methods of telling which-key to replace command names,
which are described next. The keymap-based replacements should be the most
diff --git a/which-key.el b/which-key.el
index 3a0ce97..8598fa6 100644
--- a/which-key.el
+++ b/which-key.el
@@ -895,27 +895,19 @@ but more functional."
;;;###autoload
(defun which-key-add-keymap-based-replacements (keymap key replacement &rest
more)
"Replace the description of KEY using REPLACEMENT in KEYMAP.
-KEY should take a format suitable for use in
-`kbd'. REPLACEMENT is the string to use to describe the
-command associated with KEY in the KEYMAP. You may also use a
-cons cell of the form \(STRING . COMMAND\) for each REPLACEMENT,
-where STRING is the replacement string and COMMAND is a symbol
-corresponding to the intended command to be replaced. In the
-latter case, which-key will verify the intended command before
-performing the replacement. COMMAND should be nil if the binding
-corresponds to a key prefix. For example,
+KEY should take a format suitable for use in `kbd'. REPLACEMENT
+should be a cons cell of the form \(STRING . COMMAND\) for each
+REPLACEMENT, where STRING is the replacement string and COMMAND
+is a symbol corresponding to the intended command to be
+replaced. COMMAND can be nil if the binding corresponds to a key
+prefix. An example is
\(which-key-add-keymap-based-replacements global-map
- \"C-x w\" \"Save as\"\)
+ \"C-x w\" '\(\"Save as\" . write-file\)\).
-and
-
-\(which-key-add-keymap-based-replacements global-map
- \"C-x w\" '\(\"Save as\" . write-file\)\)
-
-both have the same effect for the \"C-x C-w\" key binding, but
-the latter causes which-key to verify that the key sequence is
-actually bound to write-file before performing the replacement."
+For backwards compatibility, REPLACEMENT can also be a string,
+but the above format is preferred, and the option to use a string
+for REPLACEMENT will eventually be removed."
(while key
(cond ((consp replacement)
(define-key keymap (kbd key) replacement))
