Support a new ["..."] key binding syntax

* doc/lispref/keymaps.texi (Key Sequences):
(Changing Key Bindings): Document the various key syntaxes.

* lisp/emacs-lisp/byte-opt.el (byte-optimize-define-key)
(byte-optimize-define-keymap)
(byte-optimize-define-keymap--define): New functions to check and
expand ["..."] syntax at compile time.

* src/keymap.c (Fdefine_key): Understand the ["..."] syntax.
(syms_of_keymap): Define `kbd' symbols.

1 files changed, 56 insertions, 23 deletions

diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi
index 4277c718fea..899499ed46e 100644
--- a/doc/lispref/keymaps.texi
+++ b/doc/lispref/keymaps.texi
@@ -100,6 +100,16 @@ The @code{kbd} function is very permissive, and will try to return
 something sensible even if the syntax used isn't completely
 conforming.  To check whether the syntax is actually valid, use the
 @code{kbd-valid-p} function.
+
+@code{define-key} also supports using the shorthand syntax
+@samp{["..."]} syntax to define a key.  The string has to be a
+strictly valid @code{kbd} sequence, and if it's not valid, an error
+will be signalled.  For instance, to bind @key{C-c f}, you can say:
+
+@lisp
+(define-key global-map ["C-c f"] #'find-file-literally)
+@end lisp
+
 @end defun
 
 
@@ -1285,24 +1295,46 @@ Binding Conventions}).
 
 @cindex meta character key constants
 @cindex control character key constants
-  In writing the key sequence to rebind, it is good to use the special
-escape sequences for control and meta characters (@pxref{String Type}).
-The syntax @samp{\C-} means that the following character is a control
-character and @samp{\M-} means that the following character is a meta
-character.  Thus, the string @code{"\M-x"} is read as containing a
-single @kbd{M-x}, @code{"\C-f"} is read as containing a single
-@kbd{C-f}, and @code{"\M-\C-x"} and @code{"\C-\M-x"} are both read as
-containing a single @kbd{C-M-x}.  You can also use this escape syntax in
-vectors, as well as others that aren't allowed in strings; one example
-is @samp{[?\C-\H-x home]}.  @xref{Character Type}.
-
-  The key definition and lookup functions accept an alternate syntax for
-event types in a key sequence that is a vector: you can use a list
-containing modifier names plus one base event (a character or function
-key name).  For example, @code{(control ?a)} is equivalent to
-@code{?\C-a} and @code{(hyper control left)} is equivalent to
-@code{C-H-left}.  One advantage of such lists is that the precise
-numeric codes for the modifier bits don't appear in compiled files.
+  @code{define-key} (and other functions that are used to rebind keys)
+understand a number of different syntaxes for the keys.
+
+@table @asis
+@item A vector containing a single string.
+This is the preferred way to represent a key sequence.  Here's a
+couple of examples:
+
+@example
+["C-c M-f"]
+["S-<home>"]
+@end example
+
+The syntax is the same as the one used by Emacs when displaying key
+bindings, for instance in @samp{*Help*} buffers and help texts.
+
+If the syntax isn't valid, an error will be raised when running
+@code{define-key}, or when byte-compiling code that has these calls.
+
+@item A vector containing lists of keys.
+You can use a list containing modifier names plus one base event (a
+character or function key name).  For example, @code{[(control ?a)
+(meta b)]} is equivalent to @kbd{C-a M-b} and @code{[(hyper control
+left)]} is equivalent to @kbd{C-H-left}.
+
+@item A string with control and meta characters.
+Internally, key sequences are often represented as strings using the
+special escape sequences for control and meta characters
+(@pxref{String Type}), but this representation can also be used by
+users when rebinding keys.  A string like @code{"\M-x"} is read as
+containing a single @kbd{M-x}, @code{"\C-f"} is read as containing a
+single @kbd{C-f}, and @code{"\M-\C-x"} and @code{"\C-\M-x"} are both
+read as containing a single @kbd{C-M-x}.
+
+@item a vector of characters.
+This is the other internal representation of key sequences, and
+supports a fuller range of modifiers than the string representation.
+One example is @samp{[?\C-\H-x home]}, which represents the @kbd{C-H-x
+home} key sequence.  @xref{Character Type}.
+@end table
 
   The functions below signal an error if @var{keymap} is not a keymap,
 or if @var{key} is not a string or vector representing a key sequence.
@@ -1344,7 +1376,7 @@ bindings in it:
     @result{} (keymap)
 @end group
 @group
-(define-key map "\C-f" 'forward-char)
+(define-key map ["C-f"] 'forward-char)
     @result{} forward-char
 @end group
 @group
@@ -1354,7 +1386,7 @@ map
 
 @group
 ;; @r{Build sparse submap for @kbd{C-x} and bind @kbd{f} in that.}
-(define-key map (kbd "C-x f") 'forward-word)
+(define-key map ["C-x f"] 'forward-word)
     @result{} forward-word
 @end group
 @group
@@ -1367,14 +1399,14 @@ map
 
 @group
 ;; @r{Bind @kbd{C-p} to the @code{ctl-x-map}.}
-(define-key map (kbd "C-p") ctl-x-map)
+(define-key map ["C-p"] ctl-x-map)
 ;; @code{ctl-x-map}
 @result{} [nil @dots{} find-file @dots{} backward-kill-sentence]
 @end group
 
 @group
 ;; @r{Bind @kbd{C-f} to @code{foo} in the @code{ctl-x-map}.}
-(define-key map (kbd "C-p C-f") 'foo)
+(define-key map ["C-p C-f"] 'foo)
 @result{} 'foo
 @end group
 @group
@@ -1404,7 +1436,8 @@ keys.  Here's a very basic example:
 @lisp
 (define-keymap
   "n" #'forward-line
-  "f" #'previous-line)
+  "f" #'previous-line
+  ["C-c C-c"] #'quit-window)
 @end lisp
 
 This function creates a new sparse keymap, defines the two keystrokes