[Emacs-diffs] /srv/bzr/emacs/trunk r104423: Clarify Remapping Commands node in Lisp manual (Bug#8350).

[Chong Yidong]

------------------------------------------------------------
revno: 104423
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Sun 2011-05-29 15:00:00 -0400
message:
  Clarify Remapping Commands node in Lisp manual (Bug#8350).
  
  * keymaps.texi (Remapping Commands): Emphasize that the keymap
  needs to be active.
modified:
  doc/lispref/ChangeLog
  doc/lispref/keymaps.texi

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2011-05-28 19:58:43 +0000
+++ b/doc/lispref/ChangeLog     2011-05-29 19:00:00 +0000
@@ -1,3 +1,8 @@
+2011-05-29  Chong Yidong  <address@hidden>
+
+       * keymaps.texi (Remapping Commands): Emphasize that the keymap
+       needs to be active (Bug#8350).
+
 2011-05-28  Chong Yidong  <address@hidden>
 
        * minibuf.texi (Reading File Names): Clarify (Bug#8480).

=== modified file 'doc/lispref/keymaps.texi'
--- a/doc/lispref/keymaps.texi  2011-05-19 06:54:27 +0000
+++ b/doc/lispref/keymaps.texi  2011-05-29 19:00:00 +0000
@@ -1468,33 +1468,33 @@
 @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
address@hidden 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
address@hidden, which should be invoked instead of
address@hidden  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
address@hidden, Emacs will find the standard global binding of
address@hidden (assuming nobody has changed it).  But
address@hidden remaps @code{kill-line} to @code{my-kill-line},
-so instead of running @code{kill-line}, Emacs runs
address@hidden
address@hidden
+Then, whenever @code{my-mode-map} is active, if the user types
address@hidden (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 @@
 @end smallexample
 
 @noindent
-does not have the effect of remapping @code{kill-line} into
address@hidden  If an ordinary key binding specifies
address@hidden, 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}.
address@hidden 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
address@hidden, it is remapped to @code{my-other-kill-line}.
 
 To undo the remapping of a command, remap it to @code{nil}; e.g.