Rant: key sequences aren't specified in the elisp manual.

Rant: key sequences aren't specified in the elisp manual.

[Alan Mackenzie]

Hi, Emacs!

I've just spent ~ 2 hours trying to figure out from the elisp manual the
various ways of binding the key sequence "control-C control-backspace".

This is written in such an abstruse and unclear way in the elisp manual
(page "Changing Key Bindings") that it's probably easier to try every
vaguely plausible combination than to try to figure it out from the
manual.

In fact, I figured out "[?\C-c \C-backspace]" by just such
experimentation.  Trouble is, this is rejected by XEmacs, and I want the
specification to be portable.  So I would like a list of all the ways
Emacs can do it, so that I can try them one by one in XEmacs.

Surely, surely, surely, there should be a clear description of these
things in the elisp manual?

For a start, why is there not a "@section Specifying Key Sequences" under
the @chapter "Keymaps"?  I arrive at "Keymaps", look at the menu, and try
to guess which section describes key sequences.  "Changing Key Bindings"
looks to be the only candidate.

I go into "Changing Key Bindings".  How to specify a key sequence is all
jumbled up with the functions to do this.

Nowhere does it say "you can specify a keysequence with a string".  No,
it kicks off with "In writing the key sequence to rebind, it is good to
use the special escape sequences for control and meta characters".  Is it
plainly obvious that you can use a string, and the place where the string
is described is "Character Type", and that Ctrl, Meta, etc. are actually
parts of characters, rather than being control actions attached to them
somehow?  If it is so obvious then I'm too stupid to be writing Emacs
Lisp, because it's anything but obvious to me.

Nowhere does it say "you can specify a keysequence with a vector".  No,
its first mention of a vector is "You can also use this escape syntax in
vectors, as well as others that aren't allowed in strings; one example is
`[?\C-\H-x home]'".  So on encountering this, I immediately start
searching for the place which DOES say "you can ... with a vector", and
come back to the current page 20 minutes later in a rage, because it's
specified nowhere.

Where is the list of symbols like `home' that one can use in vectors?
Would it be too much to expect them either to be listed, or to have an
@xref to the page where they are listed?  I am confused as to whether
"backspace" is called "backspace", "del", "BS", "delete", and whether it
has to be in lower case, upper case, or it doesn't matter.

Again, what I would like to see is a "@section Specifying Key Sequences",
whose meat would look like something like this:

#########################################################################

@cindex Key Sequences
You can specify Key Sequences in any of the following ways:
@table @bullet
@item A string
......., for example @code{"\C-x5\C-g"}.  You can't specify control or
function keys in a string.  Use a vector or ..... for this.

@item A vector
.......  To apply modifiers to keys, .......  For a complete list of
named keys, @ref{....}.  For example @code{[C-S-up]}. 

@item The @code{kbd} function
......

@item Mouse clicks
......

@item ........
.......

@item ........
.......
@end table

Normally, we recommend you to use ........, but when ...., .... is
easier.   

#########################################################################

I don't have a sufficient overview of key binding to flesh out this text
myself.

Yours in frustration,

-- 
Alan Mackenzie (Munich, Germany)

Re: Rant: key sequences aren't specified in the elisp manual.

