[Emacs-diffs] master 4a2092e: Advertize set-keymap-parent as replacement for copy-keymap

[Stefan Monnier]

branch: master
commit 4a2092efd2ac76fce04a2587b360ed2ca1eac4d7
Author: Stefan Monnier <address@hidden>
Commit: Stefan Monnier <address@hidden>

    Advertize set-keymap-parent as replacement for copy-keymap
    
    * doc/lispref/keymaps.texi (Creating Keymaps):
    * src/keymap.c (Fcopy_keymap): Advertize set-keymap-parent as replacement.
---
 doc/lispref/keymaps.texi |   16 +++++++++++++++-
 src/keymap.c             |   14 ++++++++++++--
 2 files changed, 27 insertions(+), 3 deletions(-)

diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi
index 61ac80c..9abbd89 100644
--- a/doc/lispref/keymaps.texi
+++ b/doc/lispref/keymaps.texi
@@ -341,7 +341,21 @@ lots of bindings; for just a few, the sparse keymap is 
better.
 @end defun
 
 @defun copy-keymap keymap
-This function returns a copy of @var{keymap}.  Any keymaps that
+This function returns a copy of @var{keymap}.  This is almost never
+needed.  If you want a keymap that's like another yet with a few
+changes, you should use map inheritance rather than copying.
+I.e., something like:
+
address@hidden
address@hidden
+(let ((map (make-sparse-keymap)))
+  (set-keymap-parent map <theirmap>)
+  (define-key map ...)
+  ...)
address@hidden group
address@hidden example
+
+When performing @code{copy-keymap}, any keymaps that
 appear directly as bindings in @var{keymap} are also copied recursively,
 and so on to any number of levels.  However, recursive copying does not
 take place when the definition of a character is a symbol whose function
diff --git a/src/keymap.c b/src/keymap.c
index 44335ad..b27df1d 100644
--- a/src/keymap.c
+++ b/src/keymap.c
@@ -971,8 +971,18 @@ copy_keymap_1 (Lisp_Object chartable, Lisp_Object idx, 
Lisp_Object elt)
 
 DEFUN ("copy-keymap", Fcopy_keymap, Scopy_keymap, 1, 1, 0,
        doc: /* Return a copy of the keymap KEYMAP.
-The copy starts out with the same definitions of KEYMAP,
-but changing either the copy or KEYMAP does not affect the other.
+
+Note that this is almost never needed.  If you want a keymap that's like
+another yet with a few changes, you should use map inheritance rather
+than copying.  I.e. something like:
+
+    (let ((map (make-sparse-keymap)))
+      (set-keymap-parent map <theirmap>)
+      (define-key map ...)
+      ...)
+
+After performing `copy-keymap', the copy starts out with the same definitions
+of KEYMAP, but changing either the copy or KEYMAP does not affect the other.
 Any key definitions that are subkeymaps are recursively copied.
 However, a key definition which is a symbol whose definition is a keymap
 is not copied.  */)