*** empty log message ***

[gnu-emacs] / lispref / keymaps.texi

diff --git a/lispref/keymaps.texi b/lispref/keymaps.texi
index 63832ced1b4b4149774f6f0ba1d6aa61539031ca..895ca48109b3dffeb36aa8e8420e429a14d2cffd 100644 (file)
--- a/lispref/keymaps.texi
+++ b/lispref/keymaps.texi
@@ -257,18 +257,16 @@ satisfies @code{keymapp}.
 
   Here we describe the functions for creating keymaps.
 
-@c ??? This should come after make-sparse-keymap
-@defun make-keymap &optional prompt
-This function creates and returns a new full keymap.  That keymap
-contains a char-table (@pxref{Char-Tables}) with slots for all
-characters without modifiers.  The new keymap initially binds all
-these characters to @code{nil}, and does not bind any other kind of
-event.
+@defun make-sparse-keymap &optional prompt
+This function creates and returns a new sparse keymap with no entries.
+(A sparse keymap is the kind of keymap you usually want.)  The new
+keymap does not contain a char-table, unlike @code{make-keymap}, and
+does not bind any events.
 
 @example
 @group
-(make-keymap)
-    @result{} (keymap #^[t nil nil nil @dots{} nil nil keymap])
+(make-sparse-keymap)
+    @result{} (keymap)
 @end group
 @end example
 
@@ -277,18 +275,23 @@ the keymap.  The prompt string should be provided for menu keymaps
 (@pxref{Defining Menus}).
 @end defun
 
-@defun make-sparse-keymap &optional prompt
-This function creates and returns a new sparse keymap with no entries.
-The new keymap does not contain a char-table, unlike @code{make-keymap},
-and does not bind any events.  The argument @var{prompt} specifies a
-prompt string, as in @code{make-keymap}.
+@defun make-keymap &optional prompt
+This function creates and returns a new full keymap.  That keymap
+contains a char-table (@pxref{Char-Tables}) with slots for all
+characters without modifiers.  The new keymap initially binds all
+these characters to @code{nil}, and does not bind any other kind of
+event.  The argument @var{prompt} specifies a
+prompt string, as in @code{make-sparse-keymap}.
 
 @example
 @group
-(make-sparse-keymap)
-    @result{} (keymap)
+(make-keymap)
+    @result{} (keymap #^[t nil nil nil @dots{} nil nil keymap])
 @end group
 @end example
+
+A full keymap is more efficient than a sparse keymap when it holds
+lots of bindings; for just a few, the sparse keymap is better.
 @end defun
 
 @defun copy-keymap keymap
@@ -1335,10 +1338,10 @@ a key binding.
 instead of @code{kill-line} and @code{kill-word}.  It can establish
 this by making these two command-remapping bindings in its keymap:
 
-@example
+@smallexample
 (define-key my-mode-map [remap kill-line] 'my-kill-line)
 (define-key my-mode-map [remap kill-word] 'my-kill-word)
-@end example
+@end smallexample
 
 Whenever @code{my-mode-map} is an active keymap, if the user types
 @kbd{C-k}, Emacs will find the standard global binding of
@@ -1349,10 +1352,10 @@ so instead of running @code{kill-line}, Emacs runs
 
 Remapping only works through a single level.  In other words,
 
-@example
+@smallexample
 (define-key my-mode-map [remap kill-line] 'my-kill-line)
 (define-key my-mode-map [remap my-kill-line] 'my-other-kill-line)
-@end example
+@end smallexample
 
 @noindent
 does not have the effect of remapping @code{kill-line} into
@@ -1435,15 +1438,15 @@ input.  One way to do this is by using an appropriate input method
 construct the key sequence string using @code{multibyte-char-to-unibyte}
 or @code{string-make-unibyte} (@pxref{Converting Representations}).
 
-@deffn Command global-set-key key definition
+@deffn Command global-set-key key binding
 This function sets the binding of @var{key} in the current global map
-to @var{definition}.
+to @var{binding}.
 
 @smallexample
 @group
-(global-set-key @var{key} @var{definition})
+(global-set-key @var{key} @var{binding})
 @equiv{}
-(define-key (current-global-map) @var{key} @var{definition})
+(define-key (current-global-map) @var{key} @var{binding})
 @end group
 @end smallexample
 @end deffn
@@ -1479,15 +1482,15 @@ This function is implemented simply using @code{define-key}:
 @end smallexample
 @end deffn
 
-@deffn Command local-set-key key definition
+@deffn Command local-set-key key binding
 This function sets the binding of @var{key} in the current local
-keymap to @var{definition}.
+keymap to @var{binding}.
 
 @smallexample
 @group
-(local-set-key @var{key} @var{definition})
+(local-set-key @var{key} @var{binding})
 @equiv{}
-(define-key (current-local-map) @var{key} @var{definition})
+(define-key (current-local-map) @var{key} @var{binding})
 @end group
 @end smallexample
 @end deffn