[Emacs-diffs] /srv/bzr/emacs/trunk r107132: Document make-composed-keymap

[Glenn Morris]

------------------------------------------------------------
revno: 107132
committer: Glenn Morris <address@hidden>
branch nick: trunk
timestamp: Sun 2012-02-05 19:20:11 -0800
message:
  Document make-composed-keymap
  
  * doc/lispref/keymaps.texi (Inheritance and Keymaps):
  Mention make-composed-keymap and multiple inheritance.
  * etc/NEWS: Related edits.
modified:
  doc/lispref/ChangeLog
  doc/lispref/keymaps.texi
  etc/NEWS

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2012-02-06 01:27:57 +0000
+++ b/doc/lispref/ChangeLog     2012-02-06 03:20:11 +0000
@@ -1,6 +1,8 @@
 2012-02-06  Glenn Morris  <address@hidden>
 
        * keymaps.texi (Tool Bar): Mention separators.
+       (Inheritance and Keymaps):
+       Mention make-composed-keymap and multiple inheritance.
 
        * modes.texi (Running Hooks): Mention run-hook-wrapped.
 

=== modified file 'doc/lispref/keymaps.texi'
--- a/doc/lispref/keymaps.texi  2012-02-06 01:27:57 +0000
+++ b/doc/lispref/keymaps.texi  2012-02-06 03:20:11 +0000
@@ -432,6 +432,34 @@
 @code{nil}, so these character's bindings are never inherited from
 the parent keymap.
 
address@hidden keymap inheritance from multiple maps
+  Sometimes you want to make a keymap that inherits from more than one
+map.  You can use the function @code{make-composed-keymap} for this.
+
address@hidden make-composed-keymap maps &optional parent
+This function returns a new keymap composed of the existing keymap(s)
address@hidden, and optionally inheriting from a parent keymap
address@hidden  @var{maps} can be a single keymap or a list of more
+than one.  When looking up a key in the resulting new map, Emacs
+searches in each of the @var{maps}, and then in @var{parent}, stopping
+at the first match.  A @code{nil} binding in any one of @var{maps}
+overrides any binding in @var{parent}, but not a address@hidden binding
+in any other of the @var{maps}.
address@hidden defun
+
address@hidden For example, here is how Emacs sets the parent of
address@hidden, such that it inherits from both
address@hidden and @code{special-mode-map}:
+
address@hidden
+(defvar help-mode-map
+  (let ((map (make-sparse-keymap)))
+    (set-keymap-parent map (make-composed-keymap button-buffer-map
+                                                 special-mode-map))
+    ... map) ... )
address@hidden example
+
+
 @node Prefix Keys
 @section Prefix Keys
 @cindex prefix key

=== modified file 'etc/NEWS'
--- a/etc/NEWS  2012-02-06 01:45:12 +0000
+++ b/etc/NEWS  2012-02-06 03:20:11 +0000
@@ -1412,8 +1412,11 @@
 ---
 ** rx.el has a new `group-n' construct for explicitly numbered groups.
 
-** keymaps can inherit from multiple parents.
-There is a new function `make-composed-keymap' that [does something].
++++
+** New function `make-composed-keymap' that constructs a new keymap
+from multiple input maps.  You can use this to make a keymap that
+inherits from multiple maps, eg:
+ (set-keymap-parent newmap (make-composed-keymap othermap parent))
 
 +++
 ** Set `debug-on-event' to make Emacs enter the debugger e.g. on receipt