mirror/emacs
1
0
Fork 0
mirror of https://git.savannah.gnu.org/git/emacs.git synced 2024-11-27 07:37:33 +00:00
Code Issues Releases Activity

Improve documentation of 'repeat-mode' and related variables

Browse Source 
* 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.
This commit is contained in:
Eli Zaretskii 2023-02-02 15:34:58 +02:00
parent be304bb328
commit c6660a6d6d
5 changed files with 71 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

46
doc/emacs/basic.texi
View File

@ -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.

6
lisp/bindings.el
View File

@ -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)

49
lisp/repeat.el
View File

@ -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))

4
lisp/tab-bar.el
View File

@ -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

5
lisp/window.el
View File

@ -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: