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

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

[Drew Adams]

Following up on the request by Nicolas Goaziou in bug #28263, please
consider adding some information about the keys that users can bind.

Please:

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.

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.

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.

The keys reserved for users are currently specified only in the Elisp
manual (node `Key Binding Conventions').  Please consider adding a link
to that node from wherever the user-reserved keys will be called out in
the Emacs manual.

A likely location in the Emacs manual for such info would be somewhere
under node `Customizing Key Bindings'.

In GNU Emacs 26.0.91 (build 1, x86_64-w64-mingw32)
 of 2018-01-22
Repository revision: 752fba992b793a74d202c9cfc3e1a92fd458e748
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static -g3''

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

[Eli Zaretskii]

> Date: Mon, 19 Feb 2018 08:16:09 -0800 (PST)
> From: 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:

> 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 i tis in the ELisp manual.

> 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?

Bottom line, I don't really understand the issue you are asking to be
solved.  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.

Thanks.

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

[Drew Adams]

> > 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.

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

[Eli Zaretskii]

> Date: Sat, 24 Feb 2018 09:00:51 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 30530@debbugs.gnu.org
> 
> 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.

I added some text about the latter, although I seriously doubt that it
will be discoverable enough to make any difference.

As for the former, the manual is full of examples using all kinds of
keys in bindings (only one of them is from the reserved area, btw), so
it should be pretty clear that there are limitations on that.

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

[Nicolas Goaziou]

Hello,

Eli Zaretskii <eliz@gnu.org> writes:

> I added some text about the latter, although I seriously doubt that it
> will be discoverable enough to make any difference.

Thank you. 

For good measure, could you also add a @cindex about it? E.g,

  @cindex user reserved key bindings

For reference, this bug report stems from the following part of the Org
manual:

    For a better experience, the three Org commands ~org-store-link~,
    ~org-capture~ and ~org-agenda~ ought to be accessible anywhere in
    Emacs, not just in Org buffers.  To that effect, you need to bind them
    to globally available keys, like the ones reserved for users (see
    [[info:elisp::Key%20Binding%20Conventions]]).  Here are suggested
    bindings, please modify the keys to your own liking.

    #+begin_src emacs-lisp
      (global-set-key "\C-cl" 'org-store-link)
      (global-set-key "\C-ca" 'org-agenda)
      (global-set-key "\C-cc" 'org-capture)
    #+end_src

Drew pointed out that suggesting to bind user reserved keys was almost
as if we were binding them. 

I can hear that argument, and would happily stop the paragraph at
"globally available keys". However, I have the feeling this deserves
a cross-reference, and an appendix in the Elisp manual doesn't sound
like an appropriate location.

Regards,

-- 
Nicolas Goaziou                                                0x80A93738

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

[Eli Zaretskii]

> From: Nicolas Goaziou <mail@nicolasgoaziou.fr>
> Cc: Drew Adams <drew.adams@oracle.com>,  30530-done@debbugs.gnu.org
> Date: Sat, 24 Feb 2018 22:27:48 +0100
> 
> For good measure, could you also add a @cindex about it? E.g,
> 
>   @cindex user reserved key bindings

Starting an index entry with "user" is not a good idea, as it's too
general a word.  I added "reserved key bindings" instead.

>     For a better experience, the three Org commands ~org-store-link~,
>     ~org-capture~ and ~org-agenda~ ought to be accessible anywhere in
>     Emacs, not just in Org buffers.  To that effect, you need to bind them
>     to globally available keys, like the ones reserved for users (see
>     [[info:elisp::Key%20Binding%20Conventions]]).  Here are suggested
>     bindings, please modify the keys to your own liking.
> 
>     #+begin_src emacs-lisp
>       (global-set-key "\C-cl" 'org-store-link)
>       (global-set-key "\C-ca" 'org-agenda)
>       (global-set-key "\C-cc" 'org-capture)
>     #+end_src
> 
> Drew pointed out that suggesting to bind user reserved keys was almost
> as if we were binding them. 

I disagree with Drew.  By that logic, no one can ever say anything
about binding these keys, and they must always remain unbound, which
of course would defeat the reason for reserving them.

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

[Drew Adams]

> > Drew pointed out that suggesting to bind user reserved keys was almost
> > as if we were binding them.
> 
> I disagree with Drew.  By that logic, no one can ever say anything
> about binding these keys, and they must always remain unbound, which
> of course would defeat the reason for reserving them.

No.  This is about a library - and in particular an
extremely widely used library, perhaps _the most popular_
Emacs library - recommending that users globally bind a
whole set of user-reserved keys to commands for use only
by that library.

And yes that is pretty much tantamount, in practice, to
that library globally binding those keys by default.

Your claim that if a library doesn't suggest that users
sacrifice their reserved keys for that library then _no
user will ever bind such keys_ is, well, preposterous.
That doesn't follow at all.

Talk about "by that logic..."!  The Emacs doc makes clear
that these keys are reserved for users.  Users do not need
a library to instruct them to co-opt the keys for its use.
Without such "help" users will continue, just fine, to bind
such keys for whatever uses they like - as they always have.

For Org to say that for best use/experience Emacs recommends
that you globally bind these N keys to Org commands works
against their reservation for users, as a practical matter.
Some (many?) users, especially newbies, may well blindly
follow such a bogus "best use" recommendation.

I'm surprised that you would endorse this.  There is no
need for it, and it is not helpful.

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

[Eli Zaretskii]

> Date: Thu, 1 Mar 2018 09:31:13 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: drew.adams@oracle.com, 30530@debbugs.gnu.org
> 
> The Emacs doc makes clear that these keys are reserved for users.

Being reserved means that users can bind them.

> Users do not need a library to instruct them to co-opt the keys for
> its use.

No, it's not a library that "instructs" them, it's a document that
tells them they could bind these keys for their own convenience.

> I'm surprised that you would endorse this.  There is no
> need for it, and it is not helpful.

I think I'm entitled to my opinions even if you consider them
unhelpful (unhelpful to what, may I wonder?).

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

[Noam Postavsky]

On Thu, Mar 1, 2018 at 2:22 PM, Eli Zaretskii <eliz@gnu.org> wrote:

>> I'm surprised that you would endorse this.  There is no
>> need for it, and it is not helpful.
>
> I think I'm entitled to my opinions even if you consider them
> unhelpful (unhelpful to what, may I wonder?).

I think "it" referred to the org manual suggesting to bind reserved
keys, not your endorsement or opinions.

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

[Drew Adams]

> > 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.

> > Users do not need a library to instruct them to co-opt
> > the keys for its use.
> 
> No, it's not a library that "instructs" them, it's a document that
> tells them they could bind these keys for their own convenience.

We can perhaps agree to disagree about that, as well as
perhaps about the likely result of users, particularly
newbies, following that Org-doc recommendation.

> > I'm surprised that you would endorse this.
> > There is no need for it, and it is not helpful.
> 
> I think I'm entitled to my opinions

Of course you are.  No one said anything to the contrary.

> even if you consider them unhelpful (unhelpful to what,
> may I wonder?).

Please read what I wrote.  I did not say that your opinions
are unhelpful.

It is the practice that was the subject of bug #28263, and
that you seem to endorse, that I said users do not need and
is not helpful (for users, obviously).

The Org doc does not need to recommend that users bind
reserved user keys to Org commands, and doing so is (IMHO)
unhelpful to users.

Just one opinion, of course.

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

[Noam Postavsky]

On Thu, Mar 1, 2018 at 4:00 PM, Drew Adams <drew.adams@oracle.com> wrote:

>> > I'm surprised that you would endorse this.
>> > There is no need for it, and it is not helpful.
>>
>> I think I'm entitled to my opinions
>
> Of course you are.  No one said anything to the contrary.
>
>> even if you consider them unhelpful (unhelpful to what,
>> may I wonder?).
>
> Please read what I wrote.  I did not say that your opinions
> are unhelpful.

Your phrasing was ambiguous enough to read that way though.

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

[Eli Zaretskii]

> Date: Thu, 1 Mar 2018 13:00:37 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: mail@nicolasgoaziou.fr, 30530@debbugs.gnu.org
> 
> > > 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.

> We can perhaps agree to disagree about that, as well as
> perhaps about the likely result of users, particularly
> newbies, following that Org-doc recommendation.

I started by saying I disagreed with your opinion.  It's you who
decided to respond.

> The Org doc does not need to recommend that users bind
> reserved user keys to Org commands, and doing so is (IMHO)
> unhelpful to users.
> 
> Just one opinion, of course.

Once again, I disagree, and thing that any documentation of any
package can suggest binding those keys.  That's what those keys are
reserved for.

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

[Drew Adams]

> > > > 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.

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

[Eli Zaretskii]

> Date: Fri, 2 Mar 2018 07:17:14 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: mail@nicolasgoaziou.fr, 30530@debbugs.gnu.org
> 
> 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 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.

There's no difference here that I can see.  Library docs are written
by the same people who answer questions in stackoverflow and write
blogs, and draw from the same knowledge and experience.  Suggestions
for convenient key bindings in a manual that describes a library is no
different from a suggestion in a blog about such bindings.  Making
them different, let alone to a degree that requires denigrating one of
them, is more than splitting hair.

> 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.

Saying that they are reserved and suggesting to bind them in some
situation are two different ways of saying the same thing.