RE: defcustom :type to use for a key sequence?

["Drew Adams" <drew.adams@oracle.com>]

    IMO, this is better (using a string type):

      (defcustom the-key "M-SPC" :type 'string)
      (define-key my-map (kbd the-key) 'the-cmd)

Looks good, but how to, for instance, get the equivalent of each of these,
which are not the same?

 (define-key my-map [S-tab] 'the-cmd)
 (define-key my-map [S-iso-lefttab] 'the-cmd)
 (define-key my-map [(shift ?\t)] 'the-cmd)

I guess the last one would be done using S-TAB as input (so, `(kbd
"S-TAB")'). (Is that correct?) But how would you input, say, the first one
as a string? Would you input <S-tab> (so, `(kbd "<S-tab>")')? Or is it
S-<tab> (so, `(kbd "S-<tab>")')? Or are those two different keys, both of
which are different from S-TAB?

Obviously, I'm not real clear on `kbd'.  I don't find the Elisp manual too
helpful on that either.

If the external string (print) representation were used, as I think you
suggest, then users would need to know the various string representations.
That sounds like a good way to go. However, IMO, the presentation in the
Elisp manual would need to be a bit better, if we start expecting users to
use things like "<S-tab>" vs "S-TAB" to define bindings.

Also, would the Emacs (not just Elisp) manual then also need to describe the
string (print) representations? Maybe it's normal that only the Elisp manual
describes key-binding syntax, but if we expect Customize users to specify
key sequences using string (print) representations, then they will need to
know the syntax. I don't know - I guess we could assume that such
Customization would be for Elisp-savvy users (after all, we also allow :type
`sexp').

In any case, even the Elisp manual doesn't explain the `kbd' syntax clearly,
IMO. It gives a few simple examples (no menu items, for example), says that
the syntax is "the syntax used in this manual" (whatever that is - where is
that described?), and ends by sending you to node Edit Keyboard Macro(emacs)
for the full syntax explanation ("same syntax that Edit Macro mode uses for
editing keyboard macros"). However, I don't see any such syntax description
at the referenced node, Edit Keyboard Macro. Is that perhaps the wrong xref?

I'd like to see a good, clear description of how to specify any and all
bindings with `kbd'. It also deserves a better place than the Info page
"Keymap Terminology". This is about key-sequence syntax for use with `kbd';
it's not about keymap terminology.

(Did I notice a thread here lately about the manual being updated in this
regard? I'm looking at an old manual from July, so my comments here might be
out-of-date.)

    It would be very useful to have a :type 'kbd that could DTRT
    re. :set etc.

Yes. Although the name should be something more readable, such as :type
'key-sequence. It's bad enough that we use "key sequence" to stand for mouse
and menu events too, but "kbd" emphasizes the _keyboard_ far too much. Also,
there is no reason to use an abbreviation here.

    >         (defcustom the-key [(meta ?\ )] "...")
    >         (define-key my-map the-key 'the-cmd))
    >
    >         Suppose I have this:
    >
    >         (defcustom the-key [(meta ?\ )] "...")
    >         (define-key my-map the-key 'the-cmd))
    >
    >         A user might customize which key sequence is bound to
    >         `the-cmd'.
    >
    >         What :type is appropriate for the defcustom? I don't
    >         see a type ready-made for key sequences.  Just `string'?
    >         Or is a `choice' of `string' and (what kind of?)
    >         `vector' appropriate?  How can the :type allow for any
    >         key sequence (besides using just `sexp')?