[Emacs-diffs] /srv/bzr/emacs/trunk r107242: Update Command Loop chapter of Lisp manual.

[Chong Yidong]

------------------------------------------------------------
revno: 107242
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Sat 2012-02-11 21:32:02 +0800
message:
  Update Command Loop chapter of Lisp manual.
  
  * doc/emacs/commands.texi (Command Overview): Mention read-key.
  (Using Interactive, Interactive Call): Minor clarifications.
  (Function Keys, Click Events): Avoid "input stream" terminology.
  (Click Events): Add xref to Window Sizes and Accessing Mouse.
  Clarify column and row components.
  (Accessing Mouse): Add xref to Click Events.  Minor fixes.
  (Special Events): Copyedits.
  
  * doc/emacs/streams.texi (Input Streams): De-document get-file-char.
  (Output Variables): Don't refer to old backquote syntax.
modified:
  doc/lispref/ChangeLog
  doc/lispref/commands.texi
  doc/lispref/streams.texi

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2012-02-11 06:17:22 +0000
+++ b/doc/lispref/ChangeLog     2012-02-11 13:32:02 +0000
@@ -1,5 +1,16 @@
 2012-02-11  Chong Yidong  <address@hidden>
 
+       * commands.texi (Command Overview): Mention read-key.
+       (Using Interactive, Interactive Call): Minor clarifications.
+       (Function Keys, Click Events): Avoid "input stream" terminology.
+       (Click Events): Add xref to Window Sizes and Accessing Mouse.
+       Clarify column and row components.
+       (Accessing Mouse): Add xref to Click Events.  Minor fixes.
+       (Special Events): Copyedits.
+
+       * streams.texi (Input Streams): De-document get-file-char.
+       (Output Variables): Don't refer to old backquote syntax.
+
        * debugging.texi (Debugging): Copyedits.  Describe testcover, ERT.
        (Error Debugging): Note that debug-ignored-errors overrides list
        values of debug-on-error too.  Add xref to Signaling Errors.  Note

=== modified file 'doc/lispref/commands.texi'
--- a/doc/lispref/commands.texi 2012-02-04 21:58:00 +0000
+++ b/doc/lispref/commands.texi 2012-02-11 13:32:02 +0000
@@ -37,13 +37,13 @@
 @node Command Overview
 @section Command Loop Overview
 
-  The first thing the command loop must do is read a key sequence, which
-is a sequence of events that translates into a command.  It does this by
-calling the function @code{read-key-sequence}.  Your Lisp code can also
-call this function (@pxref{Key Sequence Input}).  Lisp programs can also
-do input at a lower level with @code{read-event} (@pxref{Reading One
-Event}) or discard pending input with @code{discard-input}
-(@pxref{Event Input Misc}).
+  The first thing the command loop must do is read a key sequence,
+which is a sequence of input events that translates into a command.
+It does this by calling the function @code{read-key-sequence}.  Lisp
+programs can also call this function (@pxref{Key Sequence Input}).
+They can also read input at a lower level with @code{read-key} or
address@hidden (@pxref{Reading One Event}), or discard pending
+input with @code{discard-input} (@pxref{Event Input Misc}).
 
   The key sequence is translated into a command through the currently
 active keymaps.  @xref{Key Lookup}, for information on how this is done.
@@ -67,12 +67,9 @@
 Lisp code, you must supply the file name string as an ordinary Lisp
 function argument.
 
-  If the command is a string or vector (i.e., a keyboard macro) then
address@hidden is used to execute it.  You can call this
-function yourself (@pxref{Keyboard Macros}).
-
-  To terminate the execution of a running command, type @kbd{C-g}.  This
-character causes @dfn{quitting} (@pxref{Quitting}).
+  If the command is a keyboard macro (i.e.@: a string or vector),
+Emacs executes it using @code{execute-kbd-macro} (@pxref{Keyboard
+Macros}).
 
 @defvar pre-command-hook
 This normal hook is run by the editor command loop before it executes
@@ -175,8 +172,8 @@
 
 @item
 It may be a string; its contents are a sequence of elements separated
