bug#30530: 26.0; Emacs manual: mention (1) user-reserved keys, (2) users can bind any keys

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

> > Following up on the request by Nicolas Goaziou in bug #28263, please
> > consider adding some information about the keys that users can bind.
> 
> I'm sorry, but I really don't understand the issue here, and I would
> prefer not to re-read the long discussion in that bug report (and
> expect not to be any wiser if I did).  Can someone please summarize
> the issue at hand?
> 
> > 1. Say that Emacs and 3rd-party Lisp libraries often bind keys, but that
> >    some keys are specifically reserved, by convention, for users.  Point
> >    out which keys are reserved for users.
> 
> Users can bind _any_ keys, as you yourself say:

But some users do not know that.  Telling them that explicitly
in the Emacs manual can help make it clear.

> > 2. Make it clear that users can, in any case, bind ANY keys they want;
> >    they are not limited to binding user-reserved keys.  In particular,
> >    users can rebind keys that Emacs or some 3rd-party library has already
> >    bound.
> 
> Given this, what good will it do to say something about keys reserved
> for users in the user manual?  Lisp developers should know that, which
> is why it is in the ELisp manual.

Some users do not know that these are the "safest" keys to bind,
because they are reserved for users.  Knowing that can help them
by focusing them on those keys, which are less likely to be in
conflict with libraries.

> > 3. State that after a user has bound a key, evaluating some Emacs code
> >    (including loading a Lisp library) might rebind that key if it is not
> >    reserved for users.  This is the reason some keys are reserved for
> >    users: to prevent the bother of some non-user code overriding user
> >    key bindings.
> 
> How would this help users?  What would they do to avoid that?

It's not about avoiding it.  It's about making users aware of
how it works.  They can act with more confidence and less
confusion if they know that some keys are reserved for them
and other keys they might bind risk being overridden by
loading a library or turning on a mode.  Less surprise and
pondering "WTF is going on?".

> Bottom line, I don't really understand the issue you are asking to be
> solved.

Did you check bug #28263?

> The bug report is phrased as a list of instructions to be
> executed, but that's not how bug reporting should work -- you should
> describe the problem itself as well.

The problem is that users do not necessarily have a good idea
what keys they can bind (answer: any keys) and which keys
Lisp libraries are likely to bind (answer: keys not reserved 
or users).  Users have been known to ask about such things.

Stating clearly in the Emacs manual what the case is in this
regard can help users - see above.

If you still do not get it, and you still do not want to look
at bug #28263, then feel free to close this bug.

This bug report doesn't ask for a lot.  It would be enough to
state these two things in the Emacs manual:

1. That some keys are reserved for users, so that if you bind
those there is little chance that if you later load some
library or turn on a mode you will seem to lose those bindings
you made.

2. You can nevertheless bind any keys.  Just be aware of #1,
so you are not surprised if some non-reserved key you have
bound seems to have somehow later become co-opted.

The keys that are reserved for users could be listed/described,
or the Emacs manual could just link to their description in
the Elisp manual.  Users should have _some_ easy way of knowing
which keys are reserved for their use.