Initial revision

1 files changed, 2257 insertions, 0 deletions

diff --git a/lispref/commands.texi b/lispref/commands.texi
new file mode 100644
index 00000000000..19eb0340df7
--- /dev/null
+++ b/lispref/commands.texi
@@ -0,0 +1,2257 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc. 
+@c See the file elisp.texi for copying conditions.
+@setfilename ../info/commands
+@node Command Loop, Keymaps, Minibuffers, Top
+@chapter Command Loop
+@cindex editor command loop
+@cindex command loop
+
+  When you run Emacs, it enters the @dfn{editor command loop} almost
+immediately.  This loop reads key sequences, executes their definitions,
+and displays the results.  In this chapter, we describe how these things
+are done, and the subroutines that allow Lisp programs to do them.  
+
+@menu
+* Command Overview::    How the command loop reads commands.
+* Defining Commands::   Specifying how a function should read arguments.
+* Interactive Call::    Calling a command, so that it will read arguments.
+* Command Loop Info::   Variables set by the command loop for you to examine.
+* Input Events::        What input looks like when you read it.
+* Reading Input::       How to read input events from the keyboard or mouse.
+* Waiting::             Waiting for user input or elapsed time.
+* Quitting::            How @kbd{C-g} works.  How to catch or defer quitting.
+* Prefix Command Arguments::    How the commands to set prefix args work.
+* Recursive Editing::   Entering a recursive edit,
+                          and why you usually shouldn't.
+* Disabling Commands::  How the command loop handles disabled commands.
+* Command History::     How the command history is set up, and how accessed.
+* Keyboard Macros::     How keyboard macros are implemented.
+@end menu
+
+@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{Peeking and Discarding}).
+
+  The key sequence is translated into a command through the currently
+active keymaps.  @xref{Key Lookup}, for information on how this is done.
+The result should be a keyboard macro or an interactively callable
+function.  If the key is @kbd{M-x}, then it reads the name of another
+command, which is used instead.  This is done by the command
+@code{execute-extended-command} (@pxref{Interactive Call}).
+
+  Once the command is chosen, it must be executed, which includes
+reading arguments to be given to it.  This is done by calling
+@code{command-execute} (@pxref{Interactive Call}).  For commands written
+in Lisp, the @code{interactive} specification says how to read the
+arguments.  This may use the prefix argument (@pxref{Prefix Command
+Arguments}) or may read with prompting in the minibuffer
+(@pxref{Minibuffers}).  For example, the command @code{find-file} has an
+@code{interactive} specification which says to read a file name using
+the minibuffer.  The command's function body does not use the
+minibuffer; if you call this command from Lisp code as a function, 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
+@code{execute-kbd-macro} is used to execute it.  You can call this
+function yourself (@pxref{Keyboard Macros}).
+
+  If a command runs away, typing @kbd{C-g} terminates its execution
+immediately.  This is called @dfn{quitting} (@pxref{Quitting}).
+
+@defvar pre-command-hook
+The editor command loop runs this normal hook before each command.
+@end defvar
+
+@defvar post-command-hook
+The editor command loop runs this normal hook after each command,
+and also when the command loop is entered, or reentered after
+an error or quit.
+@end defvar
+
+@node Defining Commands
+@section Defining Commands
+@cindex defining commands
+@cindex commands, defining
+@cindex functions, making them interactive
+@cindex interactive function
+
+  A Lisp function becomes a command when its body contains, at top
+level, a form which calls the special form @code{interactive}.  This
+form does nothing when actually executed, but its presence serves as a
+flag to indicate that interactive calling is permitted.  Its argument
+controls the reading of arguments for an interactive call.
+
+@menu
+* Using Interactive::     General rules for @code{interactive}.
+* Interactive Codes::     The standard letter-codes for reading arguments
+                             in various ways.
+* Interactive Examples::  Examples of how to read interactive arguments.
+@end menu
+
+@node Using Interactive
+@subsection Using @code{interactive}
+
+  This section describes how to write the @code{interactive} form that
+makes a Lisp function an interactively-callable command.
+
+@defspec interactive arg-descriptor
+@cindex argument descriptors
+This special form declares that the function in which it appears is a
+command, and that it may therefore be called interactively (via
+@kbd{M-x} or by entering a key sequence bound to it).  The argument
+@var{arg-descriptor} declares the way the arguments to the command are
+to be computed when the command is called interactively.
+
+A command may be called from Lisp programs like any other function, but
+then the arguments are supplied by the caller and @var{arg-descriptor}
+has no effect.
+
+The @code{interactive} form has its effect because the command loop
+(actually, its subroutine @code{call-interactively}) scans through the
+function definition looking for it, before calling the function.  Once
+the function is called, all its body forms including the
+@code{interactive} form are executed, but at this time
+@code{interactive} simply returns @code{nil} without even evaluating its
+argument.
+@end defspec
+
+There are three possibilities for the argument @var{arg-descriptor}:
+
+@itemize @bullet
+@item
+It may be omitted or @code{nil}; then the command is called with no
+arguments.  This leads quickly to an error if the command requires one
+or more arguments.
+
+@item
+It may be a Lisp expression that is not a string; then it should be a
+form that is evaluated to get a list of arguments to pass to the
+command.
+@cindex argument evaluation form
+
+@item
+@cindex argument prompt
+It may be a string; then its contents should consist of a code character
+followed by a prompt (which some code characters use and some ignore).
+The prompt ends either with the end of the string or with a newline.
+Here is a simple example:
+
+@smallexample
+(interactive "bFrobnicate buffer: ")
+@end smallexample
+
+@noindent
+The code letter @samp{b} says to read the name of an existing buffer,
+with completion.  The buffer name is the sole argument passed to the
+command.  The rest of the string is a prompt.
+
+If there is a newline character in the string, it terminates the prompt.
+If the string does not end there, then the rest of the string should
+contain another code character and prompt, specifying another argument.
+You can specify any number of arguments in this way.
+
+@c Emacs 19 feature
+The prompt string can use @samp{%} to include previous argument values
+in the prompt.  This is done using @code{format} (@pxref{Formatting
+Strings}).  For example, here is how you could read the name of an
+existing buffer followed by a new name to give to that buffer:
+
+@smallexample
+@group
+(interactive "bBuffer to rename: \nsRename buffer %s to: ")
+@end group
+@end smallexample
+
+@cindex @samp{*} in interactive
+@kindex buffer-read-only
+If the first character in the string is @samp{*}, then an error is
+signaled if the buffer is read-only.
+
+@cindex @samp{@@} in interactive
+@c Emacs 19 feature
+If the first character in the string is @samp{@@}, and if the key
+sequence used to invoke the command includes any mouse events, then
+the window associated with the first of those events is selected
+before the command is run.
+
+You can use @samp{*} and @samp{@@} together; the order does not matter.
+Actual reading of arguments is controlled by the rest of the prompt
+string (starting with the first character that is not @samp{*} or
+@samp{@@}).
+@end itemize
+
+@node Interactive Codes
+@comment  node-name,  next,  previous,  up
+@subsection Code Characters for @code{interactive}
+@cindex interactive code description
+@cindex description for interactive codes
+@cindex codes, interactive, description of
+@cindex characters for interactive codes
+
+  The code character descriptions below contain a number of key words,
+defined here as follows:
+
+@table @b
+@item Completion
+@cindex interactive completion
+Provide completion.  @key{TAB}, @key{SPC}, and @key{RET} perform name
+completion because the argument is read using @code{completing-read}
+(@pxref{Completion}).  @kbd{?} displays a list of possible completions.
+
+@item Existing
+Require the name of an existing object.  An invalid name is not
+accepted; the commands to exit the minibuffer do not exit if the current
+input is not valid.
+
+@item Default
+@cindex default argument string
+A default value of some sort is used if the user enters no text in the
+minibuffer.  The default depends on the code character.
+
+@item No I/O
+This code letter computes an argument without reading any input.
+Therefore, it does not use a prompt string, and any prompt string you
+supply is ignored.
+
+@item Prompt
+A prompt immediately follows the code character.  The prompt ends either
+with the end of the string or with a newline.
+
+@item Special
+This code character is meaningful only at the beginning of the
+interactive string, and it does not look for a prompt or a newline.
+It is a single, isolated character.
+@end table
+
+@cindex reading interactive arguments
+  Here are the code character descriptions for use with @code{interactive}:
+
+@table @samp
+@item *
+Signal an error if the current buffer is read-only.  Special.
+
+@item @@
+Select the window mentioned in the first mouse event in the key
+sequence that invoked this command.  Special.
+
+@item a
+A function name (i.e., a symbol which is @code{fboundp}).  Existing,
+Completion, Prompt.
+
+@item b
+The name of an existing buffer.  By default, uses the name of the
+current buffer (@pxref{Buffers}).  Existing, Completion, Default,
+Prompt.
+
+@item B
+A buffer name.  The buffer need not exist.  By default, uses the name of
+a recently used buffer other than the current buffer.  Completion,
+Prompt.
+
+@item c
+A character.  The cursor does not move into the echo area.  Prompt.
+
+@item C
+A command name (i.e., a symbol satisfying @code{commandp}).  Existing,
+Completion, Prompt.
+
+@item d
+@cindex position argument
+The position of point as a number (@pxref{Point}).  No I/O.
+
+@item D
+A directory name.  The default is the current default directory of the
+current buffer, @code{default-directory} (@pxref{System Environment}).
+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 which are lists, so you can look at
+the data in the lists.  @xref{Input Events}.  No I/O.
+
+You can use @samp{e} more than once in a single command's interactive
+specification.  If the key sequence which invoked the command has
+@var{n} events with parameters, the @var{n}th @samp{e} provides the
+@var{n}th list event.  Events which are not lists, such as function keys
+and @sc{ASCII} characters, do not count where @samp{e} is concerned.
+
+Even though @samp{e} does not use a prompt string, you must follow
+it with a newline if it is not the last code character.
+
+@item f
+A file name of an existing file (@pxref{File Names}).  The default
+directory is @code{default-directory}.  Existing, Completion, Default,
+Prompt.
+
+@item F
+A file name.  The file need not exist.  Completion, Default, Prompt.
+
+@item k
+A key sequence (@pxref{Keymap Terminology}).  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.
+
+This kind of input is used by commands such as @code{describe-key} and
+@code{global-set-key}.
+
+@item m
+@cindex marker argument
+The position of the mark as a number.  No I/O.
+
+@item n
+A number read with the minibuffer.  If the input is not a number, the
+user is asked to try again.  The prefix argument, if any, is not used.
+Prompt.
+
+@item N
+@cindex raw prefix argument usage
+The raw prefix argument.  If the prefix argument is @code{nil}, then a
+number is read as with @kbd{n}.  Requires a number.  Prompt.
+
+@item p
+@cindex numeric prefix argument usage
+The numeric prefix argument.  (Note that this @samp{p} is lower case.)
+No I/O.@refill
+
+@item P
+The raw prefix argument.  (Note that this @samp{P} is upper case.)
+@xref{Prefix Command Arguments}.  No I/O.@refill
+
+@item r
+@cindex region argument
+Point and the mark, as two numeric arguments, smallest first.  This is
+the only code letter that specifies two successive arguments rather than
+one.  No I/O.
+
+@item s
+Arbitrary text, read in the minibuffer and returned as a string
+(@pxref{Text from Minibuffer}).  Terminate the input with either
+@key{LFD} or @key{RET}.  (@kbd{C-q} may be used to include either of
+these characters in the input.)  Prompt.
+
+@item S
+An interned symbol whose name is read in the minibuffer.  Any whitespace
+character terminates the input.  (Use @kbd{C-q} to include whitespace in
+the string.)  Other characters that normally terminate a symbol (e.g.,
+parentheses and brackets) do not do so here.  Prompt.
+
+@item v
+A variable declared to be a user option (i.e., satisfying the predicate
+@code{user-variable-p}).  @xref{High-Level Completion}.  Existing,
+Completion, Prompt.
+
+@item x
+A Lisp object specified in printed representation, terminated with a
+@key{LFD} or @key{RET}.  The object is not evaluated.  @xref{Object from
+Minibuffer}.  Prompt.
+
+@item X
+@cindex evaluated expression argument
+A Lisp form is read as with @kbd{x}, but then evaluated so that its
+value becomes the argument for the command.  Prompt.
+@end table
+
+@node Interactive Examples
+@comment  node-name,  next,  previous,  up
+@subsection Examples of Using @code{interactive}
+@cindex examples of using @code{interactive}
+@cindex @code{interactive}, examples of using 
+
+  Here are some examples of @code{interactive}:
+
+@example
+@group
+(defun foo1 ()              ; @r{@code{foo1} takes no arguments,}
+    (interactive)           ;   @r{just moves forward two words.}
+    (forward-word 2))
+     @result{} foo1
+@end group
+
+@group
+(defun foo2 (n)             ; @r{@code{foo2} takes one argument,}
+    (interactive "p")       ;   @r{which is the numeric prefix.}
+    (forward-word (* 2 n)))
+     @result{} foo2
+@end group
+
+@group
+(defun foo3 (n)             ; @r{@code{foo3} takes one argument,}
+    (interactive "nCount:") ;   @r{which is read with the Minibuffer.}
+    (forward-word (* 2 n)))
+     @result{} foo3
+@end group
+
+@group
+(defun three-b (b1 b2 b3)
+  "Select three existing buffers.
+Put them into three windows, selecting the last one."
+@end group
+    (interactive "bBuffer1:\nbBuffer2:\nbBuffer3:")
+    (delete-other-windows)
+    (split-window (selected-window) 8)
+    (switch-to-buffer b1)
+    (other-window 1)
+    (split-window (selected-window) 8)
+    (switch-to-buffer b2)
+    (other-window 1)
+    (switch-to-buffer b3))
+     @result{} three-b
+@group
+(three-b "*scratch*" "declarations.texi" "*mail*")
+     @result{} nil
+@end group
+@end example
+
+@node Interactive Call
+@section Interactive Call
+@cindex interactive call
+
+  After the command loop has translated a key sequence into a
+definition, it invokes that definition using the function
+@code{command-execute}.  If the definition is a function that is a
+command, @code{command-execute} calls @code{call-interactively}, which
+reads the arguments and calls the command.  You can also call these
+functions yourself.
+
+@defun commandp object
+Returns @code{t} if @var{object} is suitable for calling interactively;
+that is, if @var{object} is a command.  Otherwise, returns @code{nil}.  
+
+The interactively callable objects include strings and vectors (treated
+as keyboard macros), lambda expressions that contain a top-level call to
+@code{interactive}, byte-code function objects, autoload objects that
+are declared as interactive (non-@code{nil} fourth argument to
+@code{autoload}), and some of the primitive functions.
+
+A symbol is @code{commandp} if its function definition is
+@code{commandp}.
+
+Keys and keymaps are not commands.  Rather, they are used to look up
+commands (@pxref{Keymaps}).
+
+See @code{documentation} in @ref{Accessing Documentation}, for a
+realistic example of using @code{commandp}.
+@end defun
+
+@defun call-interactively command &optional record-flag
+This function calls the interactively callable function @var{command},
+reading arguments according to its interactive calling specifications.
+An error is signaled if @var{command} cannot be called interactively
+(i.e., it is not a command).  Note that keyboard macros (strings and
+vectors) are not accepted, even though they are considered commands.
+
+@cindex record command history
+If @var{record-flag} is non-@code{nil}, then this command and its
+arguments are unconditionally added to the list @code{command-history}.
+Otherwise, the command is added only if it uses the minibuffer to read
+an argument.  @xref{Command History}.
+@end defun
+
+@defun command-execute command &optional record-flag
+@cindex keyboard macro execution
+This function executes @var{command} as an editing command.  The
+argument @var{command} must satisfy the @code{commandp} predicate; i.e.,
+it must be an interactively callable function or a string.
+
+A string or vector as @var{command} is executed with
+@code{execute-kbd-macro}.  A function is passed to
+@code{call-interactively}, along with the optional @var{record-flag}.
+
+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.
+@end defun
+
+@deffn Command execute-extended-command prefix-argument
+@cindex read command name
+This function reads a command name from the minibuffer using
+@code{completing-read} (@pxref{Completion}).  Then it uses
+@code{command-execute} to call the specified command.  Whatever that
+command returns becomes the value of @code{execute-extended-command}.
+
+@cindex execute with prefix argument
+If the command asks for a prefix argument, the value
+@var{prefix-argument} is supplied.  If @code{execute-extended-command}
+is called interactively, the current raw prefix argument is used for
+@var{prefix-argument}, and thus passed on to whatever command is run.
+
+@c !!! Should this be @kindex?
+@cindex @kbd{M-x}
+@code{execute-extended-command} is the normal definition of @kbd{M-x},
+so it uses the string @w{@samp{M-x }} as a prompt.  (It would be better
+to take the prompt from the events used to invoke
+@code{execute-extended-command}, but that is painful to implement.)  A
+description of the value of the prefix argument, if any, also becomes
+part of the prompt.
+
+@example
+@group
+(execute-extended-command 1)
+---------- Buffer: Minibuffer ----------
+M-x forward-word RET
+---------- Buffer: Minibuffer ----------
+     @result{} t
+@end group
+@end example
+@end deffn
+
+@defun interactive-p
+This function returns @code{t} if the containing function (the one that
+called @code{interactive-p}) was called interactively, with the function
+@code{call-interactively}.  (It makes no difference whether
+@code{call-interactively} was called from Lisp or directly from the
+editor command loop.)  Note that if the containing function was called
+by Lisp evaluation (or with @code{apply} or @code{funcall}), then it was
+not called interactively.
+
+The usual application of @code{interactive-p} is for deciding whether to
+print an informative message.  As a special exception,
+@code{interactive-p} returns @code{nil} whenever a keyboard macro is
+being run.  This is to suppress the informative messages and speed
+execution of the macro.
+
+For example:
+
+@example
+@group
+(defun foo ()
+  (interactive)
+  (and (interactive-p)
+       (message "foo")))
+     @result{} foo
+@end group
+
+@group
+(defun bar ()
+  (interactive)
+  (setq foobar (list (foo) (interactive-p))))
+     @result{} bar
+@end group
+
+@group
+;; @r{Type @kbd{M-x foo}.}
+     @print{} foo
+@end group
+
+@group
+;; @r{Type @kbd{M-x bar}.}
+;; @r{This does not print anything.}
+@end group
+
+@group
+foobar
+     @result{} (nil t)
+@end group
+@end example
+@end defun
+
+@node Command Loop Info
+@comment  node-name,  next,  previous,  up
+@section Information from the Command Loop
+
+The editor command loop sets several Lisp variables to keep status
+records for itself and for commands that are run.  
+
+@defvar last-command
+This variable records the name of the previous command executed by the
+command loop (the one before the current command).  Normally the value
+is a symbol with a function definition, but this is not guaranteed.
+
+The value is set by copying the value of @code{this-command} when a
+command returns to the command loop, except when the command specifies a
+prefix argument for the following command.
+@end defvar
+
+@defvar this-command
+@cindex current command
+This variable records the name of the command now being executed by
+the editor command loop.  Like @code{last-command}, it is normally a symbol
+with a function definition.
+
+This variable is set by the command loop just before the command is run,
+and its value is copied into @code{last-command} when the command
+finishes (unless the command specifies a prefix argument for the
+following command).
+
+@cindex kill command repetition
+Some commands change the value of this variable during their execution,
+simply as a flag for whatever command runs next.  In particular, the
+functions that kill text set @code{this-command} to @code{kill-region}
+so that any kill commands immediately following will know to append the
+killed text to the previous kill.
+@end defvar
+
+If you do not want a particular command to be recognized as the previous
+command in the case where it got an error, you must code that command to
+prevent this.  One way is to set @code{this-command} to @code{t} at the
+beginning of the command, and set @code{this-command} back to its proper
+value at the end, like this:
+
+@example
+(defun foo (args@dots{})
+  (interactive @dots{})
+  (let ((old-this-command this-command))
+    (setq this-command t)
+    @r{@dots{}do the work@dots{}}
+    (setq this-command old-this-command)))
+@end example
+
+@defun this-command-keys
+This function returns a string or vector containing the key sequence
+that invoked the present command, plus any previous commands that
+generated the prefix argument for this command.  The value is a string
+if all those events were characters.  @xref{Input Events}.
+
+@example
+@group
+(this-command-keys)
+;; @r{Now type @kbd{C-u C-x C-e}.}
+     @result{} "^U^X^E"
+@end group
+@end example
+@end defun
+
+@defvar last-nonmenu-event
+This variable holds the last input event read as part of a key
+sequence, aside from events resulting from mouse menus.
+
+One use of this variable is to figure out a good default location to
+pop up another menu.
+@end defvar
+
+@defvar last-command-event
+@defvarx last-command-char
+This variable is set to the last input event that was read by the
+command loop as part of a command.  The principal use of this variable
+is in @code{self-insert-command}, which uses it to decide which
+character to insert.
+
+@example
+@group
+last-command-char 
+;; @r{Now type @kbd{C-u C-x C-e}.}
+     @result{} 5
+@end group
+@end example
+
+@noindent
+The value is 5 because that is the @sc{ASCII} code for @kbd{C-e}.
+
+The alias @code{last-command-char} exists for compatibility with
+Emacs version 18.
+@end defvar
+
+@c Emacs 19 feature
+@defvar last-event-frame
+This variable records which frame the last input event was directed to.
+Usually this is the frame that was selected when the event was
+generated, but if that frame has redirected input focus to another
+frame, the value is the frame to which the event was redirected.
+@xref{Input Focus}.
+@end defvar
+
+@defvar echo-keystrokes
+This variable determines how much time should elapse before command
+characters echo.  Its value must be an integer, which specifies the
+number of seconds to wait before echoing.  If the user types a prefix
+key (say @kbd{C-x}) and then delays this many seconds before continuing,
+the key @kbd{C-x} is echoed in the echo area.  Any subsequent characters
+in the same command will be echoed as well.
+
+If the value is zero, then command input is not echoed.
+@end defvar
+
+@node Input Events
+@section Input Events
+@cindex events
+@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.
+
+A command invoked using events that are lists can get the full values of
+these events using the @samp{e} interactive code.  @xref{Interactive
+Codes}.
+
+A key sequence that starts with a mouse event is read using the keymaps
+of the buffer in the window that the mouse was in, not the current
+buffer.  This does not imply that clicking in a window selects that
+window or its buffer---that is entirely under the control of the command
+binding of the key sequence.
+
+@defun eventp object
+This function returns non-@code{nil} if @var{event} is an input event.
+@end defun
+
+@menu
+* Keyboard Events::             Ordinary characters--keys with symbols on them.
+* Function Keys::               Function keys--keys with names, not symbols.
+* Click Events::                Pushing and releasing a mouse button.
+* Drag Events::                 Moving the mouse before releasing the button.
+* Button-Down Events::          A button was pushed and not yet released.
+* Repeat Events::               Double and triple click (or drag, or down).
+* Motion Events::               Just moving the mouse, not pushing a button.
+* Focus Events::                Moving the mouse between frames.
+* Event Examples::              Examples of the lists for mouse events.
+* Classifying Events::          Finding the modifier keys in an event symbol.
+                                Event types.
+* Accessing Events::            Functions to extract info from events.
+* Strings of Events::           Special considerations for putting
+                                  keyboard character events in a string.
+@end menu
+
+@node Keyboard Events
+@subsection Keyboard Events
+
+There are two kinds of input you can get from the keyboard: ordinary
+keys, and function keys.  Ordinary keys correspond to characters; the
+events they generate are represented in Lisp as characters.  In Emacs
+versions 18 and earlier, characters were the only events.
+
+@cindex modifier bits (of input character)
+@cindex basic code (of input character)
+An input character event consists of a @dfn{basic code} between 0 and
+255, plus any or all of these @dfn{modifier bits}:
+
+@table @asis
+@item meta
+The 2**23 bit in the character code indicates a character
+typed with the meta key held down.
+
+@item control
+The 2**22 bit in the character code indicates a non-@sc{ASCII}
+control character.
+
+@sc{ASCII} control characters such as @kbd{C-a} have special basic
+codes of their own, so Emacs needs no special bit to indicate them.
+Thus, the code for @kbd{C-a} is just 1.
+
+But if you type a control combination not in @sc{ASCII}, such as
+@kbd{%} with the control key, the numeric value you get is the code
+for @kbd{%} plus 2**22 (assuming the terminal supports non-@sc{ASCII}
+control characters).
+
+@item shift
+The 2**21 bit in the character code indicates an @sc{ASCII} control
+character typed with the shift key held down.
+
+For letters, the basic code indicates upper versus lower case; for
+digits and punctuation, the shift key selects an entirely different
+character with a different basic code.  In order to keep within
+the @sc{ASCII} character set whenever possible, Emacs avoids using
+the 2**21 bit for those characters.
+
+However, @sc{ASCII} provides no way to distinguish @kbd{C-A} from
+@kbd{C-A}, so Emacs uses the 2**21 bit in @kbd{C-A} and not in
+@kbd{C-a}.
+
+@item hyper
+The 2**20 bit in the character code indicates a character
+typed with the hyper key held down.
+
+@item super
+The 2**19 bit in the character code indicates a character
+typed with the super key held down.
+
+@item alt
+The 2**18 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.)
+@end table
+
+  In the future, Emacs may support a larger range of basic codes.  We
+may also move the modifier bits to larger bit numbers.  Therefore, you
+should avoid mentioning specific bit numbers in your program.
+Instead, the way to test the modifier bits of a character is with the
+function @code{event-modifiers} (@pxref{Classifying Events}).
+
+@node Function Keys
+@subsection Function Keys
+
+@cindex function keys
+Most keyboards also have @dfn{function keys}---keys which have names or
+symbols that are not characters.  Function keys are represented in Lisp
+as symbols; the symbol's name is the function key's label.  For example,
+pressing a key labeled @key{F1} places the symbol @code{f1} in the input
+stream.
+
+For all keyboard events, the event type (which classifies the event for
+key lookup purposes) is identical to the event---it is the character or
+the symbol.  @xref{Classifying Events}.
+
+Here are a few special cases in the symbol naming convention for
+function keys:
+
+@table @asis
+@item @code{backspace}, @code{tab}, @code{newline}, @code{return}, @code{delete}
+These keys correspond to common @sc{ASCII} control characters that have
+special keys on most keyboards.
+
+In @sc{ASCII}, @kbd{C-i} and @key{TAB} are the same character.  Emacs
+lets you distinguish them if you wish, by returning the former as the
+integer 9, and the latter as the symbol @code{tab}.
+
+Most of the time, it's not useful to distinguish the two.  So normally
+@code{function-key-map} is set up to map @code{tab} into 9.  Thus, a
+key binding for character code 9 also applies to @code{tab}.  Likewise
+for the other symbols in this group.  The function @code{read-char}
+also converts these events into characters.
+
+In @sc{ASCII}, @key{BS} is really @kbd{C-h}.  But @code{backspace}
+converts into the character code 127 (@key{DEL}), not into code 8
+(@key{BS}).  This is what most users prefer.
+
+@item @code{kp-add}, @code{kp-decimal}, @code{kp-divide}, @dots{}
+Keypad keys (to the right of the regular keyboard).
+@item @code{kp-0}, @code{kp-1}, @dots{}
+Keypad keys with digits.
+@item @code{kp-f1}, @code{kp-f2}, @code{kp-f3}, @code{kp-f4}
+Keypad PF keys.
+@item @code{left}, @code{up}, @code{right}, @code{down}
+Cursor arrow keys
+@end table
+
+You can use the modifier keys @key{CTRL}, @key{META}, @key{HYPER},
+@key{SUPER}, @key{ALT} and @key{SHIFT} with function keys.  The way
+to represent them is with prefixes in the symbol name:
+
+@table @samp
+@item A-
+The alt modifier.
+@item C-
+The control modifier.
+@item H-
+The hyper modifier.
+@item M-
+The meta modifier.
+@item S-
+The shift modifier.
+@item s-
+The super modifier.
+@end table
+
+Thus, the symbol for the key @key{F3} with @key{META} held down is
+@kbd{M-@key{F3}}.  When you use more than one prefix, we recommend you
+write them in alphabetical order (though the order does not matter in
+arguments to the key-binding lookup and modification functions).
+
+@node Click Events
+@subsection Click Events
+@cindex click event
+@cindex mouse click event
+
+When the user presses a mouse button and releases it at the same
+location, that generates a @dfn{click} event.  Mouse click events have
+this form:
+
+@example
+(@var{event-type}
+ (@var{window} @var{buffer-pos}
+  (@var{x} . @var{y}) @var{timestamp})
+ @var{click-count})
+@end example
+
+Here is what the elements normally mean:
+
+@table @var
+@item event-type
+This is a symbol that indicates which mouse button was used.  It is
+one of the symbols @code{mouse-1}, @code{mouse-2}, @dots{}, where the
+buttons are numbered numbered left to right.
+
+You can also use prefixes @samp{A-}, @samp{C-}, @samp{H-}, @samp{M-},
+@samp{S-} and @samp{s-} for modifiers alt, control, hyper, meta, shift
+and super, just as you would with function keys.
+
+This symbol also serves as the event type of the event.  Key bindings
+describe events by their types; thus, if there is a key binding for
+@code{mouse-1}, that binding would apply to all events whose
+@var{event-type} is @code{mouse-1}.
+
+@item window
+This is the window in which the click occurred.
+
+@item x
+@itemx y
+These are the pixel-based coordinates of the click, relative to the top
+left corner of @var{window}, which is @code{(0 . 0)}.
+
+@item buffer-pos
+This is the buffer position of the character clicked on.
+
+@item timestamp
+This is the time at which the event occurred, in milliseconds.  (Since
+this value wraps around the entire range of Emacs Lisp integers in about
+five hours, it is useful only for relating the times of nearby events.)
+
+@item click-count
+This is the number of rapid repeated presses so far of the same mouse
+button.  @xref{Repeat Events}.
+@end table
+
+The meanings of @var{buffer-pos}, @var{row} and @var{column} are
+somewhat different when the event location is in a special part of the
+screen, such as the mode line or a scroll bar.
+
+If the location is in a scroll bar, then @var{buffer-pos} is the symbol
+@code{vertical-scroll-bar} or @code{horizontal-scroll-bar}, and the pair
+@code{(@var{x} . @var{y})} is replaced with a pair @code{(@var{portion}
+. @var{whole})}, where @var{portion} is the distance of the click from
+the top or left end of the scroll bar, and @var{whole} is the length of
+the entire scroll bar.
+
+If the position is on a mode line or the vertical line separating
+@var{window} from its neighbor to the right, then @var{buffer-pos} is
+the symbol @code{mode-line} or @code{vertical-line}.  For the mode line,
+@var{row} does not have meaningful data.  For the vertical line,
+@var{column} does not have meaningful data.
+
+@var{buffer-pos} may be a list containing a symbol (one of the symbols
+listed above) instead of just the symbol.  This is what happens after
+the imaginary prefix keys for these events are inserted into the input
+stream.  @xref{Key Sequence Input}.
+
+@node Drag Events
+@subsection Drag Events
+@cindex drag event
+@cindex mouse drag event
+
+With Emacs, you can have a drag event without even changing your
+clothes.  A @dfn{drag event} happens every time the user presses a mouse
+button and then moves the mouse to a different character position before
+releasing the button.  Like all mouse events, drag events are
+represented in Lisp as lists.  The lists record both the starting mouse
+position and the final position, like this:
+
+@example
+(@var{event-type}
+ (@var{window1} @var{buffer-pos1}
+  (@var{x1} . @var{y1}) @var{timestamp1})
+ (@var{window2} @var{buffer-pos2}
+  (@var{x2} . @var{y2}) @var{timestamp2})
+ @var{click-count})
+@end example
+
+For a drag event, the name of the symbol @var{event-type} contains the
+prefix @samp{drag-}.  The second and third elements of the event give
+the starting and ending position of the drag.  Aside from that, the data
+have the same meanings as in a click event (@pxref{Click Events}).  You
+can access the second element of any mouse event in the same way, with
+no need to distinguish drag events from others.
+
+The @samp{drag-} prefix follows the modifier key prefixes such as
+@samp{C-} and @samp{M-}.
+
+If @code{read-key-sequence} receives a drag event which has no key
+binding, and the corresponding click event does have a binding, it
+changes the drag event into a click event at the drag's starting
+position.  This means that you don't have to distinguish between click
+and drag events unless you want to.
+
+@node Button-Down Events
+@subsection Button-Down Events
+@cindex button-down event
+
+Click and drag events happen when the user releases a mouse button.
+They cannot happen earlier, because there is no way to distinguish a
+click from a drag until the button is released.
+
+If you want to take action as soon as a button is pressed, you need to
+handle @dfn{button-down} events.@footnote{Button-down is the
+conservative antithesis of drag.}.  These occur as soon as a button is
+pressed.  They are represented by lists which look exactly like click
+events (@pxref{Click Events}), except that the name of @var{event-type}
+contains the prefix @samp{down-}.  The @samp{down-} prefix follows the
+modifier key prefixes such as @samp{C-} and @samp{M-}.
+
+The function @code{read-key-sequence}, and the Emacs command loop,
+ignore any button-down events that don't have command bindings.  This
+means that you need not worry about defining button-down events unless
+you want them to do something.  The usual reason to define a button-down
+event is so that you can track mouse motion (by reading motion events)
+until the button is released.
+@ifinfo
+@xref{Motion Events}.
+@end ifinfo
+
+@node Repeat Events
+@subsection Repeat Events
+@cindex repeat events
+@cindex double-click events
+@cindex triple-click events
+
+If you press the same mouse button more than once in quick succession
+without moving the mouse, Emacs uses special @dfn{repeat} mouse events
+for the second and subsequent presses.
+
+The most common repeat events are @dfn{double-click} events.  Emacs
+generates a double-click event when you click a button twice; the event
+happens when you release the button (as is normal for all click
+events).
+
+The event type of a double-click event contains the prefix
+@code{double}.  Thus, a double click on the second mouse button with
+@key{meta} held down comes to the Lisp program as
+@code{M-double-mouse-2}.  If a double-click event has no binding, the
+binding of the corresponding ordinary click event is used to execute
+it.  Thus, you need not pay attention to the double click feature 
+unless you really want to.
+
+When the user performs a double click, Emacs generates first an ordinary
+click event, and then a double-click event.  Therefore, the command
+binding of the double click event must be written to assume that the
+single-click command has already run.  It must produce the desired
+results of a double click, starting from the results of a single click.
+
+This means that it is most convenient to give double clicks a meaning
+that somehow ``builds on'' the meaning of a single click.  This is what
+user interface experts recommend that double clicks should do.
+
+If you click a button, then press it down again and start moving the
+mouse with the button held down, then you get a @dfn{double-drag} event
+when you ultimately release the button.  Its event type contains
+@samp{double-drag} instead of just @samp{drag}.  If a double-drag event
+has no binding, Emacs looks for an alternate binding as if the event
+were an ordinary click.
+
+Before the double-click or double-drag event, Emacs generates a
+@dfn{double-down} event when the button is pressed down for the second
+time.  Its event type contains @samp{double-down} instead of just
+@samp{down}.  If a double-down event has no binding, Emacs looks for an
+alternate binding as if the event were an ordinary button-down event.
+If it finds no binding that way either, the double-down event is ignored.
+
+To summarize, when you click a button and then press it again right
+away, Emacs generates a double-down event, followed by either a
+double-click or a double-drag.
+
+If you click a button twice and then press it again, all in quick
+succession, Emacs generates a @dfn{triple-down} event, followed by
+either a @dfn{triple-click} or a @dfn{triple-drag}.  The event types of
+these events contain @samp{triple} instead of @samp{double}.  If any
+triple event has no binding, Emacs uses the binding that it would use
+for the corresponding double event.
+
+If you click a button three or more times and then press it again,
+the events for the presses beyond the third are all triple events.
+Emacs does not have quadruple, quintuple, etc. events as separate
+event types.  However, you can look at the event list to find out
+precisely how many times the button was pressed.
+
+@defun event-click-count event
+This function returns the number of consecutive button presses that led
+up to @var{event}.  If @var{event} is a double-down, double-click or
+double-drag event, the value is 2.  If @var{event} is a triple event,
+the value is 3 or greater.  If @var{event} is an ordinary mouse event
+(not a repeat event), the value is 1.
+@end defun
+
+@defvar double-click-time
+To count as double- and triple-clicks, mouse clicks must be at the same
+location as the first click, and the number of milliseconds between the
+first release and the second must be less than the value of
+@code{double-click-time}.  Setting @code{double-click-time} to
+@code{nil} disables multi-click detection entirely.  Setting it to
+@code{t} removes the time limit; Emacs then detects multi-clicks by
+position only.
+@end defvar
+
+@node Motion Events
+@subsection Motion Events
+@cindex motion event
+@cindex mouse motion events
+
+Emacs sometimes generates @dfn{mouse motion} events to describe motion
+of the mouse without any button activity.  Mouse motion events are
+represented by lists that look like this:
+
+@example
+(mouse-movement
+ (@var{window} @var{buffer-pos}
+  (@var{x} . @var{y}) @var{timestamp}))
+@end example
+
+The second element of the list describes the current position of the
+mouse, just as in a click event (@pxref{Click Events}).
+
+The special form @code{track-mouse} enables generation of motion events
+within its body.  Outside of @code{track-mouse} forms, Emacs does not
+generate events for mere motion of the mouse, and these events do not
+appear.
+
+@defspec track-mouse body@dots{}
+This special form executes @var{body}, with generation of mouse motion
+events enabled.  Typically @var{body} would use @code{read-event}
+to read the motion events and modify the display accordingly.
+
+When the user releases the button, that generates a click event.
+Normally @var{body} should return when it sees the click event, and
+discard the event.
+@end defspec
+
+@node Focus Events
+@subsection Focus Events
+@cindex focus event
+
+Window systems provide general ways for the user to control which window
+gets keyboard input.  This choice of window is called the @dfn{focus}.
+When the user does something to switch between Emacs frames, that
+generates a @dfn{focus event}.  The normal definition of a focus event,
+in the global keymap, is to select a new frame within Emacs, as the user
+would expect.  @xref{Input Focus}.
+
+Focus events are represented in Lisp as lists that look like this:
+
+@example
+(switch-frame @var{new-frame})
+@end example
+
+@noindent
+where @var{new-frame} is the frame switched to.
+
+In X windows, most window managers are set up so that just moving the
+mouse into a window is enough to set the focus there.  Emacs appears to
+do this, because it changes the cursor to solid in the new frame.
+However, there is no need for the Lisp program to know about the focus
+change until some other kind of input arrives.  So Emacs generates the
+focus event only when the user actually types a keyboard key or presses
+a mouse button in the new frame; just moving the mouse between frames
+does not generate a focus event.
+
+A focus event in the middle of a key sequence would garble the
+sequence.  So Emacs never generates a focus event in the middle of a key
+sequence.  If the user changes focus in the middle of a key
+sequence---that is, after a prefix key---then Emacs reorders the events
+so that the focus event comes either before or after the multi-event key
+sequence, and not within it.
+
+@node Event Examples
+@subsection Event Examples
+
+If the user presses and releases the left mouse button over the same
+location, that generates a sequence of events like this:
+
+@smallexample
+(down-mouse-1 (#<window 18 on NEWS> 2613 (0 . 38) -864320))
+(mouse-1      (#<window 18 on NEWS> 2613 (0 . 38) -864180))
+@end smallexample
+
+Or, while holding the control key down, the user might hold down the
+second mouse button, and drag the mouse from one line to the next.
+That produces two events, as shown here:
+
+@smallexample
+(C-down-mouse-2 (#<window 18 on NEWS> 3440 (0 . 27) -731219))
+(C-drag-mouse-2 (#<window 18 on NEWS> 3440 (0 . 27) -731219)
+                (#<window 18 on NEWS> 3510 (0 . 28) -729648))
+@end smallexample
+
+Or, while holding down the meta and shift keys, the user might press the
+second mouse button on the window's mode line, and then drag the mouse
+into another window.  That produces the following pair of events:
+
+@smallexample
+(M-S-down-mouse-2 (#<window 18 on NEWS> mode-line (33 . 31) -457844))
+(M-S-drag-mouse-2 (#<window 18 on NEWS> mode-line (33 . 31) -457844)
+                  (#<window 20 on carlton-sanskrit.tex> 161 (33 . 3)
+                   -453816))
+@end smallexample
+
+@node Classifying Events
+@subsection Classifying Events
+@cindex event type
+
+  Every event has an @dfn{event type} which classifies the event for key
+binding purposes.  For a keyboard event, the event type equals the event
+value; thus, the event type for a character is the character, and the
+event type for a function key symbol is the symbol itself.  For events
+which are lists, the event type is the symbol in the @sc{car} of the
+list.  Thus, the event type is always a symbol or a character.
+
+  Two events of the same type are equivalent where key bindings are
+concerned; thus, they always run the same command.  That does not
+necessarily mean they do the same things, however, as some commands look
+at the whole event to decide what to do.  For example, some commands use
+the location of a mouse event to decide what text to act on.
+
+  Sometimes broader classifications of events are useful.  For example,
+you might want to ask whether an event involved the @key{META} key,
+regardless of which other key or mouse button was used.
+
+  The functions @code{event-modifiers} and @code{event-basic-type} are
+provided to get such information conveniently.
+
+@defun event-modifiers event
+This function returns a list of the modifiers that @var{event} has.
+The modifiers are symbols; they include @code{shift}, @code{control},
+@code{meta}, @code{alt}, @code{hyper} and @code{super}.  In addition,
+the property of a mouse event symbol always has one of @code{click},
+@code{drag}, and @code{down} among the modifiers.  For example:
+
+@example
+(event-modifiers ?a)
+     @result{} nil
+(event-modifiers ?\C-a)
+     @result{} (control)
+(event-modifiers ?\C-%)
+     @result{} (control)
+(event-modifiers ?\C-\S-a)
+     @result{} (control shift)
+(event-modifiers 'f5)
+     @result{} nil
+(event-modifiers 's-f5)
+     @result{} (super)
+(event-modifiers 'M-S-f5)
+     @result{} (meta shift)
+(event-modifiers 'mouse-1)
+     @result{} (click)
+(event-modifiers 'down-mouse-1)
+     @result{} (down)
+@end example
+
+The modifiers list for a click event explicitly contains @code{click},
+but the event symbol name itself does not contain @samp{click}.
+@end defun
+
+@defun event-basic-type event
+This function returns the key or mouse button that @var{event}
+describes, with all modifiers removed.  For example:
+
+@example
+(event-basic-type ?a)
+     @result{} 97
+(event-basic-type ?A)
+     @result{} 97
+(event-basic-type ?\C-a)
+     @result{} 97
+(event-basic-type ?\C-\S-a)
+     @result{} 97
+(event-basic-type 'f5)
+     @result{} f5
+(event-basic-type 's-f5)
+     @result{} f5
+(event-basic-type 'M-S-f5)
+     @result{} f5
+(event-basic-type 'down-mouse-1)
+     @result{} mouse-1
+@end example
+@end defun
+
+@defun mouse-movement-p object
+This function returns non-@code{nil} if @var{object} is a mouse movement
+event.
+@end defun
+
+@node Accessing Events
+@subsection Accessing Events
+
+  This section describes convenient functions for accessing the data in
+an event which is a list.
+
+  The following functions return the starting or ending position of a
+mouse-button event.  The position is a list of this form:
+
+@smallexample
+(@var{window} @var{buffer-position} (@var{col} . @var{row}) @var{timestamp})
+@end smallexample
+
+@defun event-start event
+This returns the starting position of @var{event}.
+
+If @var{event} is a click or button-down event, this returns the
+location of the event.  If @var{event} is a drag event, this returns the
+drag's starting position.
+@end defun
+
+@defun event-end event
+This returns the ending position of @var{event}.
+
+If @var{event} is a drag event, this returns the position where the user
+released the mouse button.  If @var{event} is a click or button-down
+event, the value is actually the starting position, which is the only
+position such events have.
+@end defun
+
+  These four functions take a position-list as described above, and
+return various parts of it.
+
+@defun posn-window position
+Return the window that @var{position} is in.
+@end defun
+
+@defun posn-point position
+Return the buffer location in @var{position}.
+@end defun
+
+@defun posn-x-y position
+Return the pixel-based x and y coordinates column in @var{position}, as
+a cons cell @code{(@var{x} . @var{y})}.
+@end defun
+
+@defun posn-col-row position
+Return the row and column (in units of characters) in @var{position}, as
+a cons cell @code{(@var{col} . @var{row})}.  These are computed from the
+@var{x} and @var{y} values actually found in @var{position}.
+@end defun
+
+@defun posn-timestamp position
+Return the timestamp of @var{position}.
+@end defun
+
+@defun scroll-bar-scale ratio total
+This function multiples (in effect) @var{ratio} by @var{total}, 
+rounding the result to an integer.  @var{ratio} is not a number,
+but rather  a pair @code{(@var{num} . @var{denom})}.
+
+This is handy for scaling a position on a scroll bar into a buffer
+position.  Here's how to do that:
+
+@example
+(+ (point-min)
+   (scroll-bar-scale
+      (posn-col-row (event-start event))
+      (- (point-max) (point-min))))
+@end example
+@end defun
+
+@node Strings of Events
+@subsection Putting Keyboard Events in Strings
+
+  In most of the places where strings are used, we conceptualize the
+string as containing text characters---the same kind of characters found
+in buffers or files.  Occasionally Lisp programs use strings which
+conceptually contain keyboard characters; for example, they may be key
+sequences or keyboard macro definitions.  There are special rules for
+how to put keyboard characters into a string, because they are not
+limited to the range of 0 to 255 as text characters are.
+
+  A keyboard character typed using the @key{META} key is called a
+@dfn{meta character}.  The numeric code for such an event includes the
+2**23 bit; it does not even come close to fitting in a string.  However,
+earlier Emacs versions used a different representation for these
+characters, which gave them codes in the range of 128 to 255.  That did
+fit in a string, and many Lisp programs contain string constants that
+use @samp{\M-} to express meta characters, especially as the argument to
+@code{define-key} and similar functions.
+
+  We provide backward compatibility to run those programs with special
+rules for how to put a keyboard character event in a string.  Here are
+the rules:
+
+@itemize @bullet
+@item
+If the keyboard event value is in the range of 0 to 127, it can go in the
+string unchanged.
+
+@item
+The meta variants of those events, with codes in the range of 2**23 to
+2**23+127, can also go in the string, but you must change their numeric
+values.  You must set the 2**7 bit instead of the 2**23 bit, resulting
+in a value between 128 and 255.
+
+@item
+Other keyboard character events cannot fit in a string.  This includes
+keyboard events in the range of 128 to 255.
+@end itemize
+
+  Functions such as @code{read-key-sequence} that can construct strings
+containing events follow these rules.
+
+  When you use the read syntax @samp{\M-} in a string, it produces a
+code in the range of 128 to 255---the same code that you get if you
+modify the corresponding keyboard event to put it in the string.  Thus,
+meta events in strings work consistently regardless of how they get into
+the strings.
+
+  New programs can avoid dealing with these rules by using vectors
+instead of strings for key sequences when there is any possibility that
+these issues might arise.
+
+  The reason we changed the representation of meta characters as
+keyboard events is to make room for basic character codes beyond 127,
+and support meta variants of such larger character codes.
+
+@node Reading Input
+@section Reading Input
+
+  The editor command loop reads keyboard input using the function
+@code{read-key-sequence}, which uses @code{read-event}.  These and other
+functions for keyboard input are also available for use in Lisp
+programs.  See also @code{momentary-string-display} in @ref{Temporary
+Displays}, and @code{sit-for} in @ref{Waiting}.  @xref{Terminal Input},
+for functions and variables for controlling terminal input modes and
+debugging terminal input.
+
+  For higher-level input facilities, see @ref{Minibuffers}.
+
+@menu
+* Key Sequence Input::          How to read one key sequence.
+* Reading One Event::           How to read just one event.
+* Quoted Character Input::      Asking the user to specify a character.
+* Peeking and Discarding::      How to reread or throw away input events.
+@end menu
+
+@node Key Sequence Input
+@subsection Key Sequence Input
+@cindex key sequence input
+
+  The command loop reads input a key sequence at a time, by calling
+@code{read-key-sequence}.  Lisp programs can also call this function;
+for example, @code{describe-key} uses it to read the key to describe.
+
+@defun read-key-sequence prompt
+@cindex key sequence
+This function reads a key sequence and returns it as a string or
+vector.  It keeps reading events until it has accumulated a full key
+sequence; that is, enough to specify a non-prefix command using the
+currently active keymaps.
+
+If the events are all characters and all can fit in a string, then
+@code{read-key-sequence} returns a string (@pxref{Strings of Events}).
+Otherwise, it returns a vector, since a vector can hold all kinds of
+events---characters, symbols, and lists.  The elements of the string or
+vector are the events in the key sequence.
+
+Quitting is suppressed inside @code{read-key-sequence}.  In other words,
+a @kbd{C-g} typed while reading with this function is treated like any
+other character, and does not set @code{quit-flag}.  @xref{Quitting}.
+
+The argument @var{prompt} is either a string to be displayed in the echo
+area as a prompt, or @code{nil}, meaning not to display a prompt.
+
+In the example below, the prompt @samp{?} is displayed in the echo area,
+and the user types @kbd{C-x C-f}.
+
+@example
+(read-key-sequence "?")
+
+@group
+---------- Echo Area ----------
+?@kbd{C-x C-f}
+---------- Echo Area ----------
+
+     @result{} "^X^F"
+@end group
+@end example
+@end defun
+
+@defvar num-input-keys
+@c Emacs 19 feature
+This variable's value is the number of key sequences processed so far in
+this Emacs session.  This includes key sequences read from the terminal
+and key sequences read from keyboard macros being executed.
+@end defvar
+
+@cindex upper case key sequence
+@cindex downcasing in @code{lookup-key}
+If an input character is an upper case letter and has no key binding,
+but the lower case equivalent has one, then @code{read-key-sequence}
+converts the character to lower case.  Note that @code{lookup-key} does
+not perform case conversion in this way.
+
+The function @code{read-key-sequence} also transforms some mouse events.
+It converts unbound drag events into click events, and discards unbound
+button-down events entirely.  It also reshuffles focus events so that they
+never appear in a key sequence with any other events.
+
+When mouse events occur in special parts of a window, such as a mode
+line or a scroll bar, the event itself shows nothing special---only the
+symbol that would normally represent that mouse button and modifier
+keys.  The information about the screen region is kept elsewhere in the
+event---in the coordinates.  But @code{read-key-sequence} translates
+this information into imaginary prefix keys, all of which are symbols:
+@code{mode-line}, @code{vertical-line}, @code{horizontal-scroll-bar} and
+@code{vertical-scroll-bar}.
+
+For example, if you call @code{read-key-sequence} and then click the
+mouse on the window's mode line, this is what happens:
+
+@smallexample
+(read-key-sequence "Click on the mode line: ")
+     @result{} [mode-line
+          (mouse-1
+           (#<window 6 on NEWS> mode-line
+            (40 . 63) 5959987))]
+@end smallexample
+
+You can define meanings for mouse clicks in special window regions by
+defining key sequences using these imaginary prefix keys.
+
+@node Reading One Event
+@subsection Reading One Event
+
+  The lowest level functions for command input are those which read a
+single event.
+
+@defun read-event
+This function reads and returns the next event of command input, waiting
+if necessary until an event is available.  Events can come directly from
+the user or from a keyboard macro.
+
+The function @code{read-event} does not display any message to indicate
+it is waiting for input; use @code{message} first, if you wish to
+display one.  If you have not displayed a message, @code{read-event}
+does @dfn{prompting}: it displays descriptions of the events that led to
+or were read by the current command.  @xref{The Echo Area}.
+
+If @code{cursor-in-echo-area} is non-@code{nil}, then @code{read-event}
+moves the cursor temporarily to the echo area, to the end of any message
+displayed there.  Otherwise @code{read-event} does not move the cursor.
+@end defun
+
+Here is what happens if you call @code{read-event} and then press the
+right-arrow function key:
+
+@example
+@group
+(read-event)
+     @result{} right
+@end group
+@end example
+
+@defun read-char
+This function reads and returns a character of command input.  It
+discards any events that are not characters until it gets a character.
+
+In the first example, the user types @kbd{1} (which is @sc{ASCII} code
+49).  The second example shows a keyboard macro definition that calls
+@code{read-char} from the minibuffer.  @code{read-char} reads the
+keyboard macro's very next character, which is @kbd{1}.  The value of
+this function is displayed in the echo area by the command
+@code{eval-expression}.
+
+@example
+@group
+(read-char)
+     @result{} 49
+@end group
+
+@group
+(symbol-function 'foo)
+     @result{} "^[^[(read-char)^M1"
+@end group
+@group
+(execute-kbd-macro foo)
+     @print{} 49
+     @result{} nil
+@end group
+@end example
+@end defun
+
+@node Quoted Character Input
+@subsection Quoted Character Input
+@cindex quoted character input
+
+  You can use the function @code{read-quoted-char} when you want the user
+to specify a character, and allow the user to specify a control or meta
+character conveniently with quoting or as an octal character code.  The
+command @code{quoted-insert} calls this function.
+
+@defun read-quoted-char &optional prompt
+@cindex octal character input
+@cindex control characters, reading
+@cindex nonprinting characters, reading
+This function is like @code{read-char}, except that if the first
+character read is an octal digit (0-7), it reads up to two more octal digits
+(but stopping if a non-octal digit is found) and returns the
+character represented by those digits as an octal number.
+
+Quitting is suppressed when the first character is read, so that the
+user can enter a @kbd{C-g}.  @xref{Quitting}.
+
+If @var{prompt} is supplied, it specifies a string for prompting the
+user.  The prompt string is always printed in the echo area and followed
+by a single @samp{-}.
+
+In the following example, the user types in the octal number 177 (which
+is 127 in decimal).
+
+@example
+(read-quoted-char "What character")
+
+@group
+---------- Echo Area ----------
+What character-@kbd{177}
+---------- Echo Area ----------
+
+     @result{} 127
+@end group
+@end example
+@end defun
+
+@need 3000
+
+@node Peeking and Discarding
+@subsection Peeking and Discarding
+
+@defvar unread-command-events
+@cindex next input
+@cindex peeking at input
+This variable holds a list of events waiting to be read as command
+input.  The events are used in the order they appear in the list.
+
+The variable is used because in some cases a function reads a event and
+then decides not to use it.  Storing the event in this variable causes
+it to be processed normally by the command loop or when the functions to
+read command input are called.
+
+@cindex prefix argument unreading
+For example, the function that implements numeric prefix arguments reads
+any number of digits.  When it finds a non-digit event, it must unread
+the event so that it can be read normally by the command loop.
+Likewise, incremental search uses this feature to unread events it does
+not recognize.
+@end defvar
+
+@defvar unread-command-char
+This variable holds a character to be read as command input.
+A value of -1 means ``empty''.
+
+This variable is pretty much obsolete now that you can use
+@code{unread-command-events} instead; it exists only to support programs
+written for Emacs versions 18 and earlier.
+@end defvar
+
+@defun listify-key-sequence key
+This function converts the string or vector @var{key} to a list of
+events which you can put in @code{unread-command-events}.  Converting a
+vector is simple, but converting a string is tricky because of the
+special representation used for meta characters in a string
+(@pxref{Strings of Events}).
+@end defun
+
+@defun input-pending-p
+@cindex waiting for command key input
+This function determines whether any command input is currently
+available to be read.  It returns immediately, with value @code{t} if
+there is input, @code{nil} otherwise.  On rare occasions it may return
+@code{t} when no input is available.
+@end defun
+
+@defvar last-input-event
+@defvarx last-input-char
+  This variable records the last terminal input event read, whether
+as part of a command or explicitly by a Lisp program.
+
+  In the example below, a character is read (the character @kbd{1},
+@sc{ASCII} code 49).  It becomes the value of @code{last-input-char},
+while @kbd{C-e} (from the @kbd{C-x C-e} command used to evaluate this
+expression) remains the value of @code{last-command-char}.
+
+@example
+@group
+(progn (print (read-char))
+       (print last-command-char)
+       last-input-char)
+     @print{} 49
+     @print{} 5
+     @result{} 49
+@end group
+@end example
+
+The alias @code{last-input-char} exists for compatibility with
+Emacs version 18.
+@end defvar
+
+@defun discard-input
+@cindex flush input
+@cindex discard input
+@cindex terminate keyboard macro
+This function discards the contents of the terminal input buffer and
+cancels any keyboard macro that might be in the process of definition.
+It returns @code{nil}.
+
+In the following example, the user may type a number of characters right
+after starting the evaluation of the form.  After the @code{sleep-for}
+finishes sleeping, any characters that have been typed are discarded.
+
+@example
+(progn (sleep-for 2)
+  (discard-input))
+     @result{} nil
+@end example
+@end defun
+
+@node Waiting
+@section Waiting for Elapsed Time or Input
+@cindex pausing
+@cindex waiting
+
+  The waiting commands are designed to make Emacs wait for a certain
+amount of time to pass or until there is input.  For example, you may
+wish to pause in the middle of a computation to allow the user time to
+view the display.  @code{sit-for} pauses and updates the screen, and
+returns immediately if input comes in, while @code{sleep-for} pauses
+without updating the screen.
+
+@defun sit-for seconds &optional millisec nodisp
+This function performs redisplay (provided there is no pending input
+from the user), then waits @var{seconds} seconds, or until input is
+available.  The result is @code{t} if @code{sit-for} waited the full
+time with no input arriving (see @code{input-pending-p} in @ref{Peeking
+and Discarding}).  Otherwise, the value is @code{nil}.
+
+@c Emacs 19 feature ??? maybe not working yet
+The optional argument @var{millisec} specifies an additional waiting
+period measured in milliseconds.  This adds to the period specified by
+@var{seconds}.  Not all operating systems support waiting periods other
+than multiples of a second; on those that do not, you get an error if
+you specify nonzero @var{millisec}.
+
+@cindex forcing redisplay
+Redisplay is always preempted if input arrives, and does not happen at
+all if input is available before it starts.  Thus, there is no way to
+force screen updating if there is pending input; however, if there is no
+input pending, you can force an update with no delay by using
+@code{(sit-for 0)}.
+
+If @var{nodisp} is non-@code{nil}, then @code{sit-for} does not
+redisplay, but it still returns as soon as input is available (or when
+the timeout elapses).
+
+The usual purpose of @code{sit-for} is to give the user time to read
+text that you display.
+@end defun
+
+@defun sleep-for seconds &optional millisec
+This function simply pauses for @var{seconds} seconds without updating
+the display.  It pays no attention to available input.  It returns
+@code{nil}.
+
+@c Emacs 19 feature ??? maybe not working yet
+The optional argument @var{millisec} specifies an additional waiting
+period measured in milliseconds.  This adds to the period specified by
+@var{seconds}.  Not all operating systems support waiting periods other
+than multiples of a second; on those that do not, you get an error if
+you specify nonzero @var{millisec}.
+
+Use @code{sleep-for} when you wish to guarantee a delay.
+@end defun
+
+  @xref{Time of Day}, for functions to get the current time.
+
+@node Quitting
+@section Quitting
+@cindex @kbd{C-g}
+@cindex quitting
+
+  Typing @kbd{C-g} while the command loop has run a Lisp function causes
+Emacs to @dfn{quit} whatever it is doing.  This means that control
+returns to the innermost active command loop.  
+
+  Typing @kbd{C-g} while the command loop is waiting for keyboard input
+does not cause a quit; it acts as an ordinary input character.  In the
+simplest case, you cannot tell the difference, because @kbd{C-g}
+normally runs the command @code{keyboard-quit}, whose effect is to quit.
+However, when @kbd{C-g} follows a prefix key, the result is an undefined
+key.  The effect is to cancel the prefix key as well as any prefix
+argument.
+
+  In the minibuffer, @kbd{C-g} has a different definition: it aborts out
+of the minibuffer.  This means, in effect, that it exits the minibuffer
+and then quits.  (Simply quitting would return to the command loop
+@emph{within} the minibuffer.)  The reason why @kbd{C-g} does not quit
+directly when the command reader is reading input is so that its meaning
+can be redefined in the minibuffer in this way.  @kbd{C-g} following a
+prefix key is not redefined in the minibuffer, and it has its normal
+effect of canceling the prefix key and prefix argument.  This too
+would not be possible if @kbd{C-g} quit directly.
+
+  @kbd{C-g} causes a quit by setting the variable @code{quit-flag} to a
+non-@code{nil} value.  Emacs checks this variable at appropriate times
+and quits if it is not @code{nil}.  Setting @code{quit-flag}
+non-@code{nil} in any way thus causes a quit.
+
+  At the level of C code, quits cannot happen just anywhere; only at the
+special places which check @code{quit-flag}.  The reason for this is
+that quitting at other places might leave an inconsistency in Emacs's
+internal state.  Because quitting is delayed until a safe place, quitting 
+cannot make Emacs crash.
+
+  Certain functions such as @code{read-key-sequence} or
+@code{read-quoted-char} prevent quitting entirely even though they wait
+for input.  Instead of quitting, @kbd{C-g} serves as the requested
+input.  In the case of @code{read-key-sequence}, this serves to bring
+about the special behavior of @kbd{C-g} in the command loop.  In the
+case of @code{read-quoted-char}, this is so that @kbd{C-q} can be used
+to quote a @kbd{C-g}.  
+
+  You can prevent quitting for a portion of a Lisp function by binding
+the variable @code{inhibit-quit} to a non-@code{nil} value.  Then,
+although @kbd{C-g} still sets @code{quit-flag} to @code{t} as usual, the
+usual result of this---a quit---is prevented.  Eventually,
+@code{inhibit-quit} will become @code{nil} again, such as when its
+binding is unwound at the end of a @code{let} form.  At that time, if
+@code{quit-flag} is still non-@code{nil}, the requested quit happens
+immediately.  This behavior is ideal for a ``critical section'', where
+you wish to make sure that quitting does not happen within that part of
+the program.
+
+@cindex @code{read-quoted-char} quitting
+  In some functions (such as @code{read-quoted-char}), @kbd{C-g} is
+handled in a special way which does not involve quitting.  This is done
+by reading the input with @code{inhibit-quit} bound to @code{t} and
+setting @code{quit-flag} to @code{nil} before @code{inhibit-quit}
+becomes @code{nil} again.  This excerpt from the definition of
+@code{read-quoted-char} shows how this is done; it also shows that
+normal quitting is permitted after the first character of input.
+
+@example
+(defun read-quoted-char (&optional prompt)
+  "@dots{}@var{documentation}@dots{}"
+  (let ((count 0) (code 0) char)
+    (while (< count 3)
+      (let ((inhibit-quit (zerop count))
+            (help-form nil))
+        (and prompt (message "%s-" prompt))
+        (setq char (read-char))
+        (if inhibit-quit (setq quit-flag nil)))
+      @dots{})
+    (logand 255 code)))
+@end example
+
+@defvar quit-flag
+If this variable is non-@code{nil}, then Emacs quits immediately,
+unless @code{inhibit-quit} is non-@code{nil}.  Typing @kbd{C-g} sets
+@code{quit-flag} non-@code{nil}, regardless of @code{inhibit-quit}.
+@end defvar
+
+@defvar inhibit-quit
+This variable determines whether Emacs should quit when @code{quit-flag}
+is set to a value other than @code{nil}.  If @code{inhibit-quit} is
+non-@code{nil}, then @code{quit-flag} has no special effect.
+@end defvar
+
+@deffn Command keyboard-quit
+This function signals the @code{quit} condition with @code{(signal 'quit
+nil)}.  This is the same thing that quitting does.  (See @code{signal}
+in @ref{Errors}.)
+@end deffn
+
+  You can specify a character other than @kbd{C-g} to use for quitting.
+See the function @code{set-input-mode} in @ref{Terminal Input}.
+ 
+@node Prefix Command Arguments
+@section Prefix Command Arguments
+@cindex prefix argument
+@cindex raw prefix argument
+@cindex numeric prefix argument
+
+  Most Emacs commands can use a @dfn{prefix argument}, a number
+specified before the command itself.  (Don't confuse prefix arguments
+with prefix keys.)  The prefix argument is represented by a value that
+is always available (though it may be @code{nil}, meaning there is no
+prefix argument).  Each command may use the prefix argument or ignore
+it.
+
+  There are two representations of the prefix argument: @dfn{raw} and
+@dfn{numeric}.  The editor command loop uses the raw representation
+internally, and so do the Lisp variables that store the information, but
+commands can request either representation.
+
+  Here are the possible values of a raw prefix argument:
+
+@itemize @bullet
+@item
+@code{nil}, meaning there is no prefix argument.  Its numeric value is
+1, but numerous commands make a distinction between @code{nil} and the
+integer 1.
+
+@item
+An integer, which stands for itself.
+
+@item
+A list of one element, which is an integer.  This form of prefix
+argument results from one or a succession of @kbd{C-u}'s with no
+digits.  The numeric value is the integer in the list, but some
+commands make a distinction between such a list and an integer alone.
+
+@item
+The symbol @code{-}.  This indicates that @kbd{M--} or @kbd{C-u -} was
+typed, without following digits.  The equivalent numeric value is
+@minus{}1, but some commands make a distinction between the integer
+@minus{}1 and the symbol @code{-}.
+@end itemize
+
+The various possibilities may be illustrated by calling the following
+function with various prefixes:
+
+@example
+@group
+(defun display-prefix (arg)
+  "Display the value of the raw prefix arg."
+  (interactive "P")
+  (message "%s" arg))
+@end group
+@end example
+
+@noindent
+Here are the results of calling @code{display-prefix} with various
+raw prefix arguments:
+
+@example
+        M-x display-prefix  @print{} nil
+
+C-u     M-x display-prefix  @print{} (4)
+
+C-u C-u M-x display-prefix  @print{} (16)
+
+C-u 3   M-x display-prefix  @print{} 3
+
+M-3     M-x display-prefix  @print{} 3      ; @r{(Same as @code{C-u 3}.)}
+
+C-u -   M-x display-prefix  @print{} -      
+
+M- -    M-x display-prefix  @print{} -      ; @r{(Same as @code{C-u -}.)}
+
+C-u -7  M-x display-prefix  @print{} -7     
+
+M- -7   M-x display-prefix  @print{} -7     ; @r{(Same as @code{C-u -7}.)}
+@end example
+
+  Emacs uses two variables to store the prefix argument:
+@code{prefix-arg} and @code{current-prefix-arg}.  Commands such as
+@code{universal-argument} that set up prefix arguments for other
+commands store them in @code{prefix-arg}.  In contrast,
+@code{current-prefix-arg} conveys the prefix argument to the current
+command, so setting it has no effect on the prefix arguments for future
+commands.
+
+  Normally, commands specify which representation to use for the prefix
+argument, either numeric or raw, in the @code{interactive} declaration.
+(@xref{Interactive Call}.)  Alternatively, functions may look at the
+value of the prefix argument directly in the variable
+@code{current-prefix-arg}, but this is less clean.
+
+  Do not call the functions @code{universal-argument},
+@code{digit-argument}, or @code{negative-argument} unless you intend to
+let the user enter the prefix argument for the @emph{next} command.
+
+@deffn Command universal-argument
+This command reads input and specifies a prefix argument for the
+following command.  Don't call this command yourself unless you know
+what you are doing.
+@end deffn
+
+@deffn Command digit-argument arg
+This command adds to the prefix argument for the following command.  The
+argument @var{arg} is the raw prefix argument as it was before this
+command; it is used to compute the updated prefix argument.  Don't call
+this command yourself unless you know what you are doing.
+@end deffn
+
+@deffn Command negative-argument arg
+This command adds to the numeric argument for the next command.  The
+argument @var{arg} is the raw prefix argument as it was before this
+command; its value is negated to form the new prefix argument.  Don't
+call this command yourself unless you know what you are doing.
+@end deffn
+
+@defun prefix-numeric-value arg
+This function returns the numeric meaning of a valid raw prefix argument
+value, @var{arg}.  The argument may be a symbol, a number, or a list.
+If it is @code{nil}, the value 1 is returned; if it is any other symbol,
+the value @minus{}1 is returned.  If it is a number, that number is
+returned; if it is a list, the @sc{car} of that list (which should be a
+number) is returned.
+@end defun
+
+@defvar current-prefix-arg
+This variable is the value of the raw prefix argument for the
+@emph{current} command.  Commands may examine it directly, but the usual
+way to access it is with @code{(interactive "P")}.
+@end defvar
+
+@defvar prefix-arg
+The value of this variable is the raw prefix argument for the
+@emph{next} editing command.  Commands that specify prefix arguments for
+the following command work by setting this variable.
+@end defvar
+
+@node Recursive Editing
+@section Recursive Editing
+@cindex recursive command loop
+@cindex recursive editing level
+@cindex command loop, recursive
+
+  The Emacs command loop is entered automatically when Emacs starts up. 
+This top-level invocation of the command loop is never exited until the
+Emacs is killed.  Lisp programs can also invoke the command loop.  Since
+this makes more than one activation of the command loop, we call it
+@dfn{recursive editing}.  A recursive editing level has the effect of
+suspending whatever command invoked it and permitting the user to do
+arbitrary editing before resuming that command.
+
+  The commands available during recursive editing are the same ones
+available in the top-level editing loop and defined in the keymaps.
+Only a few special commands exit the recursive editing level; the others
+return to the recursive editing level when finished.  (The special
+commands for exiting are always available, but do nothing when recursive
+editing is not in progress.)
+
+  All command loops, including recursive ones, set up all-purpose error
+handlers so that an error in a command run from the command loop will
+not exit the loop.
+
+@cindex minibuffer input
+  Minibuffer input is a special kind of recursive editing.  It has a few
+special wrinkles, such as enabling display of the minibuffer and the
+minibuffer window, but fewer than you might suppose.  Certain keys
+behave differently in the minibuffer, but that is only because of the
+minibuffer's local map; if you switch windows, you get the usual Emacs
+commands.
+
+@cindex @code{throw} example
+@kindex exit
+@cindex exit recursive editing
+@cindex aborting
+  To invoke a recursive editing level, call the function
+@code{recursive-edit}.  This function contains the command loop; it also
+contains a call to @code{catch} with tag @code{exit}, which makes it
+possible to exit the recursive editing level by throwing to @code{exit}
+(@pxref{Catch and Throw}).  If you throw a value other than @code{t},
+then @code{recursive-edit} returns normally to the function that called
+it.  The command @kbd{C-M-c} (@code{exit-recursive-edit}) does this.
+Throwing a @code{t} value causes @code{recursive-edit} to quit, so that
+control returns to the command loop one level up.  This is called
+@dfn{aborting}, and is done by @kbd{C-]} (@code{abort-recursive-edit}).
+
+  Most applications should not use recursive editing, except as part of
+using the minibuffer.  Usually it is more convenient for the user if you
+change the major mode of the current buffer temporarily to a special
+major mode, which has a command to go back to the previous mode.  (This
+technique is used by the @kbd{w} command in Rmail.)  Or, if you wish to
+give the user different text to edit ``recursively'', create and select
+a new buffer in a special mode.  In this mode, define a command to
+complete the processing and go back to the previous buffer.  (The
+@kbd{m} command in Rmail does this.)
+
+  Recursive edits are useful in debugging.  You can insert a call to
+@code{debug} into a function definition as a sort of breakpoint, so that
+you can look around when the function gets there.  @code{debug} invokes
+a recursive edit but also provides the other features of the debugger.
+
+  Recursive editing levels are also used when you type @kbd{C-r} in
+@code{query-replace} or use @kbd{C-x q} (@code{kbd-macro-query}).
+
+@defun recursive-edit
+@cindex suspend evaluation
+This function invokes the editor command loop.  It is called
+automatically by the initialization of Emacs, to let the user begin
+editing.  When called from a Lisp program, it enters a recursive editing
+level.
+
+  In the following example, the function @code{simple-rec} first
+advances point one word, then enters a recursive edit, printing out a
+message in the echo area.  The user can then do any editing desired, and
+then type @kbd{C-M-c} to exit and continue executing @code{simple-rec}.
+
+@example
+(defun simple-rec ()
+  (forward-word 1)
+  (message "Recursive edit in progress.")
+  (recursive-edit)
+  (forward-word 1))
+     @result{} simple-rec
+(simple-rec)
+     @result{} nil
+@end example
+@end defun
+
+@deffn Command exit-recursive-edit
+This function exits from the innermost recursive edit (including
+minibuffer input).  Its definition is effectively @code{(throw 'exit
+nil)}.  
+@end deffn
+
+@deffn Command abort-recursive-edit
+This function aborts the command that requested the innermost recursive
+edit (including minibuffer input), by signaling @code{quit} 
+after exiting the recursive edit.  Its definition is effectively
+@code{(throw 'exit t)}.  @xref{Quitting}.
+@end deffn
+
+@deffn Command top-level
+This function exits all recursive editing levels; it does not return a
+value, as it jumps completely out of any computation directly back to
+the main command loop.
+@end deffn
+
+@defun recursion-depth
+This function returns the current depth of recursive edits.  When no
+recursive edit is active, it returns 0.
+@end defun
+
+@node Disabling Commands
+@section Disabling Commands
+@cindex disabled command
+
+  @dfn{Disabling a command} marks the command as requiring user
+confirmation before it can be executed.  Disabling is used for commands
+which might be confusing to beginning users, to prevent them from using
+the commands by accident.
+
+@kindex disabled
+  The low-level mechanism for disabling a command is to put a
+non-@code{nil} @code{disabled} property on the Lisp symbol for the
+command.  These properties are normally set up by the user's
+@file{.emacs} file with Lisp expressions such as this:
+
+@example
+(put 'upcase-region 'disabled t)
+@end example
+
+@noindent
+For a few commands, these properties are present by default and may be
+removed by the @file{.emacs} file.
+
+  If the value of the @code{disabled} property is a string, that string
+is included in the message printed when the command is used:
+
+@example
+(put 'delete-region 'disabled
+     "Text deleted this way cannot be yanked back!\n")
+@end example
+
+  @xref{Disabling,,, emacs, The GNU Emacs Manual}, for the details on
+what happens when a disabled command is invoked interactively.
+Disabling a command has no effect on calling it as a function from Lisp
+programs.
+
+@deffn Command enable-command command
+Allow @var{command} to be executed without special confirmation from now
+on.  The user's @file{.emacs} file is optionally altered so that this
+will apply to future sessions.  
+@end deffn
+
+@deffn Command disable-command command
+Require special confirmation to execute @var{command} from now on.  The
+user's @file{.emacs} file is optionally altered so that this will apply
+to future sessions.  
+@end deffn
+
+@defvar disabled-command-hook
+This variable is a normal hook that is run instead of a disabled command,
+when the user runs the disabled command interactively.  The hook functions
+can use @code{this-command-keys} to determine what the user typed to run
+the command, and thus find the command itself.
+
+By default, @code{disabled-command-hook} contains a function that asks
+the user whether to proceed.
+@end defvar
+
+@node Command History
+@section Command History
+@cindex command history
+@cindex complex command
+@cindex history of commands
+
+  The command loop keeps a history of the complex commands that have
+been executed, to make it convenient to repeat these commands.  A
+@dfn{complex command} is one for which the interactive argument reading
+uses the minibuffer.  This includes any @kbd{M-x} command, any
+@kbd{M-ESC} command, and any command whose @code{interactive}
+specification reads an argument from the minibuffer.  Explicit use of
+the minibuffer during the execution of the command itself does not cause
+the command to be considered complex.
+
+@defvar command-history
+This variable's value is a list of recent complex commands, each
+represented as a form to evaluate.  It continues to accumulate all
+complex commands for the duration of the editing session, but all but
+the first (most recent) thirty elements are deleted when a garbage
+collection takes place (@pxref{Garbage Collection}).
+
+@example
+@group
+command-history
+@result{} ((switch-to-buffer "chistory.texi")
+    (describe-key "^X^[")
+    (visit-tags-table "~/emacs/src/")
+    (find-tag "repeat-complex-command"))
+@end group
+@end example
+@end defvar
+
+  This history list is actually a special case of minibuffer history
+(@pxref{Minibuffer History}), with one special twist: the elements are
+expressions rather than strings.
+
+  There are a number of commands devoted to the editing and recall of
+previous commands.  The commands @code{repeat-complex-command}, and
+@code{list-command-history} are described in the user manual
+(@pxref{Repetition,,, emacs, The GNU Emacs Manual}).  Within the
+minibuffer, the history commands used are the same ones available in any
+minibuffer.
+
+@node Keyboard Macros
+@section Keyboard Macros
+@cindex keyboard macros
+
+  A @dfn{keyboard macro} is a canned sequence of input events that can
+be considered a command and made the definition of a key.  Don't confuse
+keyboard macros with Lisp macros (@pxref{Macros}).
+
+@defun execute-kbd-macro macro &optional count
+This function executes @var{macro} as a sequence of events.  If
+@var{macro} is a string or vector, then the events in it are executed
+exactly as if they had been input by the user.  The sequence is
+@emph{not} expected to be a single key sequence; normally a keyboard
+macro definition consists of several key sequences concatenated.
+
+If @var{macro} is a symbol, then its function definition is used in
+place of @var{macro}.  If that is another symbol, this process repeats.
+Eventually the result should be a string or vector.  If the result is
+not a symbol, string, or vector, an error is signaled.
+
+The argument @var{count} is a repeat count; @var{macro} is executed that
+many times.  If @var{count} is omitted or @code{nil}, @var{macro} is
+executed once.  If it is 0, @var{macro} is executed over and over until it
+encounters an error or a failing search.  
+@end defun
+
+@defvar last-kbd-macro
+This variable is the definition of the most recently defined keyboard
+macro.  Its value is a string or vector, or @code{nil}.
+@end defvar
+
+@defvar executing-macro
+This variable contains the string or vector that defines the keyboard
+macro that is currently executing.  It is @code{nil} if no macro is
+currently executing.
+@end defvar
+
+@defvar defining-kbd-macro
+This variable indicates whether a keyboard macro is being defined.  It
+is set to @code{t} by @code{start-kbd-macro}, and @code{nil} by
+@code{end-kbd-macro}.  You can use this variable to make a command
+behave differently when run from a keyboard macro (perhaps indirectly by
+calling @code{interactive-p}).  However, do not set this variable
+yourself.
+@end defvar
+
+@ignore @c It's hard to make this format ok.
+  The user-level commands for defining, running and editing keyboard
+macros include @code{call-last-kbd-macro}, @code{insert-kbd-macro},
+@code{start-kbd-macro}, @code{end-kbd-macro}, @code{kbd-macro-query},
+and @code{name-last-kbd-macro}.  
+@end ignore
+
+@c Broke paragraph to prevent overfull hbox. --rjc 15mar92
+  The commands are described in the user's manual (@pxref{Keyboard
+Macros,,, emacs, The GNU Emacs Manual}).
+