From 4a6eefb93a5781b08903f27325676cda0a40321c Mon Sep 17 00:00:00 2001 From: Robert Pluim 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