* keymaps.texi (Key Sequences): Renamed from Keymap Terminology.

	Explain string and vector representations of key sequences

	* keymaps.texi (Changing Key Bindings):
	* commands.texi (Interactive Codes, Interactive Codes):
	* help.texi (Describing Characters): Refer to it.

4 files changed, 55 insertions, 26 deletions

diff --git a/lispref/ChangeLog b/lispref/ChangeLog
index de08e3fb459..ec852df16fe 100644
--- a/lispref/ChangeLog
+++ b/lispref/ChangeLog
@@ -1,3 +1,12 @@
+2006-05-25  Chong Yidong  <cyd@stupidchicken.com>
+
+        * keymaps.texi (Key Sequences): Renamed from Keymap Terminology.
+        Explain string and vector representations of key sequences
+
+        * keymaps.texi (Changing Key Bindings): 
+        * commands.texi (Interactive Codes, Interactive Codes): 
+        * help.texi (Describing Characters): Refer to it.
+
 2006-05-23  Luc Teirlinck  <teirllm@auburn.edu>
 
         * frames.texi (Pointer Shape): @end table -> @end defvar.
diff --git a/lispref/commands.texi b/lispref/commands.texi
index fa5d95f0408..0723c368bba 100644
--- a/lispref/commands.texi
+++ b/lispref/commands.texi
@@ -362,7 +362,7 @@ An irrelevant argument.  This code always supplies @code{nil} as
 the argument's value.  No I/O.
 
 @item k
-A key sequence (@pxref{Keymap Terminology}).  This keeps reading events
+A key sequence (@pxref{Key Sequences}).  This keeps reading events
 until a command (or undefined command) is found in the current key
 maps.  The key sequence argument is represented as a string or vector.
 The cursor does not move into the echo area.  Prompt.
diff --git a/lispref/help.texi b/lispref/help.texi
index 0fe996dfd7c..6173c746d1e 100644
--- a/lispref/help.texi
+++ b/lispref/help.texi
@@ -497,7 +497,7 @@ can also be used as a rough inverse for @code{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; @pxref{Keymap Terminology}.)  If @var{need-vector} is
+events you use; @pxref{Key Sequences}.)  If @var{need-vector} is
 non-@code{nil}, the return value is always a vector.
 @end defun
 
diff --git a/lispref/keymaps.texi b/lispref/keymaps.texi
index 39a57eddf13..808f3a617a6 100644
--- a/lispref/keymaps.texi
+++ b/lispref/keymaps.texi
@@ -16,7 +16,7 @@ to look up the next input event; this continues until a command is
 found.  The whole process is called @dfn{key lookup}.
 
 @menu
-* Keymap Terminology::          Definitions of terms pertaining to keymaps.
+* Key Sequences::               What a key sequence looks like as a Lisp object.
 * Format of Keymaps::           What a keymap looks like as a Lisp object.
 * Creating Keymaps::            Functions to create and copy keymaps.
 * Inheritance and Keymaps::     How one keymap can inherit the bindings
@@ -37,32 +37,26 @@ found.  The whole process is called @dfn{key lookup}.
 * Menu Keymaps::                Defining a menu as a keymap.
 @end menu
 
-@node Keymap Terminology
-@section Keymap Terminology
+@node Key Sequences
+@section Key Sequences
 @cindex key
 @cindex keystroke
 @cindex key binding
 @cindex binding of a key
 @cindex complete key
 @cindex undefined key
+@cindex key sequence
 
-  A @dfn{keymap} is a table mapping event types to definitions (which
-can be any Lisp objects, though only certain types are meaningful for
-execution by the command loop).  Given an event (or an event type) and a
-keymap, Emacs can get the event's definition.  Events include
-characters, function keys, and mouse actions (@pxref{Input Events}).
-
-  A sequence of input events that form a unit is called a
-@dfn{key sequence}, or @dfn{key} for short.  A sequence of one event
-is always a key sequence, and so are some multi-event sequences.
+  A keymap determines a binding or definition for a set of @dfn{key
+sequences}, or @dfn{keys} for short.  A key sequence is a sequence of
+one or more input events that form a unit.
 
