[Emacs-diffs] /srv/bzr/emacs/emacs-24 r110866: Document set-temporary-overlay-map

[Glenn Morris]

------------------------------------------------------------
revno: 110866
committer: Glenn Morris <address@hidden>
branch nick: emacs-24
timestamp: Wed 2012-11-14 00:45:50 -0800
message:
  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.
modified:
  doc/lispref/ChangeLog
  doc/lispref/keymaps.texi
  etc/NEWS

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2012-11-14 08:18:12 +0000
+++ b/doc/lispref/ChangeLog     2012-11-14 08:45:50 +0000
@@ -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  <address@hidden>
 

=== modified file 'doc/lispref/keymaps.texi'
--- a/doc/lispref/keymaps.texi  2012-11-14 08:18:12 +0000
+++ b/doc/lispref/keymaps.texi  2012-11-14 08:45:50 +0000
@@ -664,7 +664,9 @@
 
   The highest precedence normal keymap comes from the @code{keymap}
 text or overlay property.  If that is address@hidden, 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}.
address@hidden Active Maps}.
 
   However, there are also special ways for programs to substitute
 other keymaps for some of those.  The variable
@@ -753,6 +755,7 @@
      (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 @@
 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 address@hidden 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 @@
 @code{minor-mode-overriding-map-alist}.
 @end defvar
 
address@hidden 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
address@hidden 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
address@hidden then @var{keymap} stays active.
+
+For a pseudo-Lisp description of exactly how and when this keymap applies,
address@hidden Keymaps}.
address@hidden defun
+
 @node Key Lookup
 @section Key Lookup
 @cindex key lookup

=== modified file 'etc/NEWS'
--- a/etc/NEWS  2012-11-14 08:29:25 +0000
+++ b/etc/NEWS  2012-11-14 08:45:50 +0000
@@ -932,7 +932,7 @@
 *** `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).
 +++