[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
master 1efc145: Edit the lispref manual for define-key/keymap-set fallou
From: |
Lars Ingebrigtsen |
Subject: |
master 1efc145: Edit the lispref manual for define-key/keymap-set fallout |
Date: |
Mon, 29 Nov 2021 17:55:05 -0500 (EST) |
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
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- master 1efc145: Edit the lispref manual for define-key/keymap-set fallout,
Lars Ingebrigtsen <=