-  A keymap determines a binding or definition for any key sequence.  If
-the key sequence is a single event, its binding is the definition of the
-event in the keymap.  The binding of a key sequence of more than one
-event is found by an iterative process: the binding of the first event
-is found, and must be a keymap; then the second event's binding is found
-in that keymap, and so on until all the events in the key sequence are
-used up.
+  If a keymap binds a key sequence consisting of a single event, its
+binding is the definition of that event.  The binding of a key
+sequence of more than one event is found by an iterative process: the
+binding of the first event is found, and must be a keymap; then the
+second event's binding is found in that keymap, and so on until all
+the events in the key sequence are used up.
 
   If the binding of a key sequence is a keymap, we call the key sequence
 a @dfn{prefix key}.  Otherwise, we call it a @dfn{complete key} (because
@@ -99,8 +93,28 @@ keymaps shadow both local and global keymaps.  @xref{Active Keymaps},
 for details.
 
   The Emacs Lisp representation for a key sequence is a string or vector.
-You can enter key sequence constants using the ordinary string or vector
-representation; it is also convenient to use @code{kbd}:
+
+  In the string representation, alphanumeric characters ordinarily
+stand for themselves; for example, @code{"a"} represents @key{a} and
+and @code{"1"} represents @key{1}.  Control character events are
+prefixed by the substring @code{"\C-"}, and meta characters by
+@code{"\M-"}; for example, @code{"\C-x"} represents the key @kbd{C-x}.
+In addition, the @kbd{<TAB>}, @kbd{<RET>}, @kbd{<ESC>}, and
+@kbd{<DEL>} events are represented by @code{"\t"}, @code{"\r"},
+@code{"\e"}, and @code{"\d"} respectively.  The string representation
+of a complete key sequence is then obtained by concatenating the
+string representations of each constituent event; thus, @code{"\C-x"}
+represents the key sequence @kbd{C-x}.
+
+  Key sequences containing function keys, mouse button events, or
+non-ASCII characters such as @kbd{C-=} or @kbd{H-a} cannot be
+represented as strings; they have to be represented as vectors.
+
+  In the vector representation, each element of the vector represents
+a consecutive input element, in its Lisp form.  @xref{Input Events}.
+For example, ordinary keyboard events are represented by Lisp
+characters (@pxref{Keyboard Events}), so the character @code{?a}
+represents @key{a}.
 
 @defmac kbd keyseq-text
 This macro converts the text @var{keyseq-text} (a string constant)
@@ -129,7 +143,13 @@ Macro,,, emacs, The GNU Emacs Manual}).
 @cindex full keymap
 @cindex sparse keymap
 
-  A keymap is a list whose @sc{car} is the symbol @code{keymap}.  The
+  A @dfn{keymap} is a table mapping event types to definitions (which
+can be any Lisp objects, though only certain types are meaningful for
+execution by the command loop).  Given an event (or an event type) and a
+keymap, Emacs can get the event's definition.  Events include
+characters, function keys, and mouse actions (@pxref{Input Events}).
+
+  Each keymap is a list whose @sc{car} is the symbol @code{keymap}.  The
 remaining elements of the list define the key bindings of the keymap.
 A symbol whose function definition is a keymap is also a keymap.  Use
 the function @code{keymapp} (see below) to test whether an object is a
@@ -1197,8 +1217,8 @@ numeric codes for the modifier bits don't appear in compiled files.
   For the functions below, an error is signaled if @var{keymap} is not
 a keymap or if @var{key} is not a string or vector representing a key
 sequence.  You can use event types (symbols) as shorthand for events
-that are lists.  The @code{kbd} macro (@pxref{Keymap Terminology}) is
-a convenient way to specify the key sequence.
+that are lists.  The @code{kbd} macro (@pxref{Key Sequences}) is a
+convenient way to specify the key sequence.
 
 @defun define-key keymap key binding
 This function sets the binding for @var{key} in @var{keymap}.  (If