Improve 'defvar-keymap' docstring

* etc/NEWS: Improve ':repeat' entry for 'defvar-keymap'.
* lisp/keymap.el (defvar-keymap): Improve description of ':repeat'
keyword.

diff --git a/etc/NEWS b/etc/NEWS
index 4c7af3c2769fe0c8fa1a603477469185bef59487..2717f00612a8ada5c4507fff72dffb9ce8b65011 100644 (file)
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -4082,9 +4082,11 @@ This function allows defining a number of keystrokes with one form.
 ** New macro 'defvar-keymap'.
 This macro allows defining keymap variables more conveniently.
 
-** 'repeat-map' can be defined in the macro 'defvar-keymap'.
-This is possible either by using ':repeat t' or more advanced
-':repeat (:enter (commands ...) :exit (commands ...))'.
+** 'defvar-keymap' can specify 'repeat-mode' behavior for the keymap.
+Use ':repeat t' to have all bindings be repeatable or for more
+advanced usage:
+
+    ':repeat (:enter (commands ...) :exit (commands ...))'
 
 ---
 ** 'kbd' can now be used in built-in, preloaded libraries.

diff --git a/lisp/keymap.el b/lisp/keymap.el
index 0285c0571f7033e063c3b2fe1e3227d22a30fcbf..eaeba966444d7ab1206ff09c2a5bb6fd4f6d653e 100644 (file)
--- a/lisp/keymap.el
+++ b/lisp/keymap.el
@@ -559,18 +559,26 @@ In addition to the keywords accepted by `define-keymap', this
 macro also accepts a `:doc' keyword, which (if present) is used
 as the variable documentation string.
 
-When a `:repeat' keyword is non-nil, put `repeat-map' symbol
-properties on commands in this map for `repeat-mode'.  The value
-could also be a property list with properties `:enter' and `:exit',
-for example, :repeat (:enter (commands ...) :exit (commands ...)).
-`:enter' is a list of additional commands that only enter `repeat-mode'.
-When the list is empty then by default all commands in the map enter
-`repeat-mode'.  This is applicable when a command has the `repeat-map'
-symbol property on its symbol, but doesn't exist in the map.  `:exit'
-is a list of commands that exit `repeat-mode'.  When the list is
-empty, no commands in the map exit `repeat-mode'.  This is applicable
-when a command exists in the map, but doesn't have the `repeat-map'
-symbol property on its symbol.
+The `:repeat' keyword can also be specified; it controls the
+`repeat-mode' behavior of the bindings in the keymap.  When it is
+non-nil, all commands in the map will have the `repeat-map'
+symbol property.
+
+More control is available over which commands are repeatable; the
+value can also be a property list with properties `:enter' and
+`:exit', for example:
+
+     :repeat (:enter (commands ...) :exit (commands ...))
+
+`:enter' specifies the list of additional commands that only
+enter `repeat-mode'.  When the list is empty, then by default all
+commands in the map enter `repeat-mode'.  This is useful when
+there is a command that has the `repeat-map' symbol property, but
+doesn't exist in this specific map.  `:exit' is a list of
+commands that exit `repeat-mode'.  When the list is empty, no
+commands in the map exit `repeat-mode'.  This is useful when a
+command exists in this specific map, but it doesn't have the
+`repeat-map' symbol property on its symbol.
 
 \(fn VARIABLE-NAME &key DOC FULL PARENT SUPPRESS NAME PREFIX KEYMAP REPEAT &rest [KEY DEFINITION]...)"
   (declare (indent 1))