* lisp/subr.el (set-temporary-overlay-map): Doc fix.

* etc/NEWS: Related edit.

3 files changed, 17 insertions, 6 deletions

diff --git a/etc/NEWS b/etc/NEWS
index 9fcb2d13565..e7e178744a7 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -932,7 +932,9 @@ describing the cycle.
 *** `function-get' fetches a function property, following aliases.
 +++
 *** `posnp' tests if an object is a `posn'.
-*** `set-temporary-overlay-map' sets up a temporary overlay map.
+
+*** `set-temporary-overlay-map' sets up a temporary keymap that
+takes precedence over most other maps for a short while (normally one key).
 +++
 *** `system-users' returns the user names on the system.
 +++
diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index c13ef1289f8..80ae61df8c1 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,7 @@
+2012-11-14  Glenn Morris  <rgm@gnu.org>
+
+        * subr.el (set-temporary-overlay-map): Doc fix.
+
 2012-11-13  Martin Rudalics  <rudalics@gmx.at>
 
         * window.el (record-window-buffer)
diff --git a/lisp/subr.el b/lisp/subr.el
index d328b7cddf5..d02b889ec44 100644
--- a/lisp/subr.el
+++ b/lisp/subr.el
@@ -3960,11 +3960,16 @@ The properties used on SYMBOL are `composefunc', `sendfunc',
   (put symbol 'hookvar (or hookvar 'mail-send-hook)))
 
 (defun set-temporary-overlay-map (map &optional keep-pred)
-  "Set MAP as a temporary overlay map.
-When KEEP-PRED is `t', using a key from the temporary keymap
-leaves this keymap activated.  KEEP-PRED can also be a function,
-which will have the same effect when it returns `t'.
-When KEEP-PRED is nil, the temporary keymap is used only once."
+  "Set MAP as a temporary keymap taking precedence over most other keymaps.
+Note that this does NOT take precedence over the \"overriding\" maps
+`overriding-terminal-local-map' and `overriding-local-map' (or the
+`keymap' text property).  Unlike those maps, if no match for a key is
+found in MAP, the normal key lookup sequence then continues.
+
+Normally, MAP is used only once.  If the optional argument
+KEEP-PRED is `t', MAP stays active if a key from MAP is used.
+KEEP-PRED can also be a function of no arguments: if it returns
+non-nil then MAP stays active."
   (let* ((clearfunsym (make-symbol "clear-temporary-overlay-map"))
          (overlaysym (make-symbol "t"))
          (alist (list (cons overlaysym map)))