RE: command remapping problem

[Drew Adams]

        In that case, I wonder (don't know) if it would necessitate
        any doc changes.
        IIRC, the doc now says something about using command
        remapping in preference
        to `substitute-key-definition'.

    Can you show us the precise text and say which source file it is in?

There may not be much that needs changing. This is all I could find:

1. Elisp manual node Changing Key Bindings -

 "The function `substitute-key-definition' scans a keymap for keys
 that have a certain binding and rebinds them with a different binding.
 Another feature you can use for similar effects, but which is often
 cleaner, is to add a binding that remaps a command (*note Remapping
 Commands::)."

That's not too bad. I'm not sure what is meant by "is often cleaner". Should
some "dirty" cases of using `substitute-key-definition' perhaps be pointed
out? If there is really an advantage "often", then why not point it out? If
the advantage is not performance or convenience but "cleanliness", then that
should be pointed out too - show a mess (problem) that can be created if you
use `substitute-key-definition'.

IOW, it would be good to communicate the relative advantages of each of
these two approaches in the manual. If the only advantage of
`substitute-key-definition' is the OLDMAP functionality, then we can
explicitly recommend using command remapping in all other cases. The
relative advantages are not yet clear to me. If you want people to use one
or the other, then it's good to give them the reasons.

2. At the end of the `substitute-key-definition' doc string:

 "For most uses, it is simpler and safer to use command remappping like
this:
  (define-key KEYMAP [remap OLDDEF] NEWDEF)"

It is worth mentioning the specific difference of command remapping not
supporting the OLDMAP functionality. This should be mentioned in the doc
string, rather than (just) in the Info intro, above. Also, I'm not sure that
"safer" is appropriate; if it is, whatever is unsafe should be documented.
Words like "cleaner" and "safer" don't mean much unless backed up by an
explanation of what is meant or an example.

Here's a suggestion for the last paragraph of the
`substitute-key-definition' doc string:

 If you do not need the effect of argument OLDMAP, then you can simply
 use command remapping instead of `substitute-key-definition'.
  (define-key KEYMAP [remap OLDDEF] NEWDEF)

HTH.