From 4a2092efd2ac76fce04a2587b360ed2ca1eac4d7 Mon Sep 17 00:00:00 2001 From: Stefan Monnier Date: Wed, 15 Jun 2016 11:36:51 -0400 Subject: [PATCH] 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 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 ) + (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 ) + (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. */) -- 2.39.2