GNU bug report logs - #15917
24.3.50; manual: mention keys reserved for users

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 15917 in the body.
You can then email your comments to 15917 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Michael Heerdegen <michael_heerdegen <at> web.de>
To: bug-gnu-emacs <at> gnu.org
Cc: Drew Adams <drew.adams <at> oracle.com>, Paul Smith <psmith <at> gnu.org>
Subject: 24.3.50; manual: mention keys reserved for users
Date: Mon, 18 Nov 2013 04:36:13 +0100

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)

Message #8 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Michael Heerdegen <michael_heerdegen <at> web.de>, bug-gnu-emacs <at> gnu.org
Cc: Paul Smith <psmith <at> gnu.org>
Subject: RE: 24.3.50; manual: mention keys reserved for users
Date: Sun, 17 Nov 2013 20:36:34 -0800 (PST)

And please cross reference the Elisp manual, node `Key Binding Conventions',
so users can get more complete information.

Message #11 received at 15917 <at> debbugs.gnu.org (full text, mbox):

From: Josh <josh <at> foxtail.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: michael_heerdegen <at> web.de, 15917 <at> debbugs.gnu.org,
 Paul Smith <psmith <at> gnu.org>
Subject: Re: bug#15917: 24.3.50; manual: mention keys reserved for users
Date: Sun, 17 Nov 2013 23:16:54 -0800

On Sun, Nov 17, 2013 at 8:36 PM, Drew Adams <drew.adams <at> 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

Message #14 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Andreas Röhler <andreas.roehler <at> easy-emacs.de>
To: bug-gnu-emacs <at> gnu.org
Subject: Re: bug#15917: 24.3.50; manual: mention keys reserved for users
Date: Mon, 18 Nov 2013 10:16:14 +0100

Am 18.11.2013 08:16, schrieb Josh:
> On Sun, Nov 17, 2013 at 8:36 PM, Drew Adams <drew.adams <at> 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.

Message #17 received at 15917 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Michael Heerdegen <michael_heerdegen <at> web.de>
Cc: 15917 <at> debbugs.gnu.org, Drew Adams <drew.adams <at> oracle.com>,
 Paul Smith <psmith <at> gnu.org>
Subject: Re: bug#15917: 24.3.50; manual: mention keys reserved for users
Date: Wed, 28 Oct 2020 00:39:43 -0700

Michael Heerdegen <michael_heerdegen <at> 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 <at> 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?

Message #20 received at 15917 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: Michael Heerdegen <michael_heerdegen <at> web.de>, 15917 <at> debbugs.gnu.org,
 Paul Smith <psmith <at> gnu.org>
Subject: Re: bug#15917: 24.3.50; manual: mention keys reserved for users
Date: Wed, 28 Oct 2020 09:05:09 +0100

Stefan Kangas <stefan <at> marxist.se> writes:

> The text on the above link was removed in:
>
>     commit 8ba46c89bc0c2dccc9e51f1533dd127ecc125fbd
>     Author: Chong Yidong <cyd <at> 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

Message #23 received at 15917 <at> debbugs.gnu.org (full text, mbox):

From: Michael Heerdegen <michael_heerdegen <at> web.de>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 15917 <at> debbugs.gnu.org, Stefan Kangas <stefan <at> marxist.se>,
 Paul Smith <psmith <at> gnu.org>
Subject: Re: bug#15917: 24.3.50; manual: mention keys reserved for users
Date: Thu, 29 Oct 2020 11:07:11 +0100

Lars Ingebrigtsen <larsi <at> 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.

Message #26 received at 15917 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Michael Heerdegen <michael_heerdegen <at> web.de>,
 Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 15917 <at> debbugs.gnu.org, Paul Smith <psmith <at> gnu.org>
Subject: Re: bug#15917: 24.3.50; manual: mention keys reserved for users
Date: Thu, 29 Oct 2020 15:22:57 +0000

Michael Heerdegen <michael_heerdegen <at> 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

Message #29 received at 15917 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Michael Heerdegen <michael_heerdegen <at> web.de>,
 Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 15917 <at> debbugs.gnu.org, Paul Smith <psmith <at> gnu.org>
Subject: Re: bug#15917: 24.3.50; manual: mention keys reserved for users
Date: Thu, 29 Oct 2020 15:33:10 +0000

[Message part 1 (text/plain, inline)]

Stefan Kangas <stefan <at> marxist.se> writes:

> Michael Heerdegen <michael_heerdegen <at> 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.

[0001-Say-that-C-A-Za-z-keys-are-reserved-for-users-in-use.patch (text/x-diff, attachment)]

Message #32 received at 15917 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Stefan Kangas <stefan <at> marxist.se>, Michael Heerdegen
 <michael_heerdegen <at> web.de>, Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 15917 <at> debbugs.gnu.org, Paul Smith <psmith <at> gnu.org>
Subject: RE: bug#15917: 24.3.50; manual: mention keys reserved for users
Date: Thu, 29 Oct 2020 09:59:18 -0700 (PDT)

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

Message #35 received at 15917 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Drew Adams <drew.adams <at> oracle.com>,
 Michael Heerdegen <michael_heerdegen <at> web.de>, 
 Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 15917 <at> debbugs.gnu.org, Paul Smith <psmith <at> gnu.org>
Subject: RE: bug#15917: 24.3.50; manual: mention keys reserved for users
Date: Thu, 29 Oct 2020 10:22:28 -0700

Drew Adams <drew.adams <at> 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.

Message #38 received at 15917 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Stefan Kangas <stefan <at> marxist.se>, Michael Heerdegen
 <michael_heerdegen <at> web.de>, Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 15917 <at> debbugs.gnu.org, Paul Smith <psmith <at> gnu.org>
Subject: RE: bug#15917: 24.3.50; manual: mention keys reserved for users
Date: Thu, 29 Oct 2020 10:58:27 -0700 (PDT)

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

Message #41 received at 15917 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Drew Adams <drew.adams <at> oracle.com>,
 Michael Heerdegen <michael_heerdegen <at> web.de>, 
 Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 15917 <at> debbugs.gnu.org, Paul Smith <psmith <at> gnu.org>
Subject: RE: bug#15917: 24.3.50; manual: mention keys reserved for users
Date: Thu, 29 Oct 2020 11:15:11 -0700

Drew Adams <drew.adams <at> 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.

Message #44 received at 15917 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Stefan Kangas <stefan <at> marxist.se>, Michael Heerdegen
 <michael_heerdegen <at> web.de>, Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 15917 <at> debbugs.gnu.org, Paul Smith <psmith <at> gnu.org>
Subject: RE: bug#15917: 24.3.50; manual: mention keys reserved for users
Date: Thu, 29 Oct 2020 11:28:56 -0700 (PDT)

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

Message #47 received at 15917 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Drew Adams <drew.adams <at> oracle.com>,
 Michael Heerdegen <michael_heerdegen <at> web.de>, 
 Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 15917 <at> debbugs.gnu.org, Paul Smith <psmith <at> gnu.org>
Subject: RE: bug#15917: 24.3.50; manual: mention keys reserved for users
Date: Thu, 29 Oct 2020 18:16:34 -0700

Drew Adams <drew.adams <at> 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.

Message #50 received at 15917 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: Michael Heerdegen <michael_heerdegen <at> web.de>, 15917 <at> debbugs.gnu.org,
 Paul Smith <psmith <at> gnu.org>
Subject: Re: bug#15917: 24.3.50; manual: mention keys reserved for users
Date: Fri, 30 Oct 2020 12:47:40 +0100

Stefan Kangas <stefan <at> 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

Message #53 received at 15917 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: michael_heerdegen <at> web.de, 15917 <at> debbugs.gnu.org, stefan <at> marxist.se,
 psmith <at> gnu.org
Subject: Re: bug#15917: 24.3.50; manual: mention keys reserved for users
Date: Fri, 30 Oct 2020 13:51:38 +0200

> From: Lars Ingebrigtsen <larsi <at> gnus.org>
> Date: Fri, 30 Oct 2020 12:47:40 +0100
> Cc: Michael Heerdegen <michael_heerdegen <at> web.de>, 15917 <at> debbugs.gnu.org,
>  Paul Smith <psmith <at> 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?

Message #56 received at 15917 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: michael_heerdegen <at> web.de, 15917 <at> debbugs.gnu.org, stefan <at> marxist.se,
 psmith <at> gnu.org
Subject: Re: bug#15917: 24.3.50; manual: mention keys reserved for users
Date: Fri, 30 Oct 2020 12:55:10 +0100

Eli Zaretskii <eliz <at> 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

Message #59 received at 15917 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Lars Ingebrigtsen <larsi <at> gnus.org>, Eli Zaretskii <eliz <at> gnu.org>
Cc: michael_heerdegen <at> web.de, 15917 <at> debbugs.gnu.org, psmith <at> gnu.org
Subject: Re: bug#15917: 24.3.50; manual: mention keys reserved for users
Date: Fri, 30 Oct 2020 05:09:14 -0700

Lars Ingebrigtsen <larsi <at> gnus.org> writes:

> Eli Zaretskii <eliz <at> 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.

Message #62 received at 15917 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Stefan Kangas <stefan <at> marxist.se>, Michael Heerdegen
 <michael_heerdegen <at> web.de>, Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 15917 <at> debbugs.gnu.org, Paul Smith <psmith <at> gnu.org>
Subject: RE: bug#15917: 24.3.50; manual: mention keys reserved for users
Date: Fri, 30 Oct 2020 12:29:46 -0700 (PDT)

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

Message #65 received at 15917 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Stefan Kangas <stefan <at> marxist.se>, Michael Heerdegen
 <michael_heerdegen <at> web.de>, Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 15917 <at> debbugs.gnu.org, Paul Smith <psmith <at> gnu.org>
Subject: RE: bug#15917: 24.3.50; manual: mention keys reserved for users
Date: Fri, 30 Oct 2020 13:15:08 -0700 (PDT)

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

Message #68 received at 15917 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: michael_heerdegen <at> web.de, 15917 <at> debbugs.gnu.org, larsi <at> gnus.org,
 stefan <at> marxist.se, psmith <at> gnu.org
Subject: Re: bug#15917: 24.3.50; manual: mention keys reserved for users
Date: Fri, 30 Oct 2020 22:20:11 +0200

> Date: Fri, 30 Oct 2020 13:15:08 -0700 (PDT)
> From: Drew Adams <drew.adams <at> oracle.com>
> Cc: 15917 <at> debbugs.gnu.org, Paul Smith <psmith <at> 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.

Message #71 received at 15917 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>, Drew Adams <drew.adams <at> oracle.com>
Cc: michael_heerdegen <at> web.de, 15917 <at> debbugs.gnu.org, larsi <at> gnus.org,
 stefan <at> marxist.se, psmith <at> gnu.org
Subject: RE: bug#15917: 24.3.50; manual: mention keys reserved for users
Date: Fri, 30 Oct 2020 13:50:28 -0700 (PDT)

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

Sure.  If you think that wasn't clear enough then
"GNU Emacs coding convention".  Or "Emacs Lisp
coding convention".  Or "GNU Emacs Lisp coding
convention".

The point is to use the active voice, and to make
clear that this is conventional - a recommendation,
and that code that follows this convention won't
bind these keys.

Message #74 received at 15917 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: michael_heerdegen <at> web.de, 15917 <at> debbugs.gnu.org, larsi <at> gnus.org,
 stefan <at> marxist.se, psmith <at> gnu.org
Subject: Re: bug#15917: 24.3.50; manual: mention keys reserved for users
Date: Fri, 30 Oct 2020 23:03:38 +0200

> Date: Fri, 30 Oct 2020 13:50:28 -0700 (PDT)
> From: Drew Adams <drew.adams <at> oracle.com>
> Cc: stefan <at> marxist.se, michael_heerdegen <at> web.de, larsi <at> gnus.org,
>         15917 <at> debbugs.gnu.org, psmith <at> gnu.org
> 
> > > 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.
> 
> Sure.  If you think that wasn't clear enough then
> "GNU Emacs coding convention".  Or "Emacs Lisp
> coding convention".  Or "GNU Emacs Lisp coding
> convention".

None of the above fits, because these are not coding conventions.

We have a good text proposed already, let's not waste any more time
trying to make it better.

Message #77 received at 15917 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>, Drew Adams <drew.adams <at> oracle.com>
Cc: michael_heerdegen <at> web.de, 15917 <at> debbugs.gnu.org, larsi <at> gnus.org,
 stefan <at> marxist.se, psmith <at> gnu.org
Subject: RE: bug#15917: 24.3.50; manual: mention keys reserved for users
Date: Fri, 30 Oct 2020 14:24:38 -0700 (PDT)

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

Message #80 received at 15917 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: michael_heerdegen <at> web.de, 15917 <at> debbugs.gnu.org,
 Eli Zaretskii <eliz <at> gnu.org>, psmith <at> gnu.org
Subject: bug#15917: 24.3.50; manual: mention keys reserved for users
Date: Sun, 01 Nov 2020 12:52:07 +0100

Stefan Kangas <stefan <at> 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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.