Describing Characters for Help Messages
=======================================
These functions convert events, key sequences, or characters to
textual descriptions. These descriptions are useful for including
arbitrary text characters or key sequences in messages, because they
convert non-printing and whitespace characters to sequences of printing
characters. The description of a non-whitespace printing character is
the character itself.
- Function: key-description sequence
This function returns a string containing the Emacs standard
notation for the input events in SEQUENCE. The argument SEQUENCE
may be a string, vector or list. Note:Input Events, for more
information about valid events. See also the examples for
`single-key-description', below.
- Function: single-key-description event &optional no-angles
This function returns a string describing EVENT in the standard
Emacs notation for keyboard input. A normal printing character
appears as itself, but a control character turns into a string
starting with `C-', a meta character turns into a string starting
with `M-', and space, tab, etc. appear as `SPC', `TAB', etc. A
function key symbol appears inside angle brackets `<...>'. An
event that is a list appears as the name of the symbol in the CAR
of the list, inside angle brackets.
If the optional argument NO-ANGLES is non-`nil', the angle
brackets around function keys and event symbols are omitted; this
is for compatibility with old versions of Emacs which didn't use
the brackets.
(single-key-description ?\C-x)
=> "C-x"
(key-description "\C-x \M-y \n \t \r \f123")
=> "C-x SPC M-y SPC C-j SPC TAB SPC RET SPC C-l 1 2 3"
(single-key-description 'delete)
=> "<delete>"
(single-key-description 'C-mouse-1)
=> "<C-mouse-1>"
(single-key-description 'C-mouse-1 t)
=> "C-mouse-1"
- Function: text-char-description character
This function returns a string describing CHARACTER in the
standard Emacs notation for characters that appear in text--like
`single-key-description', except that control characters are
represented with a leading caret (which is how control characters
in Emacs buffers are usually displayed).
(text-char-description ?\C-c)
=> "^C"
(text-char-description ?\M-m)
=> "M-m"
(text-char-description ?\C-\M-m)
=> "M-^M"
- Function: read-kbd-macro string
This function is used mainly for operating on keyboard macros, but
it can also be used as a rough inverse for `key-description'. You
call it with a string containing key descriptions, separated by
spaces; it returns a string or vector containing the corresponding
events. (This may or may not be a single valid key sequence,
depending on what events you use; Note:Keymap Terminology.)