-by newlines, one for each address@hidden elements actually
-supply two parameters.}.  Each element consists of a code character
+by newlines, one for each address@hidden elements actually
+supply two arguments.}.  Each element consists of a code character
 (@pxref{Interactive Codes}) optionally followed by a prompt (which
 some code characters use and some ignore).  Here is an example:
 
@@ -575,21 +572,24 @@
 @code{call-interactively}, which reads the arguments and calls the
 command.  You can also call these functions yourself.
 
+  Note that the term ``command'', in this context, refers to an
+interactively callable function (or function-like object), or a
+keyboard macro.  It does not refer to the key sequence used to invoke
+a command (@pxref{Keymaps}).
+
 @defun commandp object &optional for-call-interactively
-Returns @code{t} if @var{object} is suitable for calling interactively;
-that is, if @var{object} is a command.  Otherwise, returns @code{nil}.
-
-Interactively-callable objects include strings and vectors (which are
-treated as keyboard macros), lambda expressions that contain a
-top-level @code{interactive} form (@pxref{Using Interactive}),
-byte-code function objects made from such lambda expressions, autoload
-objects that are declared as interactive (address@hidden fourth
-argument to @code{autoload}), and some primitive functions.
-
-A symbol satisfies @code{commandp} if it has a address@hidden
+This function returns @code{t} if @var{object} is a command.
+Otherwise, it returns @code{nil}.
+
+Commands include strings and vectors (which are treated as keyboard
+macros), lambda expressions that contain a top-level
address@hidden form (@pxref{Using Interactive}), byte-code
+function objects made from such lambda expressions, autoload objects
+that are declared as interactive (address@hidden fourth argument to
address@hidden), and some primitive functions.  Also, a symbol is
+considered a command if it has a address@hidden
 @code{interactive-form} property, or if its function definition
-satisfies @code{commandp}.  Keys and keymaps are not commands.
-Rather, they are used to look up commands (@pxref{Keymaps}).
+satisfies @code{commandp}.
 
 If @var{for-call-interactively} is address@hidden, then
 @code{commandp} returns @code{t} only for objects that
@@ -649,14 +649,14 @@
 
 A string or vector as @var{command} is executed with
 @code{execute-kbd-macro}.  A function is passed to
address@hidden, along with the optional @var{record-flag}
-and @var{keys}.
address@hidden (see above), along with the
address@hidden and @var{keys} arguments.
 
-A symbol is handled by using its function definition in its place.  A
-symbol with an @code{autoload} definition counts as a command if it was
-declared to stand for an interactively callable function.  Such a
-definition is handled by loading the specified library and then
-rechecking the definition of the symbol.
+If @var{command} is a symbol, its function definition is used in its
+place.  A symbol with an @code{autoload} definition counts as a
+command if it was declared to stand for an interactively callable
+function.  Such a definition is handled by loading the specified
+library and then rechecking the definition of the symbol.
 
 The argument @var{special}, if given, means to ignore the prefix
 argument and not clear it.  This is used for executing special events
@@ -1131,9 +1131,9 @@
 @ifnottex
 2**22
 @end ifnottex
-bit in the character code indicates a character typed with
-the alt key held down.  (On some terminals, the key labeled @key{ALT}
-is actually the meta key.)
+bit in the character code indicates a character typed with the alt key
+held down.  (The key labeled @key{Alt} on most keyboards is actually
+treated as the meta key, not this.)
 @end table
 
   It is best to avoid mentioning specific bit numbers in your program.
@@ -1151,10 +1151,10 @@
 
 @cindex function keys
 Most keyboards also have @dfn{function keys}---keys that have names or
-symbols that are not characters.  Function keys are represented in Emacs
-Lisp as symbols; the symbol's name is the function key's label, in lower
-case.  For example, pressing a key labeled @key{F1} places the symbol
address@hidden in the input stream.
+symbols that are not characters.  Function keys are represented in
+Emacs Lisp as symbols; the symbol's name is the function key's label,
+in lower case.  For example, pressing a key labeled @key{F1} generates
+an input event represented by the symbol @code{f1}.
 
 The event type of a function key event is the event symbol itself.
 @xref{Classifying Events}.
@@ -1287,6 +1287,11 @@
  @var{image} (@var{dx} . @var{dy}) (@var{width} . @var{height}))
 @end example
 
