From: Eli Zaretskii Date: Thu, 2 Feb 2023 13:34:58 +0000 (+0200) Subject: Improve documentation of 'repeat-mode' and related variables X-Git-Tag: emacs-29.0.90~543 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=c6660a6d6de9450f030db6d77eeaa76b8bdd14ef;p=emacs.git Improve documentation of 'repeat-mode' and related variables * lisp/bindings.el (next-error-repeat-map) (page-navigation-repeat-map, undo-repeat-map): * lisp/tab-bar.el (tab-bar-switch-repeat-map) (tab-bar-move-repeat-map): * lisp/window.el (other-window-repeat-map) (resize-window-repeat-map): Mention repeatable commands in the doc strings. * lisp/repeat.el (repeat-exit-timeout, repeat-check-key) (repeat-echo-function, repeat-mode, repeat-check-key) (repeat-check-map, repeat-echo-message-string) (repeat-echo-message, repeat-echo-mode-line) (describe-repeat-maps): Improve wording of doc strings. (describe-repeat-maps): Improve wording of the heading line. (Bug#61183) * doc/emacs/basic.texi (Repeating): Clarify and improve wording of 'repeat-mode' documentation. --- diff --git a/doc/emacs/basic.texi b/doc/emacs/basic.texi index d8a354ff42d..a271cb65bdc 100644 --- a/doc/emacs/basic.texi +++ b/doc/emacs/basic.texi @@ -890,17 +890,37 @@ subsequent @kbd{z} repeats it once again. @findex describe-repeat-maps @vindex repeat-exit-key @vindex repeat-exit-timeout - Also you can activate @code{repeat-mode} that temporarily enables a -transient mode with short keys after a limited number of commands. -Currently supported shorter key sequences are @kbd{C-x u u} instead of -@kbd{C-x u C-x u} to undo many changes, @kbd{C-x o o} instead of -@kbd{C-x o C-x o} to switch several windows, @kbd{C-x @{ @{ @} @} ^ ^ -v v} to resize the selected window interactively, @kbd{M-g n n p p} to -navigate @code{next-error} matches, @kbd{C-x ] ] [ [} to navigate -through pages, and other keys listed by @code{describe-repeat-maps}. -Any other key exits transient mode and then is executed normally. The -user option @code{repeat-exit-key} defines an additional key to exit -this transient mode. Also it's possible to break the repetition chain -automatically after some idle time by customizing the user option + You can also activate @code{repeat-mode} which allows repeating +commands bound to sequences of two or more keys by typing a single +character. For example, after typing @w{@kbd{C-x u}} (@code{undo}, +@pxref{Undo}) to undo the most recent edits, you can undo many more +edits by typing @w{@kbd{u u u@dots{}}}. Similarly, type @w{@kbd{C-x o +o o@dots{}}} instead of @w{@kbd{C-x o C-x o C-x o@dots{}}} to switch +to the window several windows away. This works by entering a +transient repeating mode after you type the full key sequence that +invokes the command; the single-key shortcuts are shown in the echo +area. + +Only some commands support repetition in @code{repeat-mode}; type +@w{@kbd{M-x describe-repeat-maps @key{RET}}} to see which ones. + +The single-character shortcuts enabled by the transient repeating mode +do not need to be identical: for example, after typing @w{@kbd{C-x +@{}}, either @kbd{@{} or @kbd{@}} or @kbd{^} or @kbd{v}, or any series +that mixes these characters in any order, will resize the selected +window in respective ways. Similarly, after @w{@kbd{M-g n}} or +@kbd{M-g p}, typing any sequence of @kbd{n} and/or @kbd{p} in any mix +will repeat @code{next-error} and @code{previous-error} to navigate in +a @file{*compilation*} or @file{*grep*} buffer (@pxref{Compilation +Mode}). + +Typing any key other than those defined to repeat the previous command +exits the transient repeating mode, and then the key you typed is +executed normally. You can also define a key which will exit the +transient repeating mode @emph{without} executing the key which caused +the exit. To this end, customize the user option +@code{repeat-exit-key} to name a key; one natural value is @key{RET}. +Finally, it's possible to break the repetition chain automatically +after some amount of idle time: customize the user option @code{repeat-exit-timeout} to specify the idle time in seconds after -which this transient mode will be turned off. +which this transient repetition mode will be turned off automatically. diff --git a/lisp/bindings.el b/lisp/bindings.el index 34aa8399a96..f4881ac388c 100644 --- a/lisp/bindings.el +++ b/lisp/bindings.el @@ -1009,7 +1009,7 @@ if `inhibit-field-text-motion' is non-nil." ;; no idea whereas to bind it. Any suggestion welcome. -stef ;; (define-key ctl-x-map "U" 'undo-only) (defvar-keymap undo-repeat-map - :doc "Keymap to repeat undo key sequences \\`C-x u u'. Used in `repeat-mode'." + :doc "Keymap to repeat `undo' commands. Used in `repeat-mode'." :repeat t "u" #'undo) @@ -1106,7 +1106,7 @@ if `inhibit-field-text-motion' is non-nil." (define-key ctl-x-map "`" 'next-error) (defvar-keymap next-error-repeat-map - :doc "Keymap to repeat `next-error' key sequences. Used in `repeat-mode'." + :doc "Keymap to repeat `next-error' and `previous-error'. Used in `repeat-mode'." :repeat t "n" #'next-error "M-n" #'next-error @@ -1468,7 +1468,7 @@ if `inhibit-field-text-motion' is non-nil." (define-key ctl-x-map "]" 'forward-page) (defvar-keymap page-navigation-repeat-map - :doc "Keymap to repeat page navigation key sequences. Used in `repeat-mode'." + :doc "Keymap to repeat `forward-page' and `backward-page'. Used in `repeat-mode'." :repeat t "]" #'forward-page "[" #'backward-page) diff --git a/lisp/repeat.el b/lisp/repeat.el index ce59b310792..37d4aaec985 100644 --- a/lisp/repeat.el +++ b/lisp/repeat.el @@ -349,7 +349,7 @@ For example, you can set it to like `isearch-exit'." :version "28.1") (defcustom repeat-exit-timeout nil - "Break the repetition chain of keys after specified timeout. + "Break the repetition chain of keys after specified amount of idle time. When a number, exit the transient repeating mode after idle time of the specified number of seconds. You can also set the property `repeat-exit-timeout' on the command symbol. @@ -380,12 +380,12 @@ This property can override the value of this variable." (defcustom repeat-check-key t "Whether to check that the last key exists in the repeat map. -When non-nil and the last typed key (with or without modifiers) -doesn't exist in the keymap attached by the `repeat-map' property, -then don't activate that keymap for the next command. So only the -same keys among repeatable keys are allowed in the repeating sequence. -For example, with a non-nil value, only \\`C-x u u' repeats undo, -whereas \\`C-/ u' doesn't. +When non-nil, and the last typed key (with or without modifiers) +doesn't exist in the keymap specified by the `repeat-map' property +of the command, don't activate that keymap for the next command. +Thus, when this is non-nil, only the same keys among repeatable +keys are allowed in the repeating sequence. For example, with a +non-nil value, only \\`C-x u u' repeats undo, whereas \\`C-/ u' doesn't. You can also set the property `repeat-check-key' on the command symbol. This property can override the value of this variable. @@ -398,7 +398,7 @@ but the property value is `t', then check the last key." (defcustom repeat-echo-function #'repeat-echo-message "Function to display a hint about available keys. -Function is called after every repeatable command with one argument: +The function is called after every repeatable command with one argument: a repeating map, or nil after deactivating the transient repeating mode. You can use `add-function' for multiple functions simultaneously." :type '(choice (const :tag "Show hints in the echo area" @@ -422,8 +422,12 @@ the map can't be set on the command symbol property `repeat-map'.") ;;;###autoload (define-minor-mode repeat-mode "Toggle Repeat mode. -When Repeat mode is enabled, and the command symbol has the property named -`repeat-map', this map is activated temporarily for the next command. +When Repeat mode is enabled, certain commands bound to multi-key +sequences can be repeated by typing a single key, after typing the +full key sequence once. +The commands which can be repeated like that are those whose symbol + has the property `repeat-map' which specifies a keymap of single +keys for repeating. See `describe-repeat-maps' for a list of all repeatable commands." :global t :group 'repeat (if (not repeat-mode) @@ -459,7 +463,7 @@ See `describe-repeat-maps' for a list of all repeatable commands." rep-map)))) (defun repeat-check-key (key map) - "Check if the last key is suitable to activate the repeating MAP." + "Check if the last KEY is suitable for activating the repeating MAP." (let* ((prop (repeat--command-property 'repeat-check-key)) (check-key (unless (eq prop 'no) (or prop repeat-check-key)))) (or (not check-key) @@ -471,7 +475,7 @@ See `describe-repeat-maps' for a list of all repeatable commands." "Previous minibuffer state.") (defun repeat-check-map (map) - "Decides whether MAP can be used for the next command." + "Decide whether MAP can be used for the next command." (and map ;; Detect changes in the minibuffer state to allow repetitions ;; in the same minibuffer, but not when the minibuffer is activated @@ -547,7 +551,7 @@ This function can be used to force exit of repetition while it's active." (setq repeat-exit-function nil))) (defun repeat-echo-message-string (keymap) - "Return a string with a list of repeating keys." + "Return a string with the list of repeating keys in KEYMAP." (let (keys) (map-keymap (lambda (key cmd) (and cmd (push key keys))) keymap) (format-message "Repeat with %s%s" @@ -565,7 +569,8 @@ This function can be used to force exit of repetition while it's active." "")))) (defun repeat-echo-message (keymap) - "Display available repeating keys in the echo area." + "Display in the echo area the repeating keys defined by KEYMAP. +See `repeat-echo-function' to enable/disable." (let ((message-log-max nil)) (if keymap (let ((message (repeat-echo-message-string keymap))) @@ -586,7 +591,9 @@ This function can be used to force exit of repetition while it's active." "String displayed in the mode line in repeating mode.") (defun repeat-echo-mode-line (keymap) - "Display the repeat indicator in the mode line." + "Display the repeat indicator in the mode line. +KEYMAP should be non-nil, but is otherwise ignored. +See `repeat-echo-function' to enable/disable." (if keymap (unless (assq 'repeat-in-progress mode-line-modes) (add-to-list 'mode-line-modes (list 'repeat-in-progress @@ -596,9 +603,11 @@ This function can be used to force exit of repetition while it's active." (declare-function help-fns--analyze-function "help-fns" (function)) (defun describe-repeat-maps () - "Describe mappings of commands repeatable by symbol property `repeat-map'. -If `repeat-mode' is enabled, these keymaps determine which single key -can be used to repeat a command invoked via a full key sequence." + "Describe transient keymaps installed for repeating multi-key commands. +These keymaps enable repetition of commands bound to multi-key +sequences by typing just one key, when `repeat-mode' is enabled. +Commands that can be repeated this way must have their symbol +to have the `repeat-map' property whose value specified a keymap." (interactive) (require 'help-fns) (let ((help-buffer-under-preparation t)) @@ -613,7 +622,9 @@ can be used to repeat a command invoked via a full key sequence." (with-help-window (help-buffer) (with-current-buffer standard-output (setq-local outline-regexp "[*]+") - (insert "A list of keymaps used by commands with the symbol property `repeat-map'.\n") + (insert "\ +A list of keymaps and their single-key shortcuts for repeating commands. +Click on a keymap to see the commands repeatable by the keymap.\n") (dolist (keymap (sort keymaps (lambda (a b) (when (and (symbolp (car a)) diff --git a/lisp/tab-bar.el b/lisp/tab-bar.el index 119a243d6b3..dce6fa735fc 100644 --- a/lisp/tab-bar.el +++ b/lisp/tab-bar.el @@ -2624,14 +2624,14 @@ When `switch-to-buffer-obey-display-actions' is non-nil, (keymap-set tab-prefix-map "t" #'other-tab-prefix) (defvar-keymap tab-bar-switch-repeat-map - :doc "Keymap to repeat tab switch key sequences \\`C-x t o o O'. + :doc "Keymap to repeat tab switch commands `tab-next' and `tab-previous'. Used in `repeat-mode'." :repeat t "o" #'tab-next "O" #'tab-previous) (defvar-keymap tab-bar-move-repeat-map - :doc "Keymap to repeat tab move key sequences \\`C-x t m m M'. + :doc "Keymap to repeat tab move commands `tab-move' and `tab-bar-move-tab-backward'. Used in `repeat-mode'." :repeat t "m" #'tab-move diff --git a/lisp/window.el b/lisp/window.el index 0cd30822ff6..2d9f746d8fb 100644 --- a/lisp/window.el +++ b/lisp/window.el @@ -10567,8 +10567,7 @@ displaying that processes's buffer." (define-key ctl-x-4-map "4" 'other-window-prefix) (defvar-keymap other-window-repeat-map - :doc "Keymap to repeat `other-window' key sequences. -Used in `repeat-mode'." + :doc "Keymap to repeat `other-window'. Used in `repeat-mode'." :repeat t "o" #'other-window "O" (lambda () @@ -10578,6 +10577,8 @@ Used in `repeat-mode'." (defvar-keymap resize-window-repeat-map :doc "Keymap to repeat window resizing commands. +Repeatable commands are `enlarge-window' and `shrink-window', +and also `enlarge-window-horizontally' and `shrink-window-horizontally'. Used in `repeat-mode'." :repeat t ;; Standard keys: