bug#15917: 24.3.50; manual: mention keys reserved for users

bug#15917: 24.3.50; manual: mention keys reserved for users

[Michael Heerdegen]

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)

bug#15917: 24.3.50; manual: mention keys reserved for users

[Drew Adams]

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

bug#15917: 24.3.50; manual: mention keys reserved for users

[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

bug#15917: 24.3.50; manual: mention keys reserved for users

[Andreas Röhler]

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.

bug#15917: 24.3.50; manual: mention keys reserved for users

[Stefan Kangas]

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?

bug#15917: 24.3.50; manual: mention keys reserved for users

[Lars Ingebrigtsen]

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

bug#15917: 24.3.50; manual: mention keys reserved for users

[Michael Heerdegen]

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.

bug#15917: 24.3.50; manual: mention keys reserved for users

[Stefan Kangas]

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

bug#15917: 24.3.50; manual: mention keys reserved for users

[Stefan Kangas]

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

bug#15917: 24.3.50; manual: mention keys reserved for users

[Drew Adams]

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

bug#15917: 24.3.50; manual: mention keys reserved for users

[Stefan Kangas]

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.

bug#15917: 24.3.50; manual: mention keys reserved for users

[Drew Adams]

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

bug#15917: 24.3.50; manual: mention keys reserved for users

[Stefan Kangas]

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.

bug#15917: 24.3.50; manual: mention keys reserved for users

[Drew Adams]

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

bug#15917: 24.3.50; manual: mention keys reserved for users

[Stefan Kangas]

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.

bug#15917: 24.3.50; manual: mention keys reserved for users

[Lars Ingebrigtsen]

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

bug#15917: 24.3.50; manual: mention keys reserved for users

[Eli Zaretskii]

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

bug#15917: 24.3.50; manual: mention keys reserved for users

[Lars Ingebrigtsen]

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

bug#15917: 24.3.50; manual: mention keys reserved for users

[Stefan Kangas]

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.

bug#15917: 24.3.50; manual: mention keys reserved for users

[Drew Adams]

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

bug#15917: 24.3.50; manual: mention keys reserved for users

[Drew Adams]

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

bug#15917: 24.3.50; manual: mention keys reserved for users

[Eli Zaretskii]

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

bug#15917: 24.3.50; manual: mention keys reserved for users

[Drew Adams]

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

bug#15917: 24.3.50; manual: mention keys reserved for users

[Eli Zaretskii]

> Date: Fri, 30 Oct 2020 13:50:28 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: stefan@marxist.se, michael_heerdegen@web.de, larsi@gnus.org,
>         15917@debbugs.gnu.org, psmith@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.

bug#15917: 24.3.50; manual: mention keys reserved for users

[Drew Adams]

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

bug#15917: 24.3.50; manual: mention keys reserved for users

[Lars Ingebrigtsen]

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