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

[Drew Adams]

> This information is displayed in different ways in different contexts.
> With this test case:
> 
> (keymap-local-set "C-c c" #'foo)
> (keymap-local-set "<remap> <foo>" #'bar)
> 
> (defun foo ()
>   (interactive)
>   "Call with \\[foo]."
>   (message "foo"))
> 
> (defun bar ()
>   (interactive)
>   "Call with \\[foo]."
>   (message "bar"))
> 
> C-h b (for instance) says
> 
> <remap> <foo> bar
> C-c c         foo
> 
> while C-h f foo RET says
> 
> Its keys are remapped to ‘bar’.  Without this remapping, it would be
> bound to C-c c.
> 
> I think the `C-h b' output could perhaps be reorganised, because bar
> and
> foo frequently are displayed far apart, so the person looking for the
> key for bar would have to look around.
> 
> We could, for instance, add an extra line here.
> 
> But did you have other contexts in mind?

1. Please reread the bug report.  It's specific about
   what behavior is requested - see below.

2. Please don't reply here using `keymap-*'.  If you
   want to communicate with me about key bindings,
   please use the standard, traditional functions.
   I don't have, and cannot use, Emacs 28, 29 etc.
   The bug/request was reported for Emacs 24.  It's
   still relevant, I believe.

Specific request, from the bug report - just please
modify `substitute-command' to add another arg that
provides for the behavior cited:

___
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.