address@hidden
+The meanings of these list elements are documented below.
address@hidden Mouse}, for functions that let you easily access these
+elements.
+
 @table @asis
 @item @var{window}
 This is the window in which the click occurred.
@@ -1298,39 +1303,36 @@
 @code{header-line}, @code{vertical-line}, @code{left-margin},
 @code{right-margin}, @code{left-fringe}, or @code{right-fringe}.
 
-In one special case, @var{pos-or-area} is a list containing a symbol (one
-of the symbols listed above) instead of just the symbol.  This happens
-after the imaginary prefix keys for the event are inserted into the
-input stream.  @xref{Key Sequence Input}.
-
+In one special case, @var{pos-or-area} is a list containing a symbol
+(one of the symbols listed above) instead of just the symbol.  This
+happens after the imaginary prefix keys for the event are registered
+by Emacs.  @xref{Key Sequence Input}.
 
 @item @var{x}, @var{y}
-These are the pixel coordinates of the click, relative to
-the top left corner of @var{window}, which is @code{(0 . 0)}.
-For a click on text, these are relative to the top left corner of
-the window's text area.  For the mode or header line, they are
-relative to the top left window edge.  For fringes, margins, and the
-vertical border, @var{x} does not have meaningful data.  For fringes
-and margins, @var{y} is relative to the bottom edge of the header
-line.
+These are the relative pixel coordinates of the click.  For clicks in
+the text area of a window, the coordinate origin @code{(0 . 0)} is
+taken to be the top left corner of the text area.  @xref{Window
+Sizes}.  For clicks in a mode line or header line, the coordinate
+origin is the top left corner of the window itself.  For fringes,
+margins, and the vertical border, @var{x} does not have meaningful
+data.  For fringes and margins, @var{y} is relative to the bottom edge
+of the header line.  In all cases, the @var{x} and @var{y} coordinates
+increase rightward and downward respectively.
 
 @item @var{timestamp}
 This is the time at which the event occurred, in milliseconds.
 
 @item @var{object}
-This is the object on which the click occurred.  It is either
address@hidden if there is no string property, or it has the form
-(@var{string} . @var{string-pos}) when there is a string-type text
-property at the click position.
+This is either @code{nil} if there is no string-type text property at
+the click position, or a cons cell of the form (@var{string}
+. @var{string-pos}) if there is one:
 
 @table @asis
 @item @var{string}
-This is the string on which the click occurred, including any
-properties.
+The string which was clicked on, including any properties.
 
 @item @var{string-pos}
-This is the position in the string on which the click occurred,
-relevant if properties at the click need to be looked up.
+The position in the string where the click occurred.
 @end table
 
 @item @var{text-pos}
@@ -1340,14 +1342,17 @@
 the window.
 
 @item @var{col}, @var{row}
-These are the actual coordinates of the glyph under the @var{x},
address@hidden position, possibly padded with default character width
-glyphs if @var{x} is beyond the last glyph on the line.  For clicks on
-the header or mode line, these are measured from the top left edge of
-the header or mode line.  For clicks on the fringes and on the
-vertical border, these have no meaningful data.  For clicks on the
-margins, @var{col} is measured from the left edge of the margin area
-and @var{row} is measured from the top of the margin area.
+These are the actual column and row coordinate numbers of the glyph
+under the @var{x}, @var{y} position.  If @var{x} lies beyond the last
+column of actual text on its line, @var{col} is reported by adding
+fictional extra columns that have the default character width.  Row 0
+is taken to be the header line if the window has one, or the topmost
+row of the text area otherwise.  Column 0 is taken to be the leftmost
+column of the text area for clicks on a window text area, or the
+leftmost mode line or header line column for clicks there.  For clicks
+on fringes or vertical borders, these have no meaningful data.  For
+clicks on margins, @var{col} is measured from the left edge of the
+margin area and @var{row} is measured from the top of the margin area.
 
 @item @var{image}
 This is the image object on which the click occurred.  It is either
@@ -1885,7 +1890,7 @@
 a mouse button or motion event.
 
   These two functions return the starting or ending position of a
