master e93aa8d586 1/2: ; Improve documentation of 'set-transient-map' changes

[Eli Zaretskii]

branch: master
commit e93aa8d58670f013b9a457e7136a6284f173a8ce
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    ; 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 8df4b6f2b4..f5341f40f0 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 e169447025..2013260c15 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 44d094d28d..6bf12fd757 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,