bug#23236: 25.0.90; Document command remapping in Emacs manual, not just Elisp manual

[Drew Adams <drew.adams@oracle.com>]

> > Search the Emacs manual for "remap".  You will find nothing about
> > command remapping.
> 
> Because it's not a user-level feature.

I disagree.  Why do you say it is not?  Are users not supposed to
remap commands?  If they are, then what could you possibly mean
by saying that doing so is not "user-level"?

Until Emacs provides an easy Customize interface for customizing
key bindings, users will use `define-key' and `global-set-key'
to customize key bindings.  They always have, and they still must.

> > (global-set-key [remap foo] 'bar) is something that _users_ do.
> > Likewise (define-key some-map [remap foo] 'bar).
> 
> It doesn't matter who does it.  What matters is that these are Lisp
> expressions, and those are usually documented in the ELisp manuals.

I have no problem with them being documented in the Elisp manual.
This bug does not request that they be removed from the Elisp manual.

I think they - at least their existence - should also be documented
in the Emacs manual.  It may be enough to point users (from the
Emacs manual) to the Elisp manual.

But certainly users reading the Emacs manual should be able to find
the answers to questions about _how to customize_ key bindings.
And that includes command remapping.

Binding keys is an extremely common end-user task.  (Yes, it is.
It is 100% "user-level", in addition to being something that is
done in non-user files.)

Not pointing end users, in the Emacs manual, to the information
about _how they do this_ is a cop-out, I think.  They will find
that pointer only by googling etc.  The Emacs manual should be
their friend in this regard, by pointing them to the info they
need to get the job done, whether or not the details of that
info might be in the Elisp manual.

If users need to use Lisp to customize key bindings, then so be
it.  And if they therefore need to read some of the Elisp manual,
to learn how to do that, so be it.

But the _fact_ that they _can_ do it, and the _fact_ that info
about _how_ to do it is in the Elisp manual, should be in the
Emacs manual.  At a minimum.

* You can bind keys to commands of your choosing.
  See (elisp) XXXX.

* You can remap a command A to another command B's key bindings,
  so that using any of those keys invokes command A instead of
  command B.  See (elisp) YYYY.

> global-set-key is only documented in the user manual as a command, not
> as a function.  We only show a few examples of using it as a function.
> 
> > This is not something that is only for Elisp code.
> 
> I think it is.

It is not something that is only for Lisp libraries.  Is that
clearer for you?  It is something that is in thousands of end-user
init files, including users who otherwise know little or nothing
about Lisp.

If you really think that using `define-key' and `global-set-key'
in an end-user init file is inappropriate then please provide a
Customize replacement for `define-key' and `global-set-key'
immediately, and then update the Emacs manual to tell users how
to customize key bindings using Customize.

Until then, users have only `define-key' and `global-set-key' for
key customization.  The Emacs manual should help them in this
regard.  It should not be silent on command remapping.