[Edward O'Connor]

Alan Mackenzie wrote:

> Hi, Emacs!
>
> I've just spent ~ 2 hours trying to figure out from the elisp manual the
> various ways of binding the key sequence "control-C control-backspace".
[...]
> In fact, I figured out "[?\C-c \C-backspace]" by just such
> experimentation. Trouble is, this is rejected by XEmacs, and I want the
> specification to be portable.

I should think (kbd "C-c C-DEL") would DTRT under both Emacsen.


Ted

-- 
Edward O'Connor
hober0@gmail.com

Ense petit placidam sub libertate quietem.

Re: Rant: key sequences aren't specified in the elisp manual.

[Lennart Borgman]

Alan Mackenzie wrote:

>Hi, Emacs!
>
>I've just spent ~ 2 hours trying to figure out from the elisp manual the
>various ways of binding the key sequence "control-C control-backspace".
>
>This is written in such an abstruse and unclear way in the elisp manual
>(page "Changing Key Bindings") that it's probably easier to try every
>vaguely plausible combination than to try to figure it out from the
>manual.
>
>In fact, I figured out "[?\C-c \C-backspace]" by just such
>experimentation.  Trouble is, this is rejected by XEmacs, and I want the
>specification to be portable.  So I would like a list of all the ways
>Emacs can do it, so that I can try them one by one in XEmacs.
>
>Surely, surely, surely, there should be a clear description of these
>things in the elisp manual?
>
>For a start, why is there not a "@section Specifying Key Sequences" under
>the @chapter "Keymaps"?  I arrive at "Keymaps", look at the menu, and try
>to guess which section describes key sequences.  "Changing Key Bindings"
>looks to be the only candidate.
>  
>
I agree it would be very good to have this in the manual. When I not too 
long ago tried to learn more about this I found the page 
http://www.emacswiki.org/cgi-bin/wiki/KeybindingGuide. The opinion about 
that page seems however to differ.

Though I too lack the knowledge to write this.

Re: Rant: key sequences aren't specified in the elisp manual.

[Kevin Rodgers]

Alan Mackenzie wrote:
 > I've just spent ~ 2 hours trying to figure out from the elisp manual the
 > various ways of binding the key sequence "control-C control-backspace".
 >
 > This is written in such an abstruse and unclear way in the elisp manual
 > (page "Changing Key Bindings") that it's probably easier to try every
 > vaguely plausible combination than to try to figure it out from the
 > manual.

I think you would have had more luck if you'd started with the Emacs
manual.  The "Init Rebinding" node (aka Rebinding Keys in Your Init
File) says:

|    The simplest method for doing this works for ASCII characters and
| Meta-modified ASCII characters only.  This method uses a string to
| represent the key sequence you want to rebind.  For example, here's how
| to bind `C-z' to `shell':
|
|      (global-set-key "\C-z" 'shell)

and

|    When the key sequence includes function keys or mouse button events,
| or non-ASCII characters such as `C-=' or `H-a', you must use the more
| general method of rebinding, which uses a vector to specify the key
| sequence.
|
|    The way to write a vector in Emacs Lisp is with square brackets
| around the vector elements.  Use spaces to separate the elements.  If an
| element is a symbol, simply write the symbol's name--no other
| delimiters or punctuation are needed.  If a vector element is a
| character, write it as a Lisp character constant: `?' followed by the
| character as it would appear in a string.

followed by several examples.

 > In fact, I figured out "[?\C-c \C-backspace]" by just such
 > experimentation.  Trouble is, this is rejected by XEmacs, and I want the
 > specification to be portable.  So I would like a list of all the ways
 > Emacs can do it, so that I can try them one by one in XEmacs.

The "Changing Key Bindings" node of the Emacs Lisp manual says:

|    The key definition and lookup functions accept an alternate syntax
| for event types in a key sequence that is a vector: you can use a list
| containing modifier names plus one base event (a character or function
| key name).  For example, `(control ?a)' is equivalent to `?\C-a' and
| `(hyper control left)' is equivalent to `C-H-left'.  One advantage of
| such lists is that the precise numeric codes for the modifier bits
| don't appear in compiled files.

I don't know why that isn't included in or referenced from the Emacs
manual, or why it doesn't mention that another advantage of the list
syntax is that it's portable to XEmacs.

For your problem, I think the equivalent of "[?\C-c \C-backspace]" is
((control ?c) (control ?\b))

...

 > Where is the list of symbols like `home' that one can use in vectors?
 > Would it be too much to expect them either to be listed, or to have an
 > @xref to the page where they are listed?  I am confused as to whether
 > "backspace" is called "backspace", "del", "BS", "delete", and whether it
 > has to be in lower case, upper case, or it doesn't matter.

See the "Function Keys" node (aka Rebinding Function Keys) in the Emacs
manual.

 > Again, what I would like to see is a "@section Specifying Key Sequences",
 > whose meat would look like something like this:

FWIW, I agree.

-- 
Kevin Rodgers

RE: Rant: key sequences aren't specified in the elisp manual.

[Drew Adams]

     > Again, what I would like to see is a "@section Specifying 
     > Key Sequences", whose meat would look like something like this:
    
    FWIW, I agree.
    
Add my vote too.

Portable key sequences [was: key sequences aren't specified...]

[Stephen J. Turnbull]

Alan Mackenzie wrote:

    >> In fact, I figured out "[?\C-c \C-backspace]" by just such
    >> experimentation. Trouble is, this is rejected by XEmacs, and I
    >> want the specification to be portable.

As far as I know there is no portable way to express all key sequences
in all Emacsen, even of v21 or later vintage.  Even if XEmacs were
disposed to give up the regularity and readability of the vector of
lists of symbols representation, the fact remains that for at least 8
years that representation has been the one guaranteed to work for
arbitrary sequences of gestures, and only a minimum of effort has been
put into string representations.  Which string representations we
support has varied over the last few years, I believe.

>>>>> "Ted" == Edward O'Connor <hober0@gmail.com> writes:

    Ted> I should think (kbd "C-c C-DEL") would DTRT under both
    Ted> Emacsen.

Do you really mean "DEL"?  That's definitely wrong in XEmacs; `(kbd
"C-c C-<backspace>")' is the canonical way to express it (ie, that's
what would be generated by insert-kbd-macro).

Using `kbd' probably is fairly portable, but there's no guarantee that
symbols that are used in recording keyboard macros will be the same.
For example it happens to be the case that both `(kbd "C-BS")' and
`(kbd "C-backspace")' produce `[(control backspace)]' in XEmacs, but
it could easily be true that Emacs only handles "C-BS" while XEmacs
only recognizes "C-backspace".  And "C-<backspace>" is the only thing
guaranteed to work in XEmacs.

-- 
School of Systems and Information Engineering http://turnbull.sk.tsukuba.ac.jp
University of Tsukuba                    Tennodai 1-1-1 Tsukuba 305-8573 JAPAN
               Ask not how you can "do" free software business;
              ask what your business can "do for" free software.

Re: Rant: key sequences aren't specified in the elisp manual.

[Richard M. Stallman]

I agree that there should be a node that describes key sequences.
I think the right place for it is under the Input Events node
in the file commands.texi.

It should describe both the Lisp representation of key sequences and
the various ways of writing them.  Since this is important, it is ok
to duplicate some of the material about key sequences in the Emacs
Manual.  The convenience would oughtweigh the duplication.

I am too overloaded to write one, though.  Could someone else try it?
Please ack this message if you do it.

Re: Portable key sequences

[Stefan Monnier]

> As far as I know there is no portable way to express all key sequences
> in all Emacsen, even of v21 or later vintage.  Even if XEmacs were
> disposed to give up the regularity and readability of the vector of
> lists of symbols representation, the fact remains that for at least 8
> years that representation has been the one guaranteed to work for
> arbitrary sequences of gestures, and only a minimum of effort has been
> put into string representations.  Which string representations we
> support has varied over the last few years, I believe.

Emacs started supporting the vector of lists format in Emacs-20 AFAIK.


        Stefan

Re: Rant: key sequences aren't specified in the elisp manual.

[Richard Stallman]

[I sent this message a week ago but did not get a response.]

I agree that there should be a node that describes key sequences.
I think the right place for it is under the Input Events node
in the file commands.texi.

It should describe both the Lisp representation of key sequences and
the various ways of writing them.  Since this is important, it is ok
to duplicate some of the material about key sequences in the Emacs
Manual.  The convenience would oughtweigh the duplication.

I am too overloaded to write one, though.  Could someone else try it?
Please ack this message if you do it.

Re: Rant: key sequences aren't specified in the elisp manual.

[Richard Stallman]

[I sent this message twice but did not get a response.]

I agree that there should be a node that describes key sequences.
I think the right place for it is under the Input Events node
in the file commands.texi.

It should describe both the Lisp representation of key sequences and
the various ways of writing them.  Since this is important, it is ok
to duplicate some of the material about key sequences in the Emacs
Manual.  The convenience would oughtweigh the duplication.

I am too overloaded to write one, though.  Could someone else try it?
Please ack this message if you do it.