unofficial mirror of emacs-devel@gnu.org 
 help / color / mirror / code / Atom feed
* Rant: key sequences aren't specified in the elisp manual.
@ 2005-11-17 22:29 Alan Mackenzie
  2005-11-17 23:17 ` Edward O'Connor
                   ` (5 more replies)
  0 siblings, 6 replies; 10+ messages in thread
From: Alan Mackenzie @ 2005-11-17 22:29 UTC (permalink / raw)


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)

^ permalink raw reply	[flat|nested] 10+ messages in thread

end of thread, other threads:[~2005-12-11  5:03 UTC | newest]

Thread overview: 10+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2005-11-17 22:29 Rant: key sequences aren't specified in the elisp manual Alan Mackenzie
2005-11-17 23:17 ` Edward O'Connor
2005-11-19 15:48   ` Portable key sequences [was: key sequences aren't specified...] Stephen J. Turnbull
2005-11-20 17:07     ` Portable key sequences Stefan Monnier
2005-11-17 23:19 ` Rant: key sequences aren't specified in the elisp manual Lennart Borgman
2005-11-17 23:19 ` Kevin Rodgers
2005-11-17 23:30   ` Drew Adams
2005-11-19 23:26 ` Richard M. Stallman
2005-11-27  0:31 ` Richard Stallman
2005-12-11  5:03 ` Richard Stallman

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).