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

* etc/NEWS: Related edit.

2 files changed, 14 insertions, 5 deletions

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