[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
emacs-29 c6660a6d6de: Improve documentation of 'repeat-mode' and related
From: |
Eli Zaretskii |
Subject: |
emacs-29 c6660a6d6de: Improve documentation of 'repeat-mode' and related variables |
Date: |
Thu, 2 Feb 2023 08:36:20 -0500 (EST) |
branch: emacs-29
commit c6660a6d6de9450f030db6d77eeaa76b8bdd14ef
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>
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.
---
doc/emacs/basic.texi | 46 +++++++++++++++++++++++++++++++++-------------
lisp/bindings.el | 6 +++---
lisp/repeat.el | 49 ++++++++++++++++++++++++++++++-------------------
lisp/tab-bar.el | 4 ++--
lisp/window.el | 5 +++--
5 files changed, 71 insertions(+), 39 deletions(-)
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 <return> 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:
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- emacs-29 c6660a6d6de: Improve documentation of 'repeat-mode' and related variables,
Eli Zaretskii <=