Clarify usage of keymap replacements in docstrings and README

2 files changed, 32 insertions, 39 deletions

diff --git a/README.org b/README.org
index 2280f704acf..37c742edcce 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 3a0ce9753fe..8598fa666e1 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))