From 4506b005ab15e2d27996dac87e0f91dd0d4f91cb Mon Sep 17 00:00:00 2001
From: Robert Pluim <rpluim@gmail.com>
Date: Fri, 18 Nov 2022 16:05:05 +0100
Subject: [PATCH] Improve 'defvar-keymap' docstring

* etc/NEWS: Improve ':repeat' entry for 'defvar-keymap'.
* lisp/keymap.el (defvar-keymap): Improve description of ':repeat'
keyword.
---
 etc/NEWS       |  8 +++++---
 lisp/keymap.el | 32 ++++++++++++++++++++------------
 2 files changed, 25 insertions(+), 15 deletions(-)

diff --git a/etc/NEWS b/etc/NEWS
index 4c7af3c2769..2717f00612a 100644
--- 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 0285c0571f7..eaeba966444 100644
--- 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))
-- 
2.39.2