mirror/emacs
1
0
Fork 0
mirror of https://git.savannah.gnu.org/git/emacs.git synced 2025-01-15 17:00:26 +00:00
Code Issues Releases Activity

Clarify Remapping Commands node in Lisp manual (Bug#8350).

Browse Source 
* keymaps.texi (Remapping Commands): Emphasize that the keymap
needs to be active.
This commit is contained in:
Chong Yidong 2011-05-29 15:00:00 -04:00
parent d66c4c7ce6
commit 58539c631a
2 changed files with 29 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
doc/lispref/ChangeLog
View File

@ -1,3 +1,8 @@
2011-05-29 Chong Yidong <cyd@stupidchicken.com>
* keymaps.texi (Remapping Commands): Emphasize that the keymap
needs to be active (Bug#8350).
2011-05-28 Chong Yidong <cyd@stupidchicken.com>
* minibuf.texi (Reading File Names): Clarify (Bug#8480).

49
doc/lispref/keymaps.texi
View File

@ -1468,33 +1468,33 @@ Dired mode is set up:
@section Remapping Commands
@cindex remapping commands
A special kind of key binding, using a special ``key sequence''
which includes a command name, has the effect of @dfn{remapping} that
command into another. Here's how it works. You make a key binding
for a key sequence that starts with the dummy event @code{remap},
followed by the command name you want to remap. Specify the remapped
definition as the definition in this binding. The remapped definition
is usually a command name, but it can be any valid definition for
a key binding.
A special kind of key binding can be used to @dfn{remap} one command
to another, without having to refer to the key sequence(s) bound to
the original command. To use this feature, make a key binding for a
key sequence that starts with the dummy event @code{remap}, followed
by the command name you want to remap; for the binding, specify the
new definition (usually a command name, but possibly any other valid
definition for a key binding).
Here's an example. Suppose that My mode uses special commands
@code{my-kill-line} and @code{my-kill-word}, which should be invoked
instead of @code{kill-line} and @code{kill-word}. It can establish
this by making these two command-remapping bindings in its keymap:
For example, suppose My mode provides a special command
@code{my-kill-line}, which should be invoked instead of
@code{kill-line}. To establish this, its mode keymap should contain
the following remapping:
@smallexample
(define-key my-mode-map [remap kill-line] 'my-kill-line)
(define-key my-mode-map [remap kill-word] 'my-kill-word)
@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
@code{kill-line} (assuming nobody has changed it). But
@code{my-mode-map} remaps @code{kill-line} to @code{my-kill-line},
so instead of running @code{kill-line}, Emacs runs
@code{my-kill-line}.
@noindent
Then, whenever @code{my-mode-map} is active, if the user types
@kbd{C-k} (the default global key sequence for @code{kill-line}) Emacs
will instead run @code{my-kill-line}.
Remapping only works through a single level. In other words,
Note that remapping only takes place through active keymaps; for
example, putting a remapping in a prefix keymap like @code{ctl-x-map}
typically has no effect, as such keymaps are not themselves active.
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)
@ -1502,11 +1502,10 @@ Remapping only works through a single level. In other words,
@end smallexample
@noindent
does not have the effect of remapping @code{kill-line} into
@code{my-other-kill-line}. If an ordinary key binding specifies
@code{kill-line}, this keymap will remap it to @code{my-kill-line};
if an ordinary binding specifies @code{my-kill-line}, this keymap will
remap it to @code{my-other-kill-line}.
@code{kill-line} is @emph{not} remapped to @code{my-other-kill-line}.
Instead, if an ordinary key binding specifies @code{kill-line}, it is
remapped to @code{my-kill-line}; if an ordinary binding specifies
@code{my-kill-line}, it is remapped to @code{my-other-kill-line}.
To undo the remapping of a command, remap it to @code{nil}; e.g.