master 1efc145: Edit the lispref manual for define-key/keymap-set fallout

[Lars Ingebrigtsen]

branch: master
commit 1efc14561d6ec735cd35ac5e8124c4c244b1f1a2
Author: Lars Ingebrigtsen <larsi@gnus.org>
Commit: Lars Ingebrigtsen <larsi@gnus.org>

    Edit the lispref manual for define-key/keymap-set fallout
    
    * doc/lispref/variables.texi (Tips for Defining):
    * doc/lispref/text.texi (Clickable Text):
    * doc/lispref/modes.texi (Derived Modes):
    (Example Major Modes):
    * doc/lispref/loading.texi (Autoload):
    (Hooks for Loading):
    * doc/lispref/keymaps.texi (Creating Keymaps):
    (Inheritance and Keymaps):
    (Controlling Active Maps):
    (Changing Key Bindings):
    (Low-Level Key Binding):
    (Remapping Commands):
    (Translation Keymaps):
    (Key Binding Commands):
    * doc/lispref/help.texi (Help Functions):
    * doc/lispref/display.texi (Abstract Display Example):
    * doc/lispref/commands.texi (Interactive Codes):
    (Keyboard Events):
    (Misc Events):
    (Classifying Events):
    (Strings of Events): Prefer `keymap-set' instead of `define-key'
    most places, and use `defvar-keymap' in some of the examples.
---
 doc/lispref/commands.texi  | 55 +++++++++++-----------------------------------
 doc/lispref/display.texi   | 18 +++++++--------
 doc/lispref/help.texi      |  2 +-
 doc/lispref/keymaps.texi   | 39 ++++++++++++++++++++++----------
 doc/lispref/loading.texi   |  4 ++--
 doc/lispref/modes.texi     | 42 ++++++++++++++---------------------
 doc/lispref/text.texi      |  8 +++----
 doc/lispref/variables.texi | 21 +-----------------
 8 files changed, 72 insertions(+), 117 deletions(-)

diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi
index 581183a..920d380 100644
--- a/doc/lispref/commands.texi
+++ b/doc/lispref/commands.texi
@@ -455,7 +455,7 @@ This kind of input is used by commands such as 
@code{describe-key} and
 
 @item K
 A key sequence on a form that can be used as input to functions like
-@code{define-key}.  This works like @samp{k}, except that it
+@code{keymap-set}.  This works like @samp{k}, except that it
 suppresses, for the last input event in the key sequence, the
 conversions that are normally used (when necessary) to convert an
 undefined key into a defined one (@pxref{Key Sequence Input}), so this
@@ -1315,12 +1315,9 @@ actually treated as the meta key, not this.)
   It is best to avoid mentioning specific bit numbers in your program.
 To test the modifier bits of a character, use the function
 @code{event-modifiers} (@pxref{Classifying Events}).  When making key
-bindings, you can use the read syntax for characters with modifier bits
-(@samp{\C-}, @samp{\M-}, and so on).  For making key bindings with
-@code{define-key}, you can use lists such as @code{(control hyper ?x)} to
-specify the characters (@pxref{Changing Key Bindings}).  The function
-@code{event-convert-list} converts such a list into an event type
-(@pxref{Classifying Events}).
+bindings with @code{keymap-set}, you specify these events using
+strings like @samp{C-H-x} instead (for ``control hyper x'')
+(@pxref{Changing Key Bindings}).
 
 @node Function Keys
 @subsection Function Keys
@@ -2078,7 +2075,7 @@ example:
   (interactive)
   (message "Caught signal %S" last-input-event))
 
-(define-key special-event-map [sigusr1] 'sigusr-handler)
+(keymap-set special-event-map "<sigusr1>" 'sigusr-handler)
 @end smallexample
 
 To test the signal handler, you can make Emacs send a signal to itself:
@@ -2284,21 +2281,6 @@ This function returns non-@code{nil} if @var{object} is 
a mouse movement
 event.  @xref{Motion Events}.
 @end defun
 
-@defun event-convert-list list
-This function converts a list of modifier names and a basic event type
-to an event type which specifies all of them.  The basic event type
-must be the last element of the list.  For example,
-
-@example
-(event-convert-list '(control ?a))
-     @result{} 1
-(event-convert-list '(control meta ?a))
-     @result{} -134217727
-(event-convert-list '(control super f1))
-     @result{} C-s-f1
-@end example
-@end defun
-
 @node Accessing Mouse
 @subsection Accessing Mouse Events
 @cindex mouse events, data in
@@ -2518,25 +2500,14 @@ characters in a string is a complex matter, for reasons 
of historical
 compatibility, and it is not always possible.
 
   We recommend that new programs avoid dealing with these complexities
-by not storing keyboard events in strings.  Here is how to do that:
-
-@itemize @bullet
-@item
-Use vectors instead of strings for key sequences, when you plan to use
-them for anything other than as arguments to @code{lookup-key} and
-@code{define-key}.  For example, you can use
-@code{read-key-sequence-vector} instead of @code{read-key-sequence}, and
-@code{this-command-keys-vector} instead of @code{this-command-keys}.
-
-@item
-Use vectors to write key sequence constants containing meta characters,
-even when passing them directly to @code{define-key}.
-
-@item
-When you have to look at the contents of a key sequence that might be a
-string, use @code{listify-key-sequence} (@pxref{Event Input Misc})
-first, to convert it to a list.
-@end itemize
+by not storing keyboard events in strings containing control
+characters or the like, but instead store them in the common Emacs
+format as understood by @code{key-valid-p}.
+
+  If you read a key sequence with @code{read-key-sequence-vector} (or
+@code{read-key-sequence}), or access a key sequence with
+@code{this-command-keys-vector} (or @code{this-command-keys}), you can
+transform this to the recommended format by using @code{key-description}.
 
   The complexities stem from the modifier bits that keyboard input
 characters can include.  Aside from the Meta modifier, none of these
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 0bdbc06..f37b351 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -7777,16 +7777,14 @@ The string is formatted #RRGGBB (hash followed by six 
hex digits)."
   (kill-buffer nil))
 
 (setq colorcomp-mode-map
-      (let ((m (make-sparse-keymap)))
-        (suppress-keymap m)
-        (define-key m "i" 'colorcomp-R-less)
-        (define-key m "o" 'colorcomp-R-more)
-        (define-key m "k" 'colorcomp-G-less)
-        (define-key m "l" 'colorcomp-G-more)
-        (define-key m "," 'colorcomp-B-less)
-        (define-key m "." 'colorcomp-B-more)
-        (define-key m " " 'colorcomp-copy-as-kill-and-exit)
-        m))
+      (define-keymap :suppress t
+        "i" 'colorcomp-R-less
+        "o" 'colorcomp-R-more
+        "k" 'colorcomp-G-less
+        "l" 'colorcomp-G-more
+        "," 'colorcomp-B-less
+        "." 'colorcomp-B-more
+        "SPC" 'colorcomp-copy-as-kill-and-exit))
 @end smallexample
 
 Note that we never modify the data in each node, which is fixed when the
diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi
index 1a9eb30..71017a4 100644
--- a/doc/lispref/help.texi
+++ b/doc/lispref/help.texi
@@ -647,7 +647,7 @@ follows:
 
 @smallexample
 @group
-(define-key global-map (string help-char) 'help-command)
+(keymap-set global-map (key-description (string help-char)) 'help-command)
 (fset 'help-command help-map)
 @end group
 @end smallexample
diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi
index d893e22..edf1d6e 100644
--- a/doc/lispref/keymaps.texi
+++ b/doc/lispref/keymaps.texi
@@ -367,7 +367,7 @@ I.e., something like:
 @group
 (let ((map (make-sparse-keymap)))
   (set-keymap-parent map <theirmap>)
-  (define-key map ...)
+  (keymap-set map ...)
   ...)
 @end group
 @end example
@@ -420,10 +420,10 @@ The effect is that this keymap inherits all the bindings 
of
 but can add to them or override them with @var{elements}.
 
 If you change the bindings in @var{parent-keymap} using
-@code{define-key} or other key-binding functions, these changed
+@code{keymap-set} or other key-binding functions, these changed
 bindings are visible in the inheriting keymap, unless shadowed by the
 bindings made by @var{elements}.  The converse is not true: if you use
-@code{define-key} to change bindings in the inheriting keymap, these
+@code{keymap-set} to change bindings in the inheriting keymap, these
 changes are recorded in @var{elements}, but have no effect on
 @var{parent-keymap}.
 
@@ -797,7 +797,7 @@ out with.
 This function returns the current global keymap.  This is the same as
 the value of @code{global-map} unless you change one or the other.
 The return value is a reference, not a copy; if you use
-@code{define-key} or other functions on it you will alter global
+@code{keymap-set} or other functions on it you will alter global
 bindings.
 
 @example
@@ -833,7 +833,7 @@ keymap.
 @end defun
 
 @code{current-local-map} returns a reference to the local keymap, not
-a copy of it; if you use @code{define-key} or other functions on it
+a copy of it; if you use @code{keymap-set} or other functions on it
 you will alter local bindings.
 
 @defun current-minor-mode-maps
@@ -1297,7 +1297,7 @@ This function sets the binding for @var{key} in 
@var{keymap}.  (If
 in another keymap reached from @var{keymap}.)  The argument
 @var{binding} can be any Lisp object, but only certain types are
 meaningful.  (For a list of meaningful types, see @ref{Key Lookup}.)
-The value returned by @code{define-key} is @var{binding}.
+The value returned by @code{keymap-set} is @var{binding}.
 
 If @var{key} is @kbd{<t>}, this sets the default binding in
 @var{keymap}.  When an event has no binding of its own, the Emacs
@@ -1726,6 +1726,21 @@ The argument @var{accept-defaults} controls checking for 
default bindings,
 as in @code{lookup-key} (above).
 @end defun
 
+@defun event-convert-list list
+This function converts a list of modifier names and a basic event type
+to an event type which specifies all of them.  The basic event type
+must be the last element of the list.  For example,
+
+@example
+(event-convert-list '(control ?a))
+     @result{} 1
+(event-convert-list '(control meta ?a))
+     @result{} -134217727
+(event-convert-list '(control super f1))
+     @result{} C-s-f1
+@end example
+@end defun
+
 @node Remapping Commands
 @section Remapping Commands
 @cindex remapping commands
@@ -1744,7 +1759,7 @@ definition for a key binding).
 the following remapping:
 
 @smallexample
-(define-key my-mode-map [remap kill-line] 'my-kill-line)
+(keymap-set my-mode-map "<remap> <kill-line>" 'my-kill-line)
 @end smallexample
 
 @noindent
@@ -1759,8 +1774,8 @@ In addition, remapping only works through a single level; 
in the
 following 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)
+(keymap-set my-mode-map "<remap> <kill-line>" 'my-kill-line)
+(keymap-set my-mode-map "<remap> <my-kill-line>" 'my-other-kill-line)
 @end smallexample
 
 @noindent
@@ -1772,7 +1787,7 @@ remapped to @code{my-kill-line}; if an ordinary binding 
specifies
 To undo the remapping of a command, remap it to @code{nil}; e.g.,
 
 @smallexample
-(define-key my-mode-map [remap kill-line] nil)
+(keymap-set my-mode-map "<remap> <kill-line>" nil)
 @end smallexample
 
 @defun command-remapping command &optional position keymaps
@@ -1904,7 +1919,7 @@ to turn the character that follows into a Hyper character:
         symbol
       (cons symbol (cdr e)))))
 
-(define-key local-function-key-map "\C-ch" 'hyperify)
+(keymap-set local-function-key-map "C-c h" 'hyperify)
 @end group
 @end example
 
@@ -1934,7 +1949,7 @@ problematic suffixes/prefixes are @kbd{@key{ESC}}, 
@kbd{M-O} (which is really
 @section Commands for Binding Keys
 
   This section describes some convenient interactive interfaces for
-changing key bindings.  They work by calling @code{define-key}.
+changing key bindings.  They work by calling @code{keymap-set}.
 
   People often use @code{keymap-global-set} in their init files
 (@pxref{Init File}) for simple customization.  For example,
diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi
index 4d683da..ee11944 100644
--- a/doc/lispref/loading.texi
+++ b/doc/lispref/loading.texi
@@ -552,7 +552,7 @@ An autoloaded keymap loads automatically during key lookup 
when a prefix
 key's binding is the symbol @var{function}.  Autoloading does not occur
 for other kinds of access to the keymap.  In particular, it does not
 happen when a Lisp program gets the keymap from the value of a variable
-and calls @code{define-key}; not even if the variable name is the same
+and calls @code{keymap-set}; not even if the variable name is the same
 symbol @var{function}.
 
 @cindex function cell in autoload
@@ -1156,7 +1156,7 @@ You don't need to give a directory or extension in the 
file name
 @var{library}.  Normally, you just give a bare file name, like this:
 
 @example
-(with-eval-after-load "js" (define-key js-mode-map "\C-c\C-c" 'js-eval))
+(with-eval-after-load "js" (keymap-set js-mode-map "C-c C-c" 'js-eval))
 @end example
 
 To restrict which files can trigger the evaluation, include a
diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index bc5c08c..69c022e 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -916,10 +916,8 @@ which in turn may have been changed in a mode hook.
 Here is a hypothetical example:
 
 @example
-(defvar hypertext-mode-map
-  (let ((map (make-sparse-keymap)))
-    (define-key map [down-mouse-3] 'do-hyper-link)
-    map))
+(defvar-keymap hypertext-mode-map
+  "<down-mouse-3>" #'do-hyper-link)
 
 (define-derived-mode hypertext-mode
   text-mode "Hypertext"
@@ -1344,11 +1342,9 @@ the conventions listed above:
 
 ;; @r{Create the keymap for this mode.}
 @group
-(defvar text-mode-map
-  (let ((map (make-sparse-keymap)))
-    (define-key map "\e\t" 'ispell-complete-word)
-    @dots{}
-    map)
+(defvar-keymap text-mode-map
+  "C-M-i" #'ispell-complete-word
+  @dots{})
   "Keymap for `text-mode'.
 Many other modes, such as `mail-mode', `outline-mode' and
 `indented-text-mode', inherit all the commands defined in this map.")
@@ -1421,13 +1417,11 @@ common.  The following code sets up the common commands:
 
 @smallexample
 @group
-(defvar lisp-mode-shared-map
-  (let ((map (make-sparse-keymap)))
-    (set-keymap-parent map prog-mode-map)
-    (define-key map "\e\C-q" 'indent-sexp)
-    (define-key map "\177" 'backward-delete-char-untabify)
-    map)
-  "Keymap for commands shared by all sorts of Lisp modes.")
+(defvar-keymap lisp-mode-shared-map
+  :parent prog-mode-map
+  :doc "Keymap for commands shared by all sorts of Lisp modes."
+  "C-M-q" #'indent-sexp
+  "DEL" #'backward-delete-char-untabify)
 @end group
 @end smallexample
 
@@ -1436,16 +1430,12 @@ And here is the code to set up the keymap for Lisp mode:
 
 @smallexample
 @group
-(defvar lisp-mode-map
-  (let ((map (make-sparse-keymap))
-        (menu-map (make-sparse-keymap "Lisp")))
-    (set-keymap-parent map lisp-mode-shared-map)
-    (define-key map "\e\C-x" 'lisp-eval-defun)
-    (define-key map "\C-c\C-z" 'run-lisp)
-    @dots{}
-    map)
-  "Keymap for ordinary Lisp mode.
-All commands in `lisp-mode-shared-map' are inherited by this map.")
+(defvar-keymap lisp-mode-map
+  :doc "Keymap for ordinary Lisp mode.
+All commands in `lisp-mode-shared-map' are inherited by this map."
+  :parent lisp-mode-shared-map
+  "C-M-x" #'lisp-eval-defun
+  "C-c C-z" #'run-lisp)
 @end group
 @end smallexample
 
diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index 863b318..25579e7 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -4195,7 +4195,7 @@ position.  The action code is always @code{t}.
 For example, here is how Info mode handles @key{mouse-1}:
 
 @smallexample
-(define-key Info-mode-map [follow-link] 'mouse-face)
+(keymap-set Info-mode-map "<follow-link>" 'mouse-face)
 @end smallexample
 
 @item a function
@@ -4208,9 +4208,9 @@ For example, here is how pcvs enables @kbd{mouse-1} to 
follow links on
 file names only:
 
 @smallexample
-(define-key map [follow-link]
-  (lambda (pos)
-    (eq (get-char-property pos 'face) 'cvs-filename-face)))
+(keymap-set map "<follow-link>"
+            (lambda (pos)
+              (eq (get-char-property pos 'face) 'cvs-filename-face)))
 @end smallexample
 
 @item anything else
diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi
index 1ae0e5e..abef0b3 100644
--- a/doc/lispref/variables.texi
+++ b/doc/lispref/variables.texi
@@ -686,7 +686,7 @@ entire computation of the value into the @code{defvar}, 
like this:
 @example
 (defvar my-mode-map
   (let ((map (make-sparse-keymap)))
-    (define-key map "\C-c\C-a" 'my-command)
+    (keymap-set map "C-c C-a" 'my-command)
     @dots{}
     map)
   @var{docstring})
@@ -702,25 +702,6 @@ important if the user has run hooks to alter part of the 
contents
 (such as, to rebind keys).  Third, evaluating the @code{defvar} form
 with @kbd{C-M-x} will reinitialize the map completely.
 
-  Putting so much code in the @code{defvar} form has one disadvantage:
-it puts the documentation string far away from the line which names the
-variable.  Here's a safe way to avoid that:
-
-@example
-(defvar my-mode-map nil
-  @var{docstring})
-(unless my-mode-map
-  (let ((map (make-sparse-keymap)))
-    (define-key map "\C-c\C-a" 'my-command)
-    @dots{}
-    (setq my-mode-map map)))
-@end example
-
-@noindent
-This has all the same advantages as putting the initialization inside
-the @code{defvar}, except that you must type @kbd{C-M-x} twice, once on
-each form, if you do want to reinitialize the variable.
-
 @node Accessing Variables
 @section Accessing Variable Values