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)