doc string for command that is remapped

[Drew Adams]

`C-h f' for a command shows the key bindings (i.e. where-is info) at the top of
*Help*, immediately after "... is an interactive compiled Lisp function in...".
This is the first thing a user sees.

That's fine for actual key bindings; it shows you quick ways to invoke the
command, and that probably should be the first thing to read.

However, if you do `C-h f foo', and command `foo' is remapped to command `bar',
then you see this text instead, in the same place: "It is remapped to `bar',
which is bound to XXX."

That sounds a bit like it is describing merely an indirection: `foo' is
ultimately bound to XXX, but by way of `bar' (which is not true). The text is
correct, and useful, but someone unfamiliar with command remapping could easily
get the wrong impression that you can invoke `foo' by hitting XXX.

This text is not telling you a quick way to invoke command `foo' at all. If you
understand command remapping, then you know that it is telling you that `foo'
*cannot* be invoked using key sequence XXX, and that XXX instead invokes command
`bar'. That is probably what we should tell the user, explicitly.

I suggest we either change the text about remapping, to make this clearer, or we
move this text after the normal description of the command. (It is supplementary
information.)

If we leave the remapping statement where it is, how about changing it to
something like this:

  (The original binding of `foo' to XXX was remapped, so
  command `bar' is now bound to XXX.)

That makes it clear that (1) `foo' had XXX as binding previously, (2) `foo'
currently does not have that binding, and (3) `bar' has that binding now. This
is all just extra info (which is why it's in parens), but it is useful because
the implication is that you cannot use XXX to invoke `foo'.

That can be helpful because you might have thought otherwise: There is
presumably some context in which you could use XXX for `foo' (some other mode,
or vanilla Emacs vs use of some library). You might have known that `foo' was
bound to XXX, and not known about the remapping.

WDOT?

P.S. This same problem exists for command `where-is' (`C-h w') itself, of
course, but there the problem is not so bad. For `C-h f', the combination of (a)
putting the statement first in *Help* and (b) using a statement that could be
misinterpreted by some users is a double whammy.