Inadequate documentation of key sequences (for global-set-key, etc.)

[Alan Mackenzie]

[I use GNU Emacs 20.2.1 on a Linux Console]

There appears to be no adequate documentation of how to specify a key
sequence, (as used, for example, in global-set-key).

In the info page "Rebinding Keys in Your Init File", there is merely a
partial set of examples, namely: "\C-z", "\C-xl", [?\C-=], [?\H-a], [f7],
[C-mouse-1], [?\C-z], [?\C-x ?l].

This set of examples is insufficient to deduce a working form for, for
example, a key sequence with <control> and <meta> together.  When I was
having trouble with my (Linux console) keyboard setup, (see the thread
"Linux console mode: How do I bind C-M-@ ?" in gnu.emacs.help,
Message-Id: <ucvqe9.95.ln@acm.acm>, from Sun, 27 May 2001), I ended up,
in increasing frustration, trying all of the following for C-M-@:
[?\C-\M-?\@], [?\C-\M-@], [?\M-?\C-?@], [?\M-?\C-@], "?\M-?\C-@",
"\M-\C-@", "\C-\M-@", '(control meta @), [control-meta-@]

I couldn't find anything relevant in the elisp manual either.

I think there should be paragraph (or possibly a separate section) in the
emacs manual with a systematic description of how to specify key
sequences and (??) mouse sequences.  I would be nice if it documented
_all_ forms which emacs accepts, but would probably be OK if it simply
gave a canonical form for a general key sequence.

-- 
Alan Mackenzie (Munich, Germany)
Email: aacm@muuc.dee; to decode, wherever there is a repeated letter
(like "aa"), remove one of them (leaving, say, "a").