Mercurial > emacs

--- a/lispref/ChangeLog	Thu May 25 00:20:40 2006 +0000
+++ b/lispref/ChangeLog	Thu May 25 04:51:50 2006 +0000
@@ -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.
--- a/lispref/commands.texi	Thu May 25 00:20:40 2006 +0000
+++ b/lispref/commands.texi	Thu May 25 04:51:50 2006 +0000
@@ -362,7 +362,7 @@
 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.
--- a/lispref/help.texi	Thu May 25 00:20:40 2006 +0000
+++ b/lispref/help.texi	Thu May 25 04:51:50 2006 +0000
@@ -497,7 +497,7 @@
 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
--- a/lispref/keymaps.texi	Thu May 25 00:20:40 2006 +0000
+++ b/lispref/keymaps.texi	Thu May 25 04:51:50 2006 +0000
@@ -16,7 +16,7 @@
 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 @@
 * 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
-
-  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 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.
+@cindex key sequence
+
+  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.
+
+  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 @@
 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 @@
 @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 @@
   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