* bug#15917: 24.3.50; manual: mention keys reserved for users
[not found] ` <<83zh438lzp.fsf@gnu.org>
@ 2020-10-30 21:24 ` Drew Adams
0 siblings, 0 replies; 26+ messages in thread
From: Drew Adams @ 2020-10-30 21:24 UTC (permalink / raw)
To: Eli Zaretskii, Drew Adams; +Cc: michael_heerdegen, 15917, larsi, stefan, psmith
> None of the above fits, because these are not coding conventions.
Do you prefer "key-binding conventions"?
(elisp) `Key Binding Conventions':
Don't define 'C-c LETTER' as a key in Lisp programs. Sequences
consisting of 'C-c' and a letter (either upper or lower case) are
reserved for users; they are the *only* sequences reserved for
users, so do not block them.
Changing all the Emacs major modes to respect this convention was a
lot of work; abandoning this convention would make that work go to
waste, and inconvenience users. Please comply with it.
> We have a good text proposed already, let's not waste any more time
> trying to make it better.
Clearly I've wasted my time, in response to (more than one)
explicit request for suggested text. Why am I not surprised?
^ permalink raw reply [flat|nested] 26+ messages in thread
[parent not found: <<87wqk6e5zm.fsf@web.de>]
* bug#15917: 24.3.50; manual: mention keys reserved for users
@ 2013-11-18 3:36 Michael Heerdegen
2013-11-18 4:36 ` Drew Adams
2020-10-28 7:39 ` Stefan Kangas
0 siblings, 2 replies; 26+ messages in thread
From: Michael Heerdegen @ 2013-11-18 3:36 UTC (permalink / raw)
To: 15917; +Cc: Paul Smith
Hello,
(info "(emacs) Keymaps") doesn't tell anything about keys reserved for
users (C-c LETTER). BTW, this was the case some time ago, see
ftp://ftp.gnu.org/old-gnu/Manuals/emacs/html_node/emacs_492.html
Users reading the users manual should have a chance to find this
essential information, because getting used to bindings you cannot keep
because of collisions you find later is very annoying. I propose to add
a sentence describing that C-c LETTER key sequences are reserved for
users. It would also be suitable for "(emacs) Init Rebinding", but
somewhere it should be said.
Thanks,
Michael.
In GNU Emacs 24.3.50.1 (x86_64-unknown-linux-gnu, GTK+ Version 3.8.4)
of 2013-11-13 on drachen
Windowing system distributor `The X.Org Foundation', version 11.0.11403000
System Description: Debian GNU/Linux testing (jessie)
^ permalink raw reply [flat|nested] 26+ messages in thread
* bug#15917: 24.3.50; manual: mention keys reserved for users
2013-11-18 3:36 Michael Heerdegen
@ 2013-11-18 4:36 ` Drew Adams
2013-11-18 7:16 ` Josh
2020-10-28 7:39 ` Stefan Kangas
1 sibling, 1 reply; 26+ messages in thread
From: Drew Adams @ 2013-11-18 4:36 UTC (permalink / raw)
To: michael_heerdegen, 15917; +Cc: Paul Smith
And please cross reference the Elisp manual, node `Key Binding Conventions',
so users can get more complete information.
^ permalink raw reply [flat|nested] 26+ messages in thread
* bug#15917: 24.3.50; manual: mention keys reserved for users
2013-11-18 4:36 ` Drew Adams
@ 2013-11-18 7:16 ` Josh
2013-11-18 9:16 ` Andreas Röhler
0 siblings, 1 reply; 26+ messages in thread
From: Josh @ 2013-11-18 7:16 UTC (permalink / raw)
To: Drew Adams; +Cc: michael_heerdegen, 15917, Paul Smith
On Sun, Nov 17, 2013 at 8:36 PM, Drew Adams <drew.adams@oracle.com> wrote:
> And please cross reference the Elisp manual, node `Key Binding Conventions',
> so users can get more complete information.
Those conventions seem to have fallen by the wayside, at least where users'
keys are concerned: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=12976
^ permalink raw reply [flat|nested] 26+ messages in thread
* bug#15917: 24.3.50; manual: mention keys reserved for users
2013-11-18 7:16 ` Josh
@ 2013-11-18 9:16 ` Andreas Röhler
0 siblings, 0 replies; 26+ messages in thread
From: Andreas Röhler @ 2013-11-18 9:16 UTC (permalink / raw)
To: 15917
Am 18.11.2013 08:16, schrieb Josh:
> On Sun, Nov 17, 2013 at 8:36 PM, Drew Adams <drew.adams@oracle.com> wrote:
>> And please cross reference the Elisp manual, node `Key Binding Conventions',
>> so users can get more complete information.
>
> Those conventions seem to have fallen by the wayside, at least where users'
> keys are concerned: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=12976
>
>
>
>
Consider it a bug. IMO it's important to have some keys known to be free - it's very important for Emacs beginners.
OTOH Elisp manual seems the right place, as it's a coding question.
^ permalink raw reply [flat|nested] 26+ messages in thread
* bug#15917: 24.3.50; manual: mention keys reserved for users
2013-11-18 3:36 Michael Heerdegen
2013-11-18 4:36 ` Drew Adams
@ 2020-10-28 7:39 ` Stefan Kangas
2020-10-28 8:05 ` Lars Ingebrigtsen
1 sibling, 1 reply; 26+ messages in thread
From: Stefan Kangas @ 2020-10-28 7:39 UTC (permalink / raw)
To: Michael Heerdegen; +Cc: 15917, Paul Smith
Michael Heerdegen <michael_heerdegen@web.de> writes:
> (info "(emacs) Keymaps") doesn't tell anything about keys reserved for
> users (C-c LETTER). BTW, this was the case some time ago, see
>
> ftp://ftp.gnu.org/old-gnu/Manuals/emacs/html_node/emacs_492.html
New URL:
https://ftp.gnu.org/old-gnu/Manuals/emacs/html_node/emacs_492.html
> Users reading the users manual should have a chance to find this
> essential information, because getting used to bindings you cannot keep
> because of collisions you find later is very annoying. I propose to add
> a sentence describing that C-c LETTER key sequences are reserved for
> users. It would also be suitable for "(emacs) Init Rebinding", but
> somewhere it should be said.
The text on the above link was removed in:
commit 8ba46c89bc0c2dccc9e51f1533dd127ecc125fbd
Author: Chong Yidong <cyd@stupidchicken.com>
Date: Sat Sep 19 21:23:21 2009 +0000
OTOH, in `(elisp) Key Binding Conventions' we say:
• Don’t define ‘C-c LETTER’ as a key in Lisp programs. Sequences
consisting of ‘C-c’ and a letter (either upper or lower case) are
reserved for users; they are the *only* sequences reserved for
users, so do not block them.
It's not clear to me why this convention was removed from the user
manual. Should it perhaps be added back in?
^ permalink raw reply [flat|nested] 26+ messages in thread* bug#15917: 24.3.50; manual: mention keys reserved for users
2020-10-28 7:39 ` Stefan Kangas
@ 2020-10-28 8:05 ` Lars Ingebrigtsen
2020-10-29 10:07 ` Michael Heerdegen
0 siblings, 1 reply; 26+ messages in thread
From: Lars Ingebrigtsen @ 2020-10-28 8:05 UTC (permalink / raw)
To: Stefan Kangas; +Cc: Michael Heerdegen, 15917, Paul Smith
Stefan Kangas <stefan@marxist.se> writes:
> The text on the above link was removed in:
>
> commit 8ba46c89bc0c2dccc9e51f1533dd127ecc125fbd
> Author: Chong Yidong <cyd@stupidchicken.com>
> Date: Sat Sep 19 21:23:21 2009 +0000
The old text was so strict as to be misleading:
- As a user, you can redefine any key, but it is usually best to stick
-to key sequences that consist of @kbd{C-c} followed by a letter (upper
-or lower case). These keys are ``reserved for users,'' so they won't
-conflict with any properly designed Emacs extension.
I think that's too discouraging, so I see why it was removed. But I
think the text should mention that C-c LETTER is strictly reserved for
users and will never be bound by Emacs itself.
--
(domestic pets only, the antidote for overdose, milk.)
bloggy blog: http://lars.ingebrigtsen.no
^ permalink raw reply [flat|nested] 26+ messages in thread* bug#15917: 24.3.50; manual: mention keys reserved for users
2020-10-28 8:05 ` Lars Ingebrigtsen
@ 2020-10-29 10:07 ` Michael Heerdegen
2020-10-29 15:22 ` Stefan Kangas
0 siblings, 1 reply; 26+ messages in thread
From: Michael Heerdegen @ 2020-10-29 10:07 UTC (permalink / raw)
To: Lars Ingebrigtsen; +Cc: 15917, Stefan Kangas, Paul Smith
Lars Ingebrigtsen <larsi@gnus.org> writes:
> [...]
> But I think the text should mention that C-c LETTER is strictly
> reserved for users and will never be bound by Emacs itself.
Sounds good, from my side.
Regards,
Michael.
^ permalink raw reply [flat|nested] 26+ messages in thread
* bug#15917: 24.3.50; manual: mention keys reserved for users
2020-10-29 10:07 ` Michael Heerdegen
@ 2020-10-29 15:22 ` Stefan Kangas
2020-10-29 15:33 ` Stefan Kangas
2020-10-29 16:59 ` Drew Adams
0 siblings, 2 replies; 26+ messages in thread
From: Stefan Kangas @ 2020-10-29 15:22 UTC (permalink / raw)
To: Michael Heerdegen, Lars Ingebrigtsen; +Cc: 15917, Paul Smith
Michael Heerdegen <michael_heerdegen@web.de> writes:
>> But I think the text should mention that C-c LETTER is strictly
>> reserved for users and will never be bound by Emacs itself.
>
> Sounds good, from my side.
How about the following?
diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi
index 81874a04aa..d993b652f5 100644
--- a/doc/emacs/custom.texi
+++ b/doc/emacs/custom.texi
@@ -1582,6 +1582,10 @@ Keymaps
type properly, it automatically handles such sequences as single input
events.
+Key sequences that consist of @kbd{C-c} followed by a letter (upper or
+lower case) are ``reserved for users,'' and will never conflict with
+any properly designed Emacs extension or Emacs itself.
+
@node Prefix Keymaps
@subsection Prefix Keymaps
^ permalink raw reply related [flat|nested] 26+ messages in thread* bug#15917: 24.3.50; manual: mention keys reserved for users
2020-10-29 15:22 ` Stefan Kangas
@ 2020-10-29 15:33 ` Stefan Kangas
2020-10-30 11:47 ` Lars Ingebrigtsen
2020-10-29 16:59 ` Drew Adams
1 sibling, 1 reply; 26+ messages in thread
From: Stefan Kangas @ 2020-10-29 15:33 UTC (permalink / raw)
To: Michael Heerdegen, Lars Ingebrigtsen; +Cc: 15917, Paul Smith
[-- Attachment #1: Type: text/plain, Size: 337 bytes --]
Stefan Kangas <stefan@marxist.se> writes:
> Michael Heerdegen <michael_heerdegen@web.de> writes:
>
>>> But I think the text should mention that C-c LETTER is strictly
>>> reserved for users and will never be bound by Emacs itself.
>>
>> Sounds good, from my side.
>
> How about the following?
The same change is in the attached patch.
[-- Attachment #2: 0001-Say-that-C-A-Za-z-keys-are-reserved-for-users-in-use.patch --]
[-- Type: text/x-diff, Size: 923 bytes --]
From 3d360c66601d849308f3dd65e05ce2538135981a Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefan@marxist.se>
Date: Thu, 29 Oct 2020 16:26:25 +0100
Subject: [PATCH] Say that C-[A-Za-z] keys are reserved for users in user
manual
* doc/emacs/custom.texi (Keymaps): Say that C-[A-Za-z] keys reserved
for users. (Bug#15917)
---
doc/emacs/custom.texi | 4 ++++
1 file changed, 4 insertions(+)
diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi
index 81874a04aa..d993b652f5 100644
--- a/doc/emacs/custom.texi
+++ b/doc/emacs/custom.texi
@@ -1582,6 +1582,10 @@ Keymaps
type properly, it automatically handles such sequences as single input
events.
+Key sequences that consist of @kbd{C-c} followed by a letter (upper or
+lower case) are ``reserved for users,'' and will never conflict with
+any properly designed Emacs extension or Emacs itself.
+
@node Prefix Keymaps
@subsection Prefix Keymaps
--
2.28.0
^ permalink raw reply related [flat|nested] 26+ messages in thread* bug#15917: 24.3.50; manual: mention keys reserved for users
2020-10-29 15:33 ` Stefan Kangas
@ 2020-10-30 11:47 ` Lars Ingebrigtsen
2020-10-30 11:51 ` Eli Zaretskii
0 siblings, 1 reply; 26+ messages in thread
From: Lars Ingebrigtsen @ 2020-10-30 11:47 UTC (permalink / raw)
To: Stefan Kangas; +Cc: Michael Heerdegen, 15917, Paul Smith
Stefan Kangas <stefan@marxist.se> writes:
> +Key sequences that consist of @kbd{C-c} followed by a letter (upper or
> +lower case) are ``reserved for users,'' and will never conflict with
> +any properly designed Emacs extension or Emacs itself.
What about something like:
Key sequences that consist of @kbd{C-c} followed by a letter (upper or
lower case) are reserved for users. Emacs itself will never bind those
key sequences, and Emacs extensions should avoid binding them.
--
(domestic pets only, the antidote for overdose, milk.)
bloggy blog: http://lars.ingebrigtsen.no
^ permalink raw reply [flat|nested] 26+ messages in thread* bug#15917: 24.3.50; manual: mention keys reserved for users
2020-10-30 11:47 ` Lars Ingebrigtsen
@ 2020-10-30 11:51 ` Eli Zaretskii
2020-10-30 11:55 ` Lars Ingebrigtsen
0 siblings, 1 reply; 26+ messages in thread
From: Eli Zaretskii @ 2020-10-30 11:51 UTC (permalink / raw)
To: Lars Ingebrigtsen; +Cc: michael_heerdegen, 15917, stefan, psmith
> From: Lars Ingebrigtsen <larsi@gnus.org>
> Date: Fri, 30 Oct 2020 12:47:40 +0100
> Cc: Michael Heerdegen <michael_heerdegen@web.de>, 15917@debbugs.gnu.org,
> Paul Smith <psmith@gnu.org>
>
> What about something like:
>
> Key sequences that consist of @kbd{C-c} followed by a letter (upper or
> lower case) are reserved for users. Emacs itself will never bind those
> key sequences, and Emacs extensions should avoid binding them.
That'd be fine with me, but should we perhaps clarify what is a
"letter" in this context? Are we talking about ASCII letters only, or
are non-ASCII letters also included?
^ permalink raw reply [flat|nested] 26+ messages in thread* bug#15917: 24.3.50; manual: mention keys reserved for users
2020-10-30 11:51 ` Eli Zaretskii
@ 2020-10-30 11:55 ` Lars Ingebrigtsen
2020-10-30 12:09 ` Stefan Kangas
0 siblings, 1 reply; 26+ messages in thread
From: Lars Ingebrigtsen @ 2020-10-30 11:55 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: michael_heerdegen, 15917, stefan, psmith
Eli Zaretskii <eliz@gnu.org> writes:
> That'd be fine with me, but should we perhaps clarify what is a
> "letter" in this context? Are we talking about ASCII letters only, or
> are non-ASCII letters also included?
Good question. I assumed that this was about ASCII letters only, but
thinking about it, I don't see why: I think we should reserve all `C-c
LETTER' key sequences for the users.
--
(domestic pets only, the antidote for overdose, milk.)
bloggy blog: http://lars.ingebrigtsen.no
^ permalink raw reply [flat|nested] 26+ messages in thread
* bug#15917: 24.3.50; manual: mention keys reserved for users
2020-10-30 11:55 ` Lars Ingebrigtsen
@ 2020-10-30 12:09 ` Stefan Kangas
2020-11-01 11:52 ` Lars Ingebrigtsen
0 siblings, 1 reply; 26+ messages in thread
From: Stefan Kangas @ 2020-10-30 12:09 UTC (permalink / raw)
To: Lars Ingebrigtsen, Eli Zaretskii; +Cc: michael_heerdegen, 15917, psmith
Lars Ingebrigtsen <larsi@gnus.org> writes:
> Eli Zaretskii <eliz@gnu.org> writes:
>
>> That'd be fine with me, but should we perhaps clarify what is a
>> "letter" in this context? Are we talking about ASCII letters only, or
>> are non-ASCII letters also included?
>
> Good question. I assumed that this was about ASCII letters only, but
> thinking about it, I don't see why: I think we should reserve all `C-c
> LETTER' key sequences for the users.
Agreed. OTOH, it would be pretty odd for Emacs or any packages to bind
non-ASCII letters. I've never seen any software bind such keys by
default, I think.
But if we do add it, we should probably update `(elisp) Key Binding
Conventions' as well.
^ permalink raw reply [flat|nested] 26+ messages in thread
* bug#15917: 24.3.50; manual: mention keys reserved for users
2020-10-30 12:09 ` Stefan Kangas
@ 2020-11-01 11:52 ` Lars Ingebrigtsen
0 siblings, 0 replies; 26+ messages in thread
From: Lars Ingebrigtsen @ 2020-11-01 11:52 UTC (permalink / raw)
To: Stefan Kangas; +Cc: michael_heerdegen, 15917, psmith
Stefan Kangas <stefan@marxist.se> writes:
>> Good question. I assumed that this was about ASCII letters only, but
>> thinking about it, I don't see why: I think we should reserve all `C-c
>> LETTER' key sequences for the users.
>
> Agreed. OTOH, it would be pretty odd for Emacs or any packages to bind
> non-ASCII letters. I've never seen any software bind such keys by
> default, I think.
Perhaps nobody has thought of it. :-) But I guess it's because it's
rare for those keybinding to be very handy (except on national
keyboards).
I've now pushed the text (with amendments; feel free to tweak it further).
> But if we do add it, we should probably update `(elisp) Key Binding
> Conventions' as well.
Good point. Now done as well.
--
(domestic pets only, the antidote for overdose, milk.)
bloggy blog: http://lars.ingebrigtsen.no
^ permalink raw reply [flat|nested] 26+ messages in thread
* bug#15917: 24.3.50; manual: mention keys reserved for users
2020-10-29 15:22 ` Stefan Kangas
2020-10-29 15:33 ` Stefan Kangas
@ 2020-10-29 16:59 ` Drew Adams
2020-10-29 17:22 ` Stefan Kangas
1 sibling, 1 reply; 26+ messages in thread
From: Drew Adams @ 2020-10-29 16:59 UTC (permalink / raw)
To: Stefan Kangas, Michael Heerdegen, Lars Ingebrigtsen; +Cc: 15917, Paul Smith
> How about the following?
>
> diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi
> index 81874a04aa..d993b652f5 100644
> --- a/doc/emacs/custom.texi
> +++ b/doc/emacs/custom.texi
> @@ -1582,6 +1582,10 @@ Keymaps
> type properly, it automatically handles such sequences as single input
> events.
>
> +Key sequences that consist of @kbd{C-c} followed by a letter (upper or
> +lower case) are ``reserved for users,'' and will never conflict with
> +any properly designed Emacs extension or Emacs itself.
IMO that last part ("will never conflict")
sounds too automatic or passive.
In code conventions we're really _prescribing_
what we recommend that people _do_ or don't do
(active).
Here, we really want to suggest/ask that when
writing code for use by others you do not bind
`C-c' followed by a letter. It's a _request_
to never produce code that conflicts with this
recommendation.
The point is that these keys are reserved for
users. Another way to put that is to ask/tell
people writing code to be used by others not
to use these keys in that code.
^ permalink raw reply [flat|nested] 26+ messages in thread* bug#15917: 24.3.50; manual: mention keys reserved for users
2020-10-29 16:59 ` Drew Adams
@ 2020-10-29 17:22 ` Stefan Kangas
2020-10-29 17:58 ` Drew Adams
0 siblings, 1 reply; 26+ messages in thread
From: Stefan Kangas @ 2020-10-29 17:22 UTC (permalink / raw)
To: Drew Adams, Michael Heerdegen, Lars Ingebrigtsen; +Cc: 15917, Paul Smith
Drew Adams <drew.adams@oracle.com> writes:
>> +Key sequences that consist of @kbd{C-c} followed by a letter (upper or
>> +lower case) are ``reserved for users,'' and will never conflict with
>> +any properly designed Emacs extension or Emacs itself.
>
> IMO that last part ("will never conflict")
> sounds too automatic or passive.
How about "should not conflict"? Otherwise, please propose an
alternative.
^ permalink raw reply [flat|nested] 26+ messages in thread* bug#15917: 24.3.50; manual: mention keys reserved for users
2020-10-29 17:22 ` Stefan Kangas
@ 2020-10-29 17:58 ` Drew Adams
2020-10-29 18:15 ` Stefan Kangas
0 siblings, 1 reply; 26+ messages in thread
From: Drew Adams @ 2020-10-29 17:58 UTC (permalink / raw)
To: Stefan Kangas, Michael Heerdegen, Lars Ingebrigtsen; +Cc: 15917, Paul Smith
> >> +Key sequences that consist of @kbd{C-c} followed by a letter (upper or
> >> +lower case) are ``reserved for users,'' and will never conflict with
> >> +any properly designed Emacs extension or Emacs itself.
> >
> > IMO that last part ("will never conflict")
> > sounds too automatic or passive.
>
> How about "should not conflict"? Otherwise, please propose an
> alternative.
Better, yes. But that could mean that we expect that,
most of the time, they won't (automatically).
Active voice here removes such ambiguity, I think.
Key sequences that consist of @kbd{C-c} followed by a
letter are reserved for users. Please do not write
code to be used by others that binds these keys.
(Why mention "upper or lower"? Why put "reserved for users"
in quotes?)
^ permalink raw reply [flat|nested] 26+ messages in thread* bug#15917: 24.3.50; manual: mention keys reserved for users
2020-10-29 17:58 ` Drew Adams
@ 2020-10-29 18:15 ` Stefan Kangas
2020-10-29 18:28 ` Drew Adams
0 siblings, 1 reply; 26+ messages in thread
From: Stefan Kangas @ 2020-10-29 18:15 UTC (permalink / raw)
To: Drew Adams, Michael Heerdegen, Lars Ingebrigtsen; +Cc: 15917, Paul Smith
Drew Adams <drew.adams@oracle.com> writes:
>> >> +Key sequences that consist of @kbd{C-c} followed by a letter (upper or
>> >> +lower case) are ``reserved for users,'' and will never conflict with
>> >> +any properly designed Emacs extension or Emacs itself.
>> >
>> > IMO that last part ("will never conflict")
>> > sounds too automatic or passive.
>>
>> How about "should not conflict"? Otherwise, please propose an
>> alternative.
>
> Better, yes. But that could mean that we expect that,
> most of the time, they won't (automatically).
I don't understand the second sentence. Could you please elaborate?
> Active voice here removes such ambiguity, I think.
>
> Key sequences that consist of @kbd{C-c} followed by a
> letter are reserved for users. Please do not write
> code to be used by others that binds these keys.
Such advice is already in the elisp manual. The user manual should
rather advice users which keys are reserved for their use in their Init
file. So I don't think writing about "code to be used for others" is
suitable here.
> (Why mention "upper or lower"? Why put "reserved for users"
> in quotes?)
We can probably remove that, yes.
^ permalink raw reply [flat|nested] 26+ messages in thread* bug#15917: 24.3.50; manual: mention keys reserved for users
2020-10-29 18:15 ` Stefan Kangas
@ 2020-10-29 18:28 ` Drew Adams
2020-10-30 1:16 ` Stefan Kangas
0 siblings, 1 reply; 26+ messages in thread
From: Drew Adams @ 2020-10-29 18:28 UTC (permalink / raw)
To: Stefan Kangas, Michael Heerdegen, Lars Ingebrigtsen; +Cc: 15917, Paul Smith
> >> How about "should not conflict"? Otherwise, please propose an
> >> alternative.
> >
> > Better, yes. But that could mean that we expect that,
> > most of the time, they won't (automatically).
>
> I don't understand the second sentence. Could you please elaborate?
"Should" has at least two meanings: (1) you should
do something (like must but less strong) and (2)
something probably will happen.
#2 says that we expect that something will likely
happen, but it doesn't say who makes it happen.
It's passive. There's no telling someone that
you want them to do something. It's just saying
that something will likely happen (somehow).
My suggestion is that we not allow such a reading.
Remove such ambiguity.
> > Active voice here removes such ambiguity, I think.
> >
> > Key sequences that consist of @kbd{C-c} followed by a
> > letter are reserved for users. Please do not write
> > code to be used by others that binds these keys.
>
> Such advice is already in the elisp manual. The user manual should
> rather advice users which keys are reserved for their use in their Init
> file. So I don't think writing about "code to be used for others" is
> suitable here.
Sorry, I thought this was for the Elisp manual, node
`Coding Conventions'.
If this is for the user manual, and it's only a message
for users for their own use of keys, and not also users
who provide default key bindings for others (e.g. in
code they write), then my suggestion is to remove any
such text, beyond saying that these keys are reserved
for personal use (not just "users").
If you want to add (for some reason) that users can at
least expect that code Emacs distributes won't bind
such keys, that's OK too.
^ permalink raw reply [flat|nested] 26+ messages in thread* bug#15917: 24.3.50; manual: mention keys reserved for users
2020-10-29 18:28 ` Drew Adams
@ 2020-10-30 1:16 ` Stefan Kangas
2020-10-30 19:29 ` Drew Adams
0 siblings, 1 reply; 26+ messages in thread
From: Stefan Kangas @ 2020-10-30 1:16 UTC (permalink / raw)
To: Drew Adams, Michael Heerdegen, Lars Ingebrigtsen; +Cc: 15917, Paul Smith
Drew Adams <drew.adams@oracle.com> writes:
> "Should" has at least two meanings: (1) you should
> do something (like must but less strong) and (2)
> something probably will happen.
>
> #2 says that we expect that something will likely
> happen, but it doesn't say who makes it happen.
> It's passive. There's no telling someone that
> you want them to do something. It's just saying
> that something will likely happen (somehow).
>
> My suggestion is that we not allow such a reading.
> Remove such ambiguity.
OK. How do you propose to do that?
The full text would be:
+Key sequences that consist of @kbd{C-c} followed by a letter (upper or
+lower case) are ``reserved for users,'' and should not conflict with
+any properly designed Emacs extension or Emacs itself.
To me, it seems clear that the agent in this case would be either the
Emacs developers or the package developers.
^ permalink raw reply [flat|nested] 26+ messages in thread* bug#15917: 24.3.50; manual: mention keys reserved for users
2020-10-30 1:16 ` Stefan Kangas
@ 2020-10-30 19:29 ` Drew Adams
2020-10-30 20:15 ` Drew Adams
0 siblings, 1 reply; 26+ messages in thread
From: Drew Adams @ 2020-10-30 19:29 UTC (permalink / raw)
To: Stefan Kangas, Michael Heerdegen, Lars Ingebrigtsen; +Cc: 15917, Paul Smith
> > "Should" has at least two meanings: (1) you should
> > do something (like must but less strong) and (2)
> > something probably will happen.
> >
> > #2 says that we expect that something will likely
> > happen, but it doesn't say who makes it happen.
> > It's passive. There's no telling someone that
> > you want them to do something. It's just saying
> > that something will likely happen (somehow).
> >
> > My suggestion is that we not allow such a reading.
> > Remove such ambiguity.
>
> OK. How do you propose to do that?
>
> The full text would be:
>
> +Key sequences that consist of @kbd{C-c} followed by a letter (upper or
> +lower case) are ``reserved for users,'' and should not conflict with
> +any properly designed Emacs extension or Emacs itself.
>
> To me, it seems clear that the agent in this case would be either the
> Emacs developers or the package developers.
The active voice can make things clearer here. Say
that this is by GNU convention. And say that if code
follows the convention then the keys are free for
personal use. It's about personal use, not just use
"by users". Many users provide Elisp code for use
by others.
GNU convention stipulates that key sequences that consist
of C-c followed by a letter are reserved for users. Emacs
Lisp code that follows the convention does not bind these
keys, so that they are free for personal use.
What constitutes "a letter" here, I leave up to others.
^ permalink raw reply [flat|nested] 26+ messages in thread* bug#15917: 24.3.50; manual: mention keys reserved for users
2020-10-30 19:29 ` Drew Adams
@ 2020-10-30 20:15 ` Drew Adams
2020-10-30 20:20 ` Eli Zaretskii
0 siblings, 1 reply; 26+ messages in thread
From: Drew Adams @ 2020-10-30 20:15 UTC (permalink / raw)
To: Stefan Kangas, Michael Heerdegen, Lars Ingebrigtsen; +Cc: 15917, Paul Smith
> GNU convention stipulates that key sequences that consist
> of C-c followed by a letter are reserved for users. Emacs
> Lisp code that follows the convention does not bind these
> keys, so that they are free for personal use.
Perhaps "GNU coding convention" would be even clearer than
"GNU convention."
^ permalink raw reply [flat|nested] 26+ messages in thread
* bug#15917: 24.3.50; manual: mention keys reserved for users
2020-10-30 20:15 ` Drew Adams
@ 2020-10-30 20:20 ` Eli Zaretskii
0 siblings, 0 replies; 26+ messages in thread
From: Eli Zaretskii @ 2020-10-30 20:20 UTC (permalink / raw)
To: Drew Adams; +Cc: michael_heerdegen, 15917, larsi, stefan, psmith
> Date: Fri, 30 Oct 2020 13:15:08 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 15917@debbugs.gnu.org, Paul Smith <psmith@gnu.org>
>
> > GNU convention stipulates that key sequences that consist
> > of C-c followed by a letter are reserved for users. Emacs
> > Lisp code that follows the convention does not bind these
> > keys, so that they are free for personal use.
>
> Perhaps "GNU coding convention" would be even clearer than
> "GNU convention."
It is wrong to speak about GNU (coding) conventions here, since this
is not about GNU or coding, this is about key bindings in Emacs, and
in Emacs alone.
^ permalink raw reply [flat|nested] 26+ messages in thread
end of thread, other threads:[~2020-11-01 11:52 UTC | newest]
Thread overview: 26+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
[not found] <<<87wqk6e5zm.fsf@web.de>
[not found] ` <<<CADwFkmnHdfS5ff6-b-yLsoGW_6o979YD6b=X_BxGo_-Y1wDaBQ@mail.gmail.com>
[not found] ` <<<87v9euwzbe.fsf@gnus.org>
[not found] ` <<<87blglmjlc.fsf@web.de>
[not found] ` <<<CADwFkmmy1o0b0w3iwofZQF=MuiCy8tR8K2O+q-oRsKP3=6tyOg@mail.gmail.com>
[not found] ` <<<54a1c039-6929-4e4d-ac9b-e7e5daf37c68@default>
[not found] ` <<<CADwFkm=ddjsV1U+Teixfdzayhh=+y4i=ybCP=OgJpuajjWcHRw@mail.gmail.com>
[not found] ` <<<62b06d46-5371-4df7-a3c5-b53f84e728ef@default>
[not found] ` <<<CADwFkmkevFnH68gyksx-cFOZC_RwufzeG38ikO_oSk0C0_w-RA@mail.gmail.com>
[not found] ` <<<ac4fd6e5-f511-4b37-8bbe-71a05bd84f9f@default>
[not found] ` <<<CADwFkm=9vHHoBP31hZLRddbKmWbxiF93RSom5cmxo2xo5CDuKw@mail.gmail.com>
[not found] ` <<<ab6c8b7a-18cb-4562-a079-6d2ecf61c970@default>
[not found] ` <<<897aec19-fa31-4ee8-80b4-8241ce3710c6@default>
[not found] ` <<<837dr7a2kk.fsf@gnu.org>
[not found] ` <<0b75f12c-9e1d-4f3f-b8c3-666ae3da6eb0@default>
[not found] ` <<83zh438lzp.fsf@gnu.org>
2020-10-30 21:24 ` bug#15917: 24.3.50; manual: mention keys reserved for users Drew Adams
[not found] <<87wqk6e5zm.fsf@web.de>
[not found] ` <<CADwFkmnHdfS5ff6-b-yLsoGW_6o979YD6b=X_BxGo_-Y1wDaBQ@mail.gmail.com>
[not found] ` <<87v9euwzbe.fsf@gnus.org>
[not found] ` <<87blglmjlc.fsf@web.de>
[not found] ` <<CADwFkmmy1o0b0w3iwofZQF=MuiCy8tR8K2O+q-oRsKP3=6tyOg@mail.gmail.com>
[not found] ` <<54a1c039-6929-4e4d-ac9b-e7e5daf37c68@default>
[not found] ` <<CADwFkm=ddjsV1U+Teixfdzayhh=+y4i=ybCP=OgJpuajjWcHRw@mail.gmail.com>
[not found] ` <<62b06d46-5371-4df7-a3c5-b53f84e728ef@default>
[not found] ` <<CADwFkmkevFnH68gyksx-cFOZC_RwufzeG38ikO_oSk0C0_w-RA@mail.gmail.com>
[not found] ` <<ac4fd6e5-f511-4b37-8bbe-71a05bd84f9f@default>
[not found] ` <<CADwFkm=9vHHoBP31hZLRddbKmWbxiF93RSom5cmxo2xo5CDuKw@mail.gmail.com>
[not found] ` <<ab6c8b7a-18cb-4562-a079-6d2ecf61c970@default>
[not found] ` <<897aec19-fa31-4ee8-80b4-8241ce3710c6@default>
[not found] ` <<837dr7a2kk.fsf@gnu.org>
2020-10-30 20:50 ` Drew Adams
2020-10-30 21:03 ` Eli Zaretskii
2013-11-18 3:36 Michael Heerdegen
2013-11-18 4:36 ` Drew Adams
2013-11-18 7:16 ` Josh
2013-11-18 9:16 ` Andreas Röhler
2020-10-28 7:39 ` Stefan Kangas
2020-10-28 8:05 ` Lars Ingebrigtsen
2020-10-29 10:07 ` Michael Heerdegen
2020-10-29 15:22 ` Stefan Kangas
2020-10-29 15:33 ` Stefan Kangas
2020-10-30 11:47 ` Lars Ingebrigtsen
2020-10-30 11:51 ` Eli Zaretskii
2020-10-30 11:55 ` Lars Ingebrigtsen
2020-10-30 12:09 ` Stefan Kangas
2020-11-01 11:52 ` Lars Ingebrigtsen
2020-10-29 16:59 ` Drew Adams
2020-10-29 17:22 ` Stefan Kangas
2020-10-29 17:58 ` Drew Adams
2020-10-29 18:15 ` Stefan Kangas
2020-10-29 18:28 ` Drew Adams
2020-10-30 1:16 ` Stefan Kangas
2020-10-30 19:29 ` Drew Adams
2020-10-30 20:15 ` Drew Adams
2020-10-30 20:20 ` Eli Zaretskii
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.