[Emacs-diffs] /srv/bzr/emacs/trunk r109181: Improve documentation of special events and of the "e" interactive spec.

[Eli Zaretskii]

------------------------------------------------------------
revno: 109181
committer: Eli Zaretskii <address@hidden>
branch nick: trunk
timestamp: Sat 2012-07-21 17:48:17 +0300
message:
  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.
modified:
  doc/lispref/ChangeLog
  doc/lispref/commands.texi
  doc/lispref/keymaps.texi

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2012-07-17 07:43:01 +0000
+++ b/doc/lispref/ChangeLog     2012-07-21 14:48:17 +0000
@@ -1,3 +1,10 @@
+2012-07-21  Eli Zaretskii  <address@hidden>
+
+       * 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  <address@hidden>
 
        * text.texi (Insertion): Document insert-char changes.

=== modified file 'doc/lispref/commands.texi'
--- a/doc/lispref/commands.texi 2012-06-23 12:39:23 +0000
+++ b/doc/lispref/commands.texi 2012-07-21 14:48:17 +0000
@@ -379,9 +379,14 @@
 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 @@
 @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 address@hidden if @var{object} is an input event
@@ -2840,11 +2846,11 @@
 definition to find the actual event.
 
   The events types @code{iconify-frame}, @code{make-frame-visible},
address@hidden, @code{drag-n-drop}, and user signals like
address@hidden 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}).
address@hidden, @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

=== modified file 'doc/lispref/keymaps.texi'
--- a/doc/lispref/keymaps.texi  2012-06-17 05:13:40 +0000
+++ b/doc/lispref/keymaps.texi  2012-07-21 14:48:17 +0000
@@ -45,7 +45,8 @@
 
   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 @@
 constituent events; thus, @code{"\C-xl"} represents the key sequence
 @kbd{C-x l}.
 
-  Key sequences containing function keys, mouse button events, or
address@hidden 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 address@hidden characters such as @kbd{C-=} or
address@hidden 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,