Reserved keymap not reserved anymore?

Reserved keymap not reserved anymore?

[Paul Smith]

It used to be that the keymap C-c <letter> was reserved (documented to
be so in the Emacs manual) for user customizations, so I could be sure
that if I set a key in that map, other modes would not conflict with it.

However I just went looking in the Emacs 24 manual and I can't find any
reference to this reservation there.

Was it removed?  Is there a new one?  Is there some new facility which
means it's not needed as much anymore?

RE: Reserved keymap not reserved anymore?

[Drew Adams]

> It used to be that the keymap C-c <letter> was reserved (documented
> to be so in the Emacs manual) for user customizations, so I could be
> sure that if I set a key in that map, other modes would not conflict
> with it.
> 
> However I just went looking in the Emacs 24 manual and I can't find
> any reference to this reservation there.
> 
> Was it removed?  Is there a new one?  Is there some new facility
> which means it's not needed as much anymore?

It is in the Elisp manual, node `Key Binding Conventions', not the
Emacs manual.  I don't think it was ever in the Emacs manual.

Re: Reserved keymap not reserved anymore?

[Paul Smith]

On Sun, 2013-11-17 at 13:14 -0800, Drew Adams wrote:
> > It used to be that the keymap C-c <letter> was reserved (documented
> > to be so in the Emacs manual) for user customizations, so I could be
> > sure that if I set a key in that map, other modes would not conflict
> > with it.
> > 
> > However I just went looking in the Emacs 24 manual and I can't find
> > any reference to this reservation there.
> > 
> > Was it removed?  Is there a new one?  Is there some new facility
> > which means it's not needed as much anymore?
> 
> It is in the Elisp manual, node `Key Binding Conventions', not the
> Emacs manual.  I don't think it was ever in the Emacs manual.

Thanks for the pointer.

It used to be in the Emacs manual though; I found this:

ftp://ftp.gnu.org/old-gnu/Manuals/emacs/html_node/emacs_492.html

That's the Emacs 21.2 manual.  See the last paragraph.

That same "Keymaps" section appears in the current Emacs manual but it's
been largely rewritten, and that section no longer appears.

Cheers!

Re: Reserved keymap not reserved anymore?

[Michael Heerdegen]

Paul Smith <psmith@gnu.org> writes:

> > It is in the Elisp manual, node `Key Binding Conventions', not the
> > Emacs manual.  I don't think it was ever in the Emacs manual.
>
> Thanks for the pointer.
>
> It used to be in the Emacs manual though; I found this:
>
> ftp://ftp.gnu.org/old-gnu/Manuals/emacs/html_node/emacs_492.html
>
> That's the Emacs 21.2 manual.  See the last paragraph.
>
> That same "Keymaps" section appears in the current Emacs manual but it's
> been largely rewritten, and that section no longer appears.

Drew, don't you think it belongs in the user manual?  This is not a
programmer's issue - a user should know which keys he can use for his
bindings, and which are reserved.  Do I miss something?


Regards,

Michael.

Re: Reserved keymap not reserved anymore?

[Paul Smith]

On Sun, 2013-11-17 at 23:45 +0100, Michael Heerdegen wrote:
> Drew, don't you think it belongs in the user manual?  This is not a
> programmer's issue - a user should know which keys he can use for his
> bindings, and which are reserved.  Do I miss something?

I think it belongs in both.  In the Emacs manual, as you say, so users
know about it.  And in the Elisp manual so people writing new modes,
etc. know about the reservation and don't use it.

My $0.02.

RE: Reserved keymap not reserved anymore?

[Drew Adams]

> > Drew, don't you think it belongs in the user manual?  This is not
> > a programmer's issue - a user should know which keys he can use
> > for his bindings, and which are reserved.  Do I miss something?

There are NO keys that are reserved for something other than users.
It's the opposite.  Some keys are reserved _for users_.  ALL keys
are available to users for their own bindings.  (I know that you know
this.  Just want to be clear.)
 
> I think it belongs in both.  In the Emacs manual, as you say, so
> users know about it.  And in the Elisp manual so people writing new
> modes, etc. know about the reservation and don't use it. My $0.02.

My opinion doesn't count for much, but since you ask, no, I don't
really think the whole rundown of key conventions belongs in the user
manual.  What belongs in the user manual somewhere is a cross
reference to the Elisp manual, and some mention of what I said above:
Some key sequences (in particular, `C-c LETTER') are reserved for
users, but users are free to bind any keys they like.

The reason users might want to be aware of the keys that are NOT
reserved for users is that if a user binds such a key it risks
conflicting with some binding established by code, typically
overriding the latter.  But I think the info about the conventions
can be kept only in the Elisp manual and pointed to by the user
manual.

Emacs users includes users who write commands and users who bind
commands to keys, of course, in addition to users who do not.  But
to do either of those things you use Emacs Lisp.  The conventions
about key bindings are most useful to someone writing code that
provides a set of key bindings for, e.g., a mode.  The best place
for the detailed info about key-binding conventions is (only) in
the Elisp manual.

Nevertheless, it can save a user some grief over possible conflicts
if s?he is aware of the keys that risk a conflict.  So a cross
reference makes sense.

Someone else decided long ago to move the info to the Elisp manual.
I have not checked whether there is some info in the Emacs manual
that mentions anything about this or, more importantly, cross
references the Elisp manual details.

If you think that readers of the Emacs manual need a litter more
help with this, `M-x report-emacs-bug' is your friend...

RE: Reserved keymap not reserved anymore?

[Drew Adams]

> If you think that readers of the Emacs manual need a litter
                                                       ^^^^^^
Sheesh - "little".

Re: Reserved keymap not reserved anymore?

[Michael Heerdegen]

Paul Smith <psmith@gnu.org> writes:

> On Sun, 2013-11-17 at 23:45 +0100, Michael Heerdegen wrote:
> > Drew, don't you think it belongs in the user manual?  This is not a
> > programmer's issue - a user should know which keys he can use for his
> > bindings, and which are reserved.  Do I miss something?
>
> I think it belongs in both.  In the Emacs manual, as you say, so users
> know about it.  And in the Elisp manual so people writing new modes,
> etc. know about the reservation and don't use it.

Yes, I didn't mean we should remove it from the Lisp manual ;-)

Ok, I have opened bug#15917 about this issue.  Thanks Paul and Drew.


Regards,

Michael.