-mouse-button event, as a list of this form:
+mouse-button event, as a list of this form (@pxref{Click Events}):
 
 @example
 (@var{window} @var{pos-or-area} (@var{x} . @var{y}) @var{timestamp}
@@ -1936,12 +1941,13 @@
 cons cell @code{(@var{x} . @var{y})}.  These coordinates are relative
 to the window given by @code{posn-window}.
 
-This example shows how to convert these window-relative coordinates
-into frame-relative coordinates:
+This example shows how to convert the window-relative coordinates in
+the text area of a window into frame-relative coordinates:
 
 @example
 (defun frame-relative-coordinates (position)
-  "Return frame-relative coordinates from POSITION."
+  "Return frame-relative coordinates from POSITION.
+POSITION is assumed to lie in a window text area."
   (let* ((x-y (posn-x-y position))
          (window (posn-window position))
          (edges (window-inside-pixel-edges window)))
@@ -1966,10 +1972,10 @@
 
 @defun posn-actual-col-row position
 Return the actual row and column in @var{position}, as a cons cell
address@hidden(@var{col} . @var{row})}.  The values are the actual row number
-in the window, and the actual character number in that row.  It returns
address@hidden if @var{position} does not include actual positions values.
-You can use @code{posn-col-row} to get approximate values.
address@hidden(@var{col} . @var{row})}.  The values are the actual row and
+column numbers in the window.  @xref{Click Events}, for details.  It
+returns @code{nil} if @var{position} does not include actual positions
+values.
 @end defun
 
 @defun posn-string position
@@ -2680,9 +2686,9 @@
 special meaning in a search, because these events should exit the search
 and then execute normally.
 
-The reliable and easy way to extract events from a key sequence so as to
-put them in @code{unread-command-events} is to use
address@hidden (@pxref{Strings of Events}).
+The reliable and easy way to extract events from a key sequence so as
+to put them in @code{unread-command-events} is to use
address@hidden (see below).
 
 Normally you add events to the front of this list, so that the events
 most recently unread will be reread first.
@@ -2787,28 +2793,29 @@
 @section Special Events
 
 @cindex special events
-Special events are handled at a very low level---as soon as they are
-read.  The @code{read-event} function processes these events itself, and
-never returns them.  Instead, it keeps waiting for the first event
-that is not special and returns that one.
+Certain @dfn{special events} are handled at a very low level---as soon
+as they are read.  The @code{read-event} function processes these
+events itself, and never returns them.  Instead, it keeps waiting for
+the first event that is not special and returns that one.
 
-Events that are handled in this way do not echo, they are never grouped
-into key sequences, and they never appear in the value of
+  Special events do not echo, they are never grouped into key
+sequences, and they never appear in the value of
 @code{last-command-event} or @code{(this-command-keys)}.  They do not
 discard a numeric argument, they cannot be unread with
 @code{unread-command-events}, they may not appear in a keyboard macro,
 and they are not recorded in a keyboard macro while you are defining
 one.
 
-These events do, however, appear in @code{last-input-event} immediately
-after they are read, and this is the way for the event's definition to
-find the actual event.
+  Special events do, however, appear in @code{last-input-event}
+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},
+  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}).
+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/streams.texi'
--- a/doc/lispref/streams.texi  2012-01-19 07:21:25 +0000
+++ b/doc/lispref/streams.texi  2012-02-11 13:32:02 +0000
@@ -266,12 +266,6 @@
 input, and unread it.  Another attempt to read from the stream at this
 point would read @samp{()} and return @code{nil}.
 
address@hidden get-file-char
-This function is used internally as an input stream to read from the
-input file opened by the function @code{load}.  Don't use this function
-yourself.
address@hidden defun
-
 @node Input Functions
 @section Input Functions
 
@@ -702,9 +696,8 @@
 
 @defvar print-quoted
 If this is address@hidden, that means to print quoted forms using
-abbreviated reader syntax.  @code{(quote foo)} prints as @code{'foo},
address@hidden(function foo)} as @code{#'foo}, and backquoted forms print
-using modern backquote syntax.
+abbreviated reader syntax, e.g.@: @code{(quote foo)} prints as
address@hidden'foo}, and @code{(function foo)} as @code{#'foo}.
 @end defvar
 
 @defvar print-escape-newlines