From 1efc14561d6ec735cd35ac5e8124c4c244b1f1a2 Mon Sep 17 00:00:00 2001 From: Lars Ingebrigtsen Date: Mon, 29 Nov 2021 23:54:48 +0100 Subject: [PATCH] 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 581183a0a39..920d380266f 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 "" '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 0bdbc06013e..f37b35112af 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 1a9eb30fde1..71017a4d3db 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 d893e22b8b9..edf1d6e83fd 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 ) - (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{}, 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 " " '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 " " 'my-kill-line) +(keymap-set my-mode-map " " '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 " " 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 4d683da1ad3..ee119445e56 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 bc5c08c687c..69c022e5253 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 + "" #'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 863b318c205..25579e79eae 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 "" '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 "" + (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 1ae0e5e5ee1..abef0b3d0c6 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 -- 2.39.5