[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[elpa] externals/which-key cd0c48c 29/32: Clarify usage of keymap replac
From: |
ELPA Syncer |
Subject: |
[elpa] externals/which-key cd0c48c 29/32: Clarify usage of keymap replacements in docstrings and README |
Date: |
Wed, 30 Jun 2021 18:57:31 -0400 (EDT) |
branch: externals/which-key
commit cd0c48cda2e7cc1d3bc93d3611e267a7d022de8a
Author: Justin Burkett <justin@burkett.cc>
Commit: Justin Burkett <justin@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))
- [elpa] externals/which-key d8445fd 24/32: Try again to fix tests, (continued)
- [elpa] externals/which-key d8445fd 24/32: Try again to fix tests, ELPA Syncer, 2021/06/30
- [elpa] externals/which-key fffd3e5 07/32: Fix default of which-key-replacement-alist, ELPA Syncer, 2021/06/30
- [elpa] externals/which-key 8d6d81d 09/32: Expand get-keymap-bindings test, ELPA Syncer, 2021/06/30
- [elpa] externals/which-key 6290c9e 26/32: Improve which-key-add-keymap-based-bindings, ELPA Syncer, 2021/06/30
- [elpa] externals/which-key 063b867 18/32: Fix github action, ELPA Syncer, 2021/06/30
- [elpa] externals/which-key 28f386c 25/32: Fix key sort order functions, ELPA Syncer, 2021/06/30
- [elpa] externals/which-key 11471fb 21/32: Add install python step to github action, ELPA Syncer, 2021/06/30
- [elpa] externals/which-key e236920 14/32: Merge branch 'alt-get-bindings', ELPA Syncer, 2021/06/30
- [elpa] externals/which-key 7cfbf8c 23/32: Turn off fail-fast in github action, ELPA Syncer, 2021/06/30
- [elpa] externals/which-key eb5a2e3 28/32: Clean up some docstrings, ELPA Syncer, 2021/06/30
- [elpa] externals/which-key cd0c48c 29/32: Clarify usage of keymap replacements in docstrings and README,
ELPA Syncer <=
- [elpa] externals/which-key 27d9fec 32/32: Fix compiler warnings, ELPA Syncer, 2021/06/30
- [elpa] externals/which-key 4c27fc0 30/32: Improve which-key-add-keymap-based-replacements., ELPA Syncer, 2021/06/30
- [elpa] externals/which-key 8a558e6 06/32: Update tests, ELPA Syncer, 2021/06/30
- [elpa] externals/which-key e42d946 11/32: Fix prefix sorting, ELPA Syncer, 2021/06/30
- [elpa] externals/which-key fc88551 05/32: Remove pseudo binding stuff, ELPA Syncer, 2021/06/30
- [elpa] externals/which-key 465d2fb 10/32: Fix add-keymap-based-bindings and associated test, ELPA Syncer, 2021/06/30
- [elpa] externals/which-key 6ae80f5 22/32: Try without cask, ELPA Syncer, 2021/06/30
- [elpa] externals/which-key d621634 19/32: Try with cask again, ELPA Syncer, 2021/06/30
- [elpa] externals/which-key a55b908 04/32: Alternative approach to retrieving bindings (WIP), ELPA Syncer, 2021/06/30
- [elpa] externals/which-key 1f9c37d 03/32: Merge pull request #305 from tarsiiformes/first-line, ELPA Syncer, 2021/06/30