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

From: Drew Adams <[email-masked]>
Date: Fri, 2 Mar 2018 07:17:14 -0800 (PST)

> > > > The Emacs doc makes clear that these keys are reserved for users.
> > >
> > > Being reserved means that users can bind them.
> >
> > You keep repeating that, but it has never been in question.
> 
> You are questioning that, by insisting that no document can
> suggest binding those keys.

Not at all.  It is fine for the Emacs and Elisp manuals to
point out that users can bind these keys and that the keys
are reserved for them.

That's in fact the point of this bug report: to make that
message even more clear than it has been, by bringing it
to the attention of readers of the Emacs manual.

It is a message not just for library writers (which is
why it is in the Elisp manual).  It is a message for
end users - it's about keys reserved for _them_ (so it
belongs also in the Emacs manual).

Same goes for blogs and other documents.  Same also for
the doc of a library.  Reminding users that these keys
are reserved for their use - however they might want to
bind them - is _always_ a good thing.

That's not the same thing as the doc of a library that
most Emacs users use, and that is often the gateway to
starting to use Emacs, telling users that they should
bind these keys _for that library_, for best results.

That is tantamount to the Emacs manual or tutorial
telling users that these keys are reserved for users
(good) BUT that Emacs recommends that they bind some
of them to Org commands (bad).  That's misleading,
confusing, and not helpful, IMO.

And there's no need for it.  It is enough for any doc,
including the Org doc, to simply remind users that
they can bind any of these keys without worry that
some library will change them.

We should not start Emacs users off with a suggestion
that they bind such keys for Org (or anything else).

Or if we really think (I don't) that that's the way
to start using Emacs then Org should bind those keys
by default.  In that case, there would be no pretense
of reserving them.  (Users could still, of course,
bind them.)

Either the keys are reserved for users or they are
not.  IMHO, the _single_ message about these keys
from Emacs to users (especially new users) should
be the message that these keys are reserved for
their use.  End of story.

That message should not be diluted and confused
by a second message that for best results you are
nevertheless encouraged to bind many such keys to
Org commands.