Document make-composed-keymap

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

3 files changed, 35 insertions, 2 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index e26f91b1b4c..5de2251c19f 100644
--- 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 923989413ee..a4c8c3981f3 100644
--- 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 f1088874eb8..2e50271d2dd 100644
--- 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