GNU bug report logs -
#30530
26.0; Emacs manual: mention (1) user-reserved keys, (2) users can bind any keys
Previous Next
Reported by: Drew Adams <drew.adams <at> oracle.com>
Date: Mon, 19 Feb 2018 16:17:01 UTC
Severity: wishlist
Found in version 26.0
Done: Eli Zaretskii <eliz <at> gnu.org>
Bug is archived. No further changes may be made.
To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 30530 in the body.
You can then email your comments to 30530 AT debbugs.gnu.org in the normal way.
Toggle the display of automated, internal messages from the tracker.
Report forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#30530; Package
emacs.
(Mon, 19 Feb 2018 16:17:01 GMT)
Full text and
rfc822 format available.
Acknowledgement sent
to
Drew Adams <drew.adams <at> oracle.com>:
New bug report received and forwarded. Copy sent to
bug-gnu-emacs <at> gnu.org.
(Mon, 19 Feb 2018 16:17:01 GMT)
Full text and
rfc822 format available.
Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):
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''
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#30530; Package
emacs.
(Sat, 24 Feb 2018 10:35:02 GMT)
Full text and
rfc822 format available.
Message #8 received at 30530 <at> debbugs.gnu.org (full text, mbox):
> Date: Mon, 19 Feb 2018 08:16:09 -0800 (PST)
> From: Drew Adams <drew.adams <at> 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.
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#30530; Package
emacs.
(Sat, 24 Feb 2018 17:02:01 GMT)
Full text and
rfc822 format available.
Message #11 received at 30530 <at> debbugs.gnu.org (full text, mbox):
> > 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.
Reply sent
to
Eli Zaretskii <eliz <at> gnu.org>:
You have taken responsibility.
(Sat, 24 Feb 2018 17:45:01 GMT)
Full text and
rfc822 format available.
Notification sent
to
Drew Adams <drew.adams <at> oracle.com>:
bug acknowledged by developer.
(Sat, 24 Feb 2018 17:45:02 GMT)
Full text and
rfc822 format available.
Message #16 received at 30530-done <at> debbugs.gnu.org (full text, mbox):
> Date: Sat, 24 Feb 2018 09:00:51 -0800 (PST)
> From: Drew Adams <drew.adams <at> oracle.com>
> Cc: 30530 <at> 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.
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#30530; Package
emacs.
(Sat, 24 Feb 2018 21:28:02 GMT)
Full text and
rfc822 format available.
Message #19 received at 30530-done <at> debbugs.gnu.org (full text, mbox):
Hello,
Eli Zaretskii <eliz <at> 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
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#30530; Package
emacs.
(Thu, 01 Mar 2018 15:45:02 GMT)
Full text and
rfc822 format available.
Message #22 received at 30530 <at> debbugs.gnu.org (full text, mbox):
> From: Nicolas Goaziou <mail <at> nicolasgoaziou.fr>
> Cc: Drew Adams <drew.adams <at> oracle.com>, 30530-done <at> 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.
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#30530; Package
emacs.
(Thu, 01 Mar 2018 17:32:02 GMT)
Full text and
rfc822 format available.
Message #25 received at 30530 <at> debbugs.gnu.org (full text, mbox):
> > 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.
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#30530; Package
emacs.
(Thu, 01 Mar 2018 19:23:02 GMT)
Full text and
rfc822 format available.
Message #28 received at 30530 <at> debbugs.gnu.org (full text, mbox):
> Date: Thu, 1 Mar 2018 09:31:13 -0800 (PST)
> From: Drew Adams <drew.adams <at> oracle.com>
> Cc: drew.adams <at> oracle.com, 30530 <at> 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?).
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#30530; Package
emacs.
(Thu, 01 Mar 2018 19:31:02 GMT)
Full text and
rfc822 format available.
Message #31 received at 30530 <at> debbugs.gnu.org (full text, mbox):
On Thu, Mar 1, 2018 at 2:22 PM, Eli Zaretskii <eliz <at> 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.
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#30530; Package
emacs.
(Thu, 01 Mar 2018 21:01:02 GMT)
Full text and
rfc822 format available.
Message #34 received at 30530 <at> debbugs.gnu.org (full text, mbox):
> > 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.
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#30530; Package
emacs.
(Thu, 01 Mar 2018 21:34:02 GMT)
Full text and
rfc822 format available.
Message #37 received at 30530 <at> debbugs.gnu.org (full text, mbox):
On Thu, Mar 1, 2018 at 4:00 PM, Drew Adams <drew.adams <at> 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.
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#30530; Package
emacs.
(Fri, 02 Mar 2018 05:33:01 GMT)
Full text and
rfc822 format available.
Message #40 received at 30530 <at> debbugs.gnu.org (full text, mbox):
> Date: Thu, 1 Mar 2018 13:00:37 -0800 (PST)
> From: Drew Adams <drew.adams <at> oracle.com>
> Cc: mail <at> nicolasgoaziou.fr, 30530 <at> 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.
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#30530; Package
emacs.
(Fri, 02 Mar 2018 15:18:01 GMT)
Full text and
rfc822 format available.
Message #43 received at 30530 <at> debbugs.gnu.org (full text, mbox):
> > > > 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.
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#30530; Package
emacs.
(Fri, 02 Mar 2018 15:50:02 GMT)
Full text and
rfc822 format available.
Message #46 received at 30530 <at> debbugs.gnu.org (full text, mbox):
> Date: Fri, 2 Mar 2018 07:17:14 -0800 (PST)
> From: Drew Adams <drew.adams <at> oracle.com>
> Cc: mail <at> nicolasgoaziou.fr, 30530 <at> 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.
bug archived.
Request was from
Debbugs Internal Request <help-debbugs <at> gnu.org>
to
internal_control <at> debbugs.gnu.org.
(Sat, 31 Mar 2018 11:24:04 GMT)
Full text and
rfc822 format available.
This bug report was last modified 7 years and 84 days ago.
Previous Next
GNU bug tracking system
Copyright (C) 1999 Darren O. Benham,
1997,2003 nCipher Corporation Ltd,
1994-97 Ian Jackson.