From 4a6eefb93a5781b08903f27325676cda0a40321c Mon Sep 17 00:00:00 2001
From: Robert Pluim <rpluim@gmail.com>
Date: Tue, 21 Mar 2023 10:56:07 +0100
Subject: [PATCH] Expand defvar-keymap documentation

* doc/lispref/keymaps.texi (Creating Keymaps): Describe the :repeat keyword.
---
 doc/lispref/keymaps.texi | 61 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 61 insertions(+)

diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi
index 0eea696c612..fdab5075b94 100644
--- a/doc/lispref/keymaps.texi
+++ b/doc/lispref/keymaps.texi
@@ -451,9 +451,70 @@ Here's an example:
 @lisp
 (defvar-keymap eww-textarea-map
   :parent text-mode-map
+  :doc "Keymap for the eww text area."
   "RET" #'forward-line
   "TAB" #'shr-next-link)
 @end lisp
+
+@kindex :repeat
+@kindex repeat-mode
+@cindex repeatable key bindings
+Each command in the keymap can be marked as `repeatable', i.e. usable
+in @code{repeat-mode}, by putting a @code{repeat-map} property on it,
+e.g.
+
+@lisp
+(put 'undo 'repeat-map 'undo-repeat-map)
+@end lisp
+
+where the value of the property is the map to be used by
+@code{repeat-mode}.
+
+To avoid repetitive invocations of @code{put}, @code{defvar-keymap}
+also has a @code{:repeat} keyword, which can be used to specify which
+commands in the keymap are usable by @code{repeat-mode}.  The
+following values are available:
+
+@table @code
+@item t
+This means all the commands in the keymap are repeatable, and is the
+most common usage.
+
+@item (:enter (commands ...) :exit (commands ...))
+This specifies that the commands in the @code{:enter} list enter
+@code{repeat-mode}, and the commands in the @code{:exit} list exit
+repeat mode.
+
+If the @code{:enter} list is empty, then all commands in the map enter
+@code{repeat-mode}.  Specifying one or more commands in this list is
+useful if there is a command which doesn't exist in the map being
+defined, but which should have the @code{repeat-map} property.
+
+If the @code{:exit} list is empty then no commands in the map exit
+@code{repeat-mode}.  Specifying one ore more commands in this list is
+useful if the keymap being defined contains a command that should not
+have the @code{repeat-map} property.
+@end table
+
+In order to make e.g.@: @kbd{u} repeat the @code{undo} command, the
+following two stanzas are equivalent:
+
+@lisp
+(defvar-keymap undo-repeat-map
+  "u" #'undo)
+(put 'undo 'repeat-map 'undo-repeat-map)
+@end lisp
+
+and
+
+@lisp
+(defvar-keymap undo-repeat-map
+  :repeat t
+  "u" #'undo)
+@end lisp
+
+The latter is preferred when there are many commands in the map, all
+of which should be repeatable.
 @end defmac
 
 @defun copy-keymap keymap
-- 
2.39.5