Improve documentation of special events and of the "e" interactive spec.

 doc/lispref/commands.texi (Special Events): Mention language-change event.
 (Input Events, Interactive Codes):
 doc/lispref/keymaps.texi (Key Sequences): Mention events that are
 non-keyboard but also non-mouse events.

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index bc01d64c509dd4827dc0528163d819dcb6c7561c..addf622d21d031e07489cc3d3f761e9a8307e06a 100644 (file)
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,10 @@
+2012-07-21  Eli Zaretskii  <eliz@gnu.org>
+
+       * commands.texi (Special Events): Mention language-change event.
+       (Input Events, Interactive Codes):
+       * keymaps.texi (Key Sequences): Mention events that are
+       non-keyboard but also non-mouse events.
+
 2012-07-17  Chong Yidong  <cyd@gnu.org>
 
        * text.texi (Insertion): Document insert-char changes.

diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi
index a5fb4638c9d6debac5d37792cfb81a18b83636c3..7e24de94fbed8515215550fe45006d92adfb5789 100644 (file)
--- a/doc/lispref/commands.texi
+++ b/doc/lispref/commands.texi
@@ -379,9 +379,14 @@ current buffer, @code{default-directory} (@pxref{File Name Expansion}).
 Existing, Completion, Default, Prompt.
 
 @item e
-The first or next mouse event in the key sequence that invoked the command.
-More precisely, @samp{e} gets events that are lists, so you can look at
-the data in the lists.  @xref{Input Events}.  No I/O.
+The first or next non-keyboard event in the key sequence that invoked
+the command.  More precisely, @samp{e} gets events that are lists, so
+you can look at the data in the lists.  @xref{Input Events}.  No I/O.
+
+You use @samp{e} for mouse events and for special system events
+(@pxref{Misc Events}).  The event list that the command receives
+depends on the event.  @xref{Input Events}, which describes the forms
+of the list for each event in the corresponding subsections.
 
 You can use @samp{e} more than once in a single command's interactive
 specification.  If the key sequence that invoked the command has
@@ -972,9 +977,10 @@ moving point out of these sequences is completely turned off.
 @cindex input events
 
 The Emacs command loop reads a sequence of @dfn{input events} that
-represent keyboard or mouse activity.  The events for keyboard activity
-are characters or symbols; mouse events are always lists.  This section
-describes the representation and meaning of input events in detail.
+represent keyboard or mouse activity, or system events sent to Emacs.
+The events for keyboard activity are characters or symbols; other
+events are always lists.  This section describes the representation
+and meaning of input events in detail.
 
 @defun eventp object
 This function returns non-@code{nil} if @var{object} is an input event
@@ -2840,11 +2846,11 @@ immediately after they are read, and this is the way for the event's
 definition to find the actual event.
 
   The events types @code{iconify-frame}, @code{make-frame-visible},
-@code{delete-frame}, @code{drag-n-drop}, and user signals like
-@code{sigusr1} are normally handled in this way.  The keymap which
-defines how to handle special events---and which events are
-special---is in the variable @code{special-event-map} (@pxref{Active
-Keymaps}).
+@code{delete-frame}, @code{drag-n-drop}, @code{language-change}, and
+user signals like @code{sigusr1} are normally handled in this way.
+The keymap which defines how to handle special events---and which
+events are special---is in the variable @code{special-event-map}
+(@pxref{Active Keymaps}).
 
 @node Waiting
 @section Waiting for Elapsed Time or Input

diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi
index ac3d9e4758087fdf5e9eeed30031eb7dcfcc984d..ad7092a9ed77037057026c36aea95b50bc67c26d 100644 (file)
--- a/doc/lispref/keymaps.texi
+++ b/doc/lispref/keymaps.texi
@@ -45,7 +45,8 @@ is found.  The whole process is called @dfn{key lookup}.
 
   A @dfn{key sequence}, or @dfn{key} for short, is a sequence of one
 or more input events that form a unit.  Input events include
-characters, function keys, and mouse actions (@pxref{Input Events}).
+characters, function keys, mouse actions, or system events external to
+Emacs, such as @code{iconify-frame} (@pxref{Input Events}).
 The Emacs Lisp representation for a key sequence is a string or
 vector.  Unless otherwise stated, any Emacs Lisp function that accepts
 a key sequence as an argument can handle both representations.
@@ -62,9 +63,10 @@ sequence is the concatenation of the string representations of the
 constituent events; thus, @code{"\C-xl"} represents the key sequence
 @kbd{C-x l}.
 
-  Key sequences containing function keys, mouse button events, or
-non-@acronym{ASCII} characters such as @kbd{C-=} or @kbd{H-a} cannot be
-represented as strings; they have to be represented as vectors.
+  Key sequences containing function keys, mouse button events, system
+events, or non-@acronym{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
 an input event, in its Lisp form.  @xref{Input Events}.  For example,