Document make-composed-keymap

* doc/lispref/keymaps.texi (Inheritance and Keymaps):
Mention make-composed-keymap and multiple inheritance.
* etc/NEWS: Related edits.

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index e26f91b1b4c675cbde1ac7dfb594773bedb2fc6b..5de2251c19f44163fae10641913a8b2e992f4c88 100644 (file)
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,6 +1,8 @@
 2012-02-06  Glenn Morris  <rgm@gnu.org>
 
        * keymaps.texi (Tool Bar): Mention separators.
+       (Inheritance and Keymaps):
+       Mention make-composed-keymap and multiple inheritance.
 
        * modes.texi (Running Hooks): Mention run-hook-wrapped.
 

diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi
index 923989413ee30f5de38c7b654da40d2044df7575..a4c8c3981f3e368528eb6df38d153ba5e5831e89 100644 (file)
--- a/doc/lispref/keymaps.texi
+++ b/doc/lispref/keymaps.texi
@@ -432,6 +432,34 @@ for every numeric character code without modifier bits, even if it is
 @code{nil}, so these character's bindings are never inherited from
 the parent keymap.
 
+@cindex 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.
+
+@defun make-composed-keymap maps &optional parent
+This function returns a new keymap composed of the existing keymap(s)
+@var{maps}, and optionally inheriting from a parent keymap
+@var{parent}.  @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 non-@code{nil} binding
+in any other of the @var{maps}.
+@end defun
+
+@noindent For example, here is how Emacs sets the parent of
+@code{help-mode-map}, such that it inherits from both
+@code{button-buffer-map} and @code{special-mode-map}:
+
+@example
+(defvar help-mode-map
+  (let ((map (make-sparse-keymap)))
+    (set-keymap-parent map (make-composed-keymap button-buffer-map
+                                                 special-mode-map))
+    ... map) ... )
+@end example
+
+
 @node Prefix Keys
 @section Prefix Keys
 @cindex prefix key

diff --git a/etc/NEWS b/etc/NEWS
index f1088874eb8f524d09db41acd9229d7223940939..2e50271d2dd45a0772c40bb7593ed12c25864702 100644 (file)
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1412,8 +1412,11 @@ as well as those in the -*- line.
 ---
 ** 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