From e93aa8d58670f013b9a457e7136a6284f173a8ce Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Thu, 7 Jul 2022 09:29:51 +0300 Subject: [PATCH] ; Improve documentation of 'set-transient-map' changes * lisp/subr.el (set-transient-map-timeout, set-transient-map): Doc fixes. * etc/NEWS: Improve wording of the 'set-transient-map' entry. * doc/lispref/keymaps.texi (Controlling Active Maps): Fix wording and passive tense, and improve indexing. (Bug#21634) --- doc/lispref/keymaps.texi | 22 +++++++++++++--------- etc/NEWS | 9 +++++---- lisp/subr.el | 29 ++++++++++++++++------------- 3 files changed, 34 insertions(+), 26 deletions(-) diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi index 8df4b6f2b47..f5341f40f0a 100644 --- a/doc/lispref/keymaps.texi +++ b/doc/lispref/keymaps.texi @@ -1063,15 +1063,19 @@ The optional argument @var{on-exit}, if non-@code{nil}, specifies a function that is called, with no arguments, after @var{keymap} is deactivated. -The optional argument @var{message}, if a string, specifies the format -string for the message to display after activating the transient map. -When the string contains the specifier @samp{%k}, it's replaced with -the list of keys from the transient map. - -The optional argument @var{timeout}, if a number, specifies the number -of seconds of idle time after which @var{keymap} is deactivated. The -value of the argument @var{timeout} can be overridden by the variable -@code{set-transient-map-timeout}. +The optional argument @var{message} specifies the message to display +after activating the transient map. If @var{message} is a string, it +is the format string for the message, and any @samp{%k} specifier in +that string is replaced with the list of keys from the transient map. +Any other non-@code{nil} value of @var{message} stands for the default +message format @samp{Repeat with %k}. + +@vindex set-transient-map-timeout +If the optional argument @var{timeout} is non-@code{nil}, it should be +a number that specifies how many seconds of idle time to wait before +deactivating @var{keymap}. The value of the variable +@code{set-transient-map-timeout}, if non-@code{nil}, overrides the +value of this argument. This function works by adding and removing @var{keymap} from the variable @code{overriding-terminal-local-map}, which takes precedence diff --git a/etc/NEWS b/etc/NEWS index e1694470258..2013260c151 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -2279,10 +2279,11 @@ patcomp.el, pc-mode.el, pc-select.el, s-region.el, and sregex.el. +++ ** New arguments MESSAGE and TIMEOUT of 'set-transient-map'. -MESSAGE specifies a string that lists available keys, -and TIMEOUT deactivates the transient map after the specified -number of seconds. The default timeout is defined by -the new variable 'set-transient-map-timeout'. +MESSAGE specifies a message to display after activating the transient +map, including a special formatting spec to list available keys. +TIMEOUT is the idle time after which to deactivate the transient map. +The default timeout value can be defined by the new variable +'set-transient-map-timeout'. +++ ** New function 'seq-split'. diff --git a/lisp/subr.el b/lisp/subr.el index 44d094d28dd..6bf12fd7577 100644 --- a/lisp/subr.el +++ b/lisp/subr.el @@ -6014,9 +6014,10 @@ To test whether a function can be called interactively, use 'set-temporary-overlay-map #'set-transient-map "24.4") (defvar set-transient-map-timeout nil - "Deactivate the transient map after specified timeout. -When a number, after idle time of the specified number of seconds -deactivate the map set by the previous call of `set-transient-map'.") + "Timeout in seconds for deactivation of a transient keymap. +If this is a number, it specifies the amount of idle time +after which to deactivate the keymap set by `set-transient-map', +thus overriding the value of the TIMEOUT argument to that function.") (defvar set-transient-map-timer nil "Timer for `set-transient-map-timeout'.") @@ -6032,16 +6033,18 @@ if it returns non-nil, then MAP stays active. Optional arg ON-EXIT, if non-nil, specifies a function that is called, with no arguments, after MAP is deactivated. -Optional arg MESSAGE, if a string, specifies the format string for the -message to display after activating the transient map. When the string -contains the specifier %k, it's replaced with the list of keys from the -transient map. Other non-nil values of MESSAGE use the message format -\"Repeat with %k\". On deactivating the map the displayed message -is cleared out. - -Optional arg TIMEOUT, if a number, specifies the number of seconds -of idle time after which the map is deactivated. The variable -`set-transient-map-timeout' overrides the argument TIMEOUT. +Optional arg MESSAGE, if non-nil, requests display of an informative +message after activating the transient map. If MESSAGE is a string, +it specifies the format string for the message to display, and the %k +specifier in the string is replaced with the list of keys from the +transient map. Any other non-nil value of MESSAGE means to use the +message format string \"Repeat with %k\". Upon deactivating the map, +the displayed message will be cleared out. + +Optional arg TIMEOUT, if non-nil, should be a number specifying the +number of seconds of idle time after which the map is deactivated. +The variable `set-transient-map-timeout', if non-nil, overrides the +value of TIMEOUT. This function uses `overriding-terminal-local-map', which takes precedence over all other keymaps. As usual, if no match for a key is found in MAP, -- 2.39.5