Add command remapping, a more robust alternative to #'substitute-key-definition src/ChangeLog addition: 2012-09-02 Aidan Kehoe <kehoea@parhasard.net> * keymap.c: Add command remapping, a more robust equivalent to #'substitute-key-definition. * keymap.c (CHECK_REMAPPING_POSITION): New. * keymap.c (keymap_equal): Correct a comment here. * keymap.c (Fdefine_key): Document the command remapping syntax. * keymap.c (Fremap_command): New. * keymap.c (command_remapping): New. * keymap.c (Fcommand_remapping): New. * keymap.c (commands_remapped_to_mapper): New. * keymap.c (commands_remapped_to_traverser): New. * keymap.c (Fcommands_remapped_to): New. * keymap.c (get_relevant_keymaps): Take a new POSITION argument. * keymap.c (Fcurrent_keymaps, event_binding): Supply the new POSITION argument to get_relevant_keymaps. * keymap.c (Fkey_binding): Add new arguments, NO-REMAP and POSITION. * keymap.c (map_keymap_mapper): * keymap.c (Fwhere_is_internal): * keymap.c (where_is_to_char): * keymap.c (where_is_recursive_mapper): Don't expose the key remapping in these functions. This conflicts with GNU, but is more sane for our callers. Access to command remapping is with the functions #'command-remapping, #'commands-remapped-to, and #'remap-command, not with the general keymap functions, apart from the compatibility hack in #'define-key. * keymap.c (syms_of_keymap): * keymap.c (vars_of_keymap): * keymap.c (complex_vars_of_keymap): * lisp.h: New CHECK_COMMAND macro. man/ChangeLog addition: 2012-09-02 Aidan Kehoe <kehoea@parhasard.net> * lispref/keymaps.texi (Keymaps): * lispref/keymaps.texi (Changing Key Bindings): * lispref/keymaps.texi (Scanning Keymaps): * lispref/keymaps.texi (Remapping commands): * lispref/keymaps.texi (XEmacs): New. * lispref/keymaps.texi (Other Keymap Functions): Document the new command remapping functionality in this file. lisp/ChangeLog addition: 2012-09-02 Aidan Kehoe <kehoea@parhasard.net> * help.el (describe-function-1): Document any command remapping that has been done in this function. tests/ChangeLog addition: 2012-09-02 Aidan Kehoe <kehoea@parhasard.net> * automated/keymap-tests.el: Test the new command remapping functionality.

--- a/man/lispref/keymaps.texi	Sun Aug 12 11:32:36 2012 +0100
+++ b/man/lispref/keymaps.texi	Sun Sep 02 14:31:40 2012 +0100
@@ -33,6 +33,8 @@
 * Changing Key Bindings::    Redefining a key in a keymap.
 * Key Binding Commands::     Interactive interfaces for redefining keys.
 * Scanning Keymaps::         Looking through all keymaps, for printing help.
+* Remapping commands::       Specifying that one command should override
+                                another.
 * Other Keymap Functions::   Miscellaneous keymap functions.
 @end menu
 
@@ -1168,7 +1170,8 @@
 @var{olddef} is replaced with @var{newdef} wherever it appears.  Prefix
 keymaps are checked recursively.
 
-The function returns @code{nil}.
+The function returns @code{nil}.  @pxref{Remapping commands} for a more
+robust way of doing the same thing.
 
 For example, this redefines @kbd{C-x C-f}, if you do it in an XEmacs with
 standard bindings:
@@ -1581,6 +1584,37 @@
 displayed.
 @end deffn
 
+@node Remapping commands
+@section Remapping commands
+
+This section describes some functionality to allow commands to be
+remapped, e.g. when providing workalike commands.
+
+@defun remap-command keymap old new
+This function ensures that in @var{keymap} any command lookups that
+would previously have given @var{old} now give @var{new}.  This is
+equivalent to the following GNU-compatible code, which also works in
+XEmacs:
+
+@smallexample
+(define-key KEYMAP [remap OLD] NEW)
+@end smallexample
+@end defun
+
+@defun command-remapping command &optional position keymaps
+If @var{command} has a remapping in @var{keymaps}, this function returns
+that remapping.  Otherwise it returns @var{nil}.  @var{keymaps} defaults
+to the currently active keymaps. @var{position} specifies the relevant buffer
+position where keymaps should be searched for, and overrides
+@var{keymaps}.  It can also be a marker or an event.
+@end defun
+
+@defun commands-remapped-to command &optional position keymaps
+This is the inverse operation of @code{command-remapping}; it returns a
+list of the commands that will never be executed in @var{keymaps}
+because @var{command} will be execute instead.
+@end defun
+
 @node Other Keymap Functions
 @section Other Keymap Functions