Document set-temporary-overlay-map

* doc/lispref/keymaps.texi (Active Keymaps, Searching Keymaps)
(Controlling Active Maps): Document set-temporary-overlay-map.

* etc/NEWS: Related markup.

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 5bdcf86..e5320bf 100644 (file)
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -2,6 +2,8 @@
 
        * keymaps.texi (Searching Keymaps, Tool Bar): Untabify examples,
        so they align better in info.
+       (Active Keymaps, Searching Keymaps, Controlling Active Maps):
+       Document set-temporary-overlay-map.
 
 2012-11-12  Glenn Morris  <rgm@gnu.org>
 

diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi
index 7605f23..f6d571e 100644 (file)
--- a/doc/lispref/keymaps.texi
+++ b/doc/lispref/keymaps.texi
@@ -664,7 +664,9 @@ additional active keymaps through the variable
 
   The highest precedence normal keymap comes from the @code{keymap}
 text or overlay property.  If that is non-@code{nil}, it is the first
-keymap to be processed, in normal circumstances.
+keymap to be processed, in normal circumstances.  Next comes
+any keymap added by the function @code{set-temporary-overlay-map}.
+@xref{Controlling Active Maps}.
 
   However, there are also special ways for programs to substitute
 other keymaps for some of those.  The variable
@@ -753,6 +755,7 @@ them:
      (overriding-local-map
       (@var{find-in} overriding-local-map))
      ((or (@var{find-in} (get-char-property (point) 'keymap))
+          (@var{find-in} @var{temp-map})
           (@var{find-in-any} emulation-mode-map-alists)
           (@var{find-in-any} minor-mode-overriding-map-alist)
           (@var{find-in-any} minor-mode-map-alist)
@@ -770,7 +773,8 @@ Lookup}.)  If the key sequence starts with a mouse event, or a
 symbolic prefix event followed by a mouse event, that event's position
 is used instead of point and the current buffer.  Mouse events on an
 embedded string use non-@code{nil} text properties from that string
-instead of the buffer.
+instead of the buffer.  @var{temp-map} is a pseudo variable that
+represents the effect of a @code{set-temporary-overlay-map} call.
 
   When a match is found (@pxref{Key Lookup}), if the binding in the
 keymap is a function, the search is over.  However if the keymap entry
@@ -950,6 +954,21 @@ are used before @code{minor-mode-map-alist} and
 @code{minor-mode-overriding-map-alist}.
 @end defvar
 
+@defun set-temporary-overlay-map keymap &optional keep
+This function adds @var{keymap} as a temporary keymap that takes
+precedence over most other keymaps.  It does not take precedence over
+the ``overriding'' maps (see above); and unlike them, if no match for
+a key is found in @var{keymap}, the search continues.
+
+Normally, @var{keymap} is used only once.  If the optional argument
+@var{pred} is @code{t}, the map stays active if a key from @var{keymap}
+is used.  @var{pred} can also be a function of no arguments: if it returns
+non-@code{nil} then @var{keymap} stays active.
+
+For a pseudo-Lisp description of exactly how and when this keymap applies,
+@pxref{Searching Keymaps}.
+@end defun
+
 @node Key Lookup
 @section Key Lookup
 @cindex key lookup

diff --git a/etc/NEWS b/etc/NEWS
index e7e1787..84bedfb 100644 (file)
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -932,7 +932,7 @@ 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 keymap that
 takes precedence over most other maps for a short while (normally one key).
 +++