diff options
| -rw-r--r-- | doc/lispref/keymaps.texi | 16 | ||||
| -rw-r--r-- | src/keymap.c | 14 |
2 files changed, 27 insertions, 3 deletions
diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi index 61ac80c589c..9abbd898d91 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: + +@example +@group +(let ((map (make-sparse-keymap))) + (set-keymap-parent map <theirmap>) + (define-key map ...) + ...) +@end group +@end 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 44335aded87..b27df1d0452 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. */) |