Subject: 24.3.50; `substitute-command-keys': allow for expansion of <remap>...

From: "Drew Adams" <[email-masked]>
Date: Thu, 28 Mar 2013 22:17:02 -0700

In a particular mode, suppose code remaps a command, such as
`reposition-window', to a command `foo'.  `substitute-command-keys'
shows that fact only this way:
 
 <remap> <reposition-window>     foo
 
That can be good information to show users, provided the currently
active bindings of `reposition-window' are known to them.  If not, it
just obscures things.
 
And `substitute-command-keys' might be called from a particular mode
(and several minor modes might be current etc.), so that it might not be
accurate or sufficient for a user to resort to `M-x where-is
reposition-window' to try to find out what <remap> corresponds to in the
context of the call to `substitute-command-keys'.

Please add an optional arg to `substitute-command-keys' that changes the
behavior.  Please allow for these 3 possibilities:
 
1. Follow the current behavior (it could be the default): show only the
<remap> entry.
 
2. Show instead a key binding entry for each actual-key binding caused
by the remapping.  IOW, expand <remap> into one or more actual-key
bindings.  Handle remap of remap the same way.  IOW, the output would
not show any <remap> entries, but would show only their expansions.
 
3. Show both the <remap> entries and their expansions, i.e., #1 + #2.
 
4. Alternatively, the <remap> entries could be links/buttons that when
followed expand to actual-key bindings (in place, within the same
overall list of bindings).  One difference (advantage & disadvantage)
with this approach would be the order of the keys in the buffer.
 
Note that with the introduction of things like <remap> we are now
farther afield from the claimed behavior (and the intention) of
`substitute-command-keys':
 
  \[COMMAND] is replaced by either a keystroke sequence that
  invokes COMMAND, or "M-x COMMAND"
 
<remap>... is technically a "keystroke sequence" in one sense (it is a
key binding, at least), but in another sense it is not what the user
expects.  When <remap> was added we more or less just punted wrt
`substitute-command-keys' - we didn't really finish the job.

In GNU Emacs 24.3.50.1 (i386-mingw-nt5.1.2600)
 of 2013-03-23 on VBOX
Bzr revision: 112115 [email-masked]
Windowing system distributor `Microsoft Corp.', version 5.1.2600
Configured using:
 `configure --with-gcc (4.7) --no-opt --enable-checking --cflags
 -IC:/emacs/libs/libXpm-3.5.10/include -IC:/emacs/libs/libXpm-3.5.10/src
 -IC:/emacs/libs/libpng-dev_1.4.3-1_win32/include
 -IC:/emacs/libs/zlib-dev_1.2.5-2_win32/include
 -IC:/emacs/libs/giflib-4.1.4-1-lib/include
 -IC:/emacs/libs/jpeg-6b-4-lib/include
 -IC:/emacs/libs/tiff-3.8.2-1-lib/include
 -IC:/emacs/libs/libxml2-2.7.8-w32-bin/include/libxml2
 -IC:/emacs/libs/gnutls-3.1.10-w32/include
 -IC:/emacs/libs/libiconv-1.14-2-mingw32-dev/include'