@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999
+@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/commands
@node Command Loop, Keymaps, Minibuffers, Top
* 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.
+* Adjusting Point:: Adjustment of point after a command.
* Input Events:: What input looks like when you read it.
* Reading Input:: How to read input events from the keyboard or mouse.
* Special Events:: Events processed immediately and individually.
@subsection Using @code{interactive}
This section describes how to write the @code{interactive} form that
-makes a Lisp function an interactively-callable command.
+makes a Lisp function an interactively-callable command, and how to
+examine a commands's @code{interactive} form.
@defspec interactive arg-descriptor
@cindex argument descriptors
@end group
@end smallexample
-@cindex @samp{*} in interactive
+@cindex @samp{*} in @code{interactive}
@cindex read-only buffers in interactive
If the first character in the string is @samp{*}, then an error is
signaled if the buffer is read-only.
-@cindex @samp{@@} in interactive
+@cindex @samp{@@} in @code{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
@samp{@@}).
@end itemize
+@cindex examining the @code{interactive} form
+@defun interactive-form function
+This function returns the @code{interactive} form of @var{function}. If
+@var{function} is a command (@pxref{Interactive Call}), the value is a
+list of the form @code{(interactive @var{spec})}, where @var{spec} is
+the descriptor specification used by the command's @code{interactive}
+form to compute the function's arguments (@pxref{Using Interactive}).
+If @var{function} is not a command, @code{interactive-form} returns
+@code{nil}.
+@end defun
+
@node Interactive Codes
@comment node-name, next, previous, up
@subsection Code Characters for @code{interactive}
specification. If the key sequence that invoked the command has
@var{n} events that are lists, the @var{n}th @samp{e} provides the
@var{n}th such event. Events that are not lists, such as function keys
-and @sc{ASCII} characters, do not count where @samp{e} is concerned.
+and @sc{ascii} characters, do not count where @samp{e} is concerned.
@item f
A file name of an existing file (@pxref{File Names}). The default
@item F
A file name. The file need not exist. Completion, Default, Prompt.
+@item i
+An irrelevant argument. This code always supplies @code{nil} as
+the argument's value. No I/O.
+
@item k
A key sequence (@pxref{Keymap Terminology}). This keeps reading events
until a command (or undefined command) is found in the current key
@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.
+
+@item z
+A coding system name (a symbol). If the user enters null input, the
+argument value is @code{nil}. @xref{Coding Systems}. Completion,
+Existing, Prompt.
+
+@item Z
+A coding system name (a symbol)---but only if this command has a prefix
+argument. With no prefix argument, @samp{Z} provides @code{nil} as the
+argument value. Completion, Existing, Prompt.
@end table
@node Interactive Examples
supply if the command inquires which events were used to invoke it.
@end defun
-@defun command-execute command &optional record-flag keys
+@defun command-execute command &optional record-flag keys special
@cindex keyboard macro execution
This function executes @var{command}. The argument @var{command} must
satisfy the @code{commandp} predicate; i.e., it must be an interactively
The argument @var{keys}, if given, specifies the sequence of events to
supply if the command inquires which events were used to invoke it.
+
+The argument @var{special}, if given, means to ignore the prefix
+argument and not clear it. This is used for executing special events
+(@pxref{Special Events}).
@end defun
@deffn Command execute-extended-command prefix-argument
buffer-local. @xref{Multiple Displays}.
@end defvar
+@defvar real-last-command
+This variable is set up by Emacs just like @code{last-command},
+but never altered by Lisp programs.
+@end defvar
+
@defvar this-command
@cindex current command
This variable records the name of the command now being executed by
@end defun
@defun this-command-keys-vector
-Like @code{this-command-keys}, except that it always returns
-the events in a vector, so you do never need to deal with the complexities
-of storing input events in a string (@pxref{Strings of Events}).
+Like @code{this-command-keys}, except that it always returns the events
+in a vector, so you don't need to deal with the complexities of storing
+input events in a string (@pxref{Strings of Events}).
+@end defun
+
+@tindex clear-this-command-keys
+@defun clear-this-command-keys
+This function empties out the table of events for
+@code{this-command-keys} to return, and also empties the records that
+the function @code{recent-keys} (@pxref{Recording Input}) will
+subsequently return. This is useful after reading a password, to
+prevent the password from echoing inadvertently as part of the next
+command in certain cases.
@end defun
@defvar last-nonmenu-event
@end example
@noindent
-The value is 5 because that is the @sc{ASCII} code for @kbd{C-e}.
+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.
@xref{Input Focus}.
@end defvar
+@node Adjusting Point
+@section Adjusting Point After Commands
+
+ It is not easy to display a value of point in the middle of a sequence
+of text that has the @code{display} or @code{composition} property. So
+after a command finishes and returns to the command loop, if point is
+within such a sequence, the command loop normally moves point to the
+edge of the sequence.
+
+ A command can inhibit this feature by setting the variable
+@code{disable-point-adjustment}:
+
+@defvar disable-point-adjustment
+@tindex disable-point-adjustment
+If this variable is non-@code{nil} when a command returns to the command
+loop, then the command loop does not check for text properties such as
+@code{display} and @code{composition}, and does not move point out of
+sequences that have these properties.
+
+The command loop sets this variable to @code{nil} before each command,
+so if a command sets it, the effect applies only to that command.
+@end defvar
+
+@defvar global-disable-point-adjustment
+@tindex global-disable-point-adjustment
+If you set this variable to a non-@code{nil} value, the feature of
+moving point out of these sequences is completely turned off.
+@end defvar
+
@node Input Events
@section Input Events
@cindex events
describes the representation and meaning of input events in detail.
@defun eventp object
-This function returns non-@code{nil} if @var{object} is an input event.
-A symbol
+This function returns non-@code{nil} if @var{object} is an input event
+or event type.
+
+Note that any symbol might be used as an event or an event type.
+@code{eventp} cannot distinguish whether a symbol is intended by Lisp
+code to be used as an event. Instead, it distinguishes whether the
+symbol has actually been used in an event that has been read as input in
+the current Emacs session. If a symbol has not yet been so used,
+@code{eventp} returns @code{nil}.
@end defun
@menu
@item meta
The
@tex
-$2^{27}$
+@math{2^{27}}
@end tex
-@ifinfo
+@ifnottex
2**27
-@end ifinfo
+@end ifnottex
bit in the character code indicates a character
typed with the meta key held down.
@item control
The
@tex
-$2^{26}$
+@math{2^{26}}
@end tex
-@ifinfo
+@ifnottex
2**26
-@end ifinfo
-bit in the character code indicates a non-@sc{ASCII}
+@end ifnottex
+bit in the character code indicates a non-@sc{ascii}
control character.
-@sc{ASCII} control characters such as @kbd{C-a} have special basic
+@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
+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
@tex
-$2^{26}$
+@math{2^{26}}
@end tex
-@ifinfo
+@ifnottex
2**26
-@end ifinfo
-(assuming the terminal supports non-@sc{ASCII}
+@end ifnottex
+(assuming the terminal supports non-@sc{ascii}
control characters).
@item shift
The
@tex
-$2^{25}$
+@math{2^{25}}
@end tex
-@ifinfo
+@ifnottex
2**25
-@end ifinfo
-bit in the character code indicates an @sc{ASCII} control
+@end ifnottex
+bit in the character code indicates an @sc{ascii} control
character typed with the shift key held down.
For letters, the basic code itself 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
+@sc{ascii} character set whenever possible, Emacs avoids using the
@tex
-$2^{25}$
+@math{2^{25}}
@end tex
-@ifinfo
+@ifnottex
2**25
-@end ifinfo
+@end ifnottex
bit for those characters.
-However, @sc{ASCII} provides no way to distinguish @kbd{C-A} from
+However, @sc{ascii} provides no way to distinguish @kbd{C-A} from
@kbd{C-a}, so Emacs uses the
@tex
-$2^{25}$
+@math{2^{25}}
@end tex
-@ifinfo
+@ifnottex
2**25
-@end ifinfo
+@end ifnottex
bit in @kbd{C-A} and not in
@kbd{C-a}.
@item hyper
The
@tex
-$2^{24}$
+@math{2^{24}}
@end tex
-@ifinfo
+@ifnottex
2**24
-@end ifinfo
+@end ifnottex
bit in the character code indicates a character
typed with the hyper key held down.
@item super
The
@tex
-$2^{23}$
+@math{2^{23}}
@end tex
-@ifinfo
+@ifnottex
2**23
-@end ifinfo
+@end ifnottex
bit in the character code indicates a character
typed with the super key held down.
@item alt
The
@tex
-$2^{22}$
+@math{2^{22}}
@end tex
-@ifinfo
+@ifnottex
2**22
-@end ifinfo
+@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.)
@table @asis
@item @code{backspace}, @code{tab}, @code{newline}, @code{return}, @code{delete}
-These keys correspond to common @sc{ASCII} control characters that have
+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. If the
+In @sc{ascii}, @kbd{C-i} and @key{TAB} are the same character. If the
terminal can distinguish between them, Emacs conveys the distinction to
Lisp programs by representing the former as the integer 9, and the
latter as the symbol @code{tab}.
symbols in this group. The function @code{read-char} likewise converts
these events into characters.
-In @sc{ASCII}, @key{BS} is really @kbd{C-h}. But @code{backspace}
+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.
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{y} does not have meaningful data. For the vertical line, @var{x}
-does not have meaningful data.
+the symbol @code{mode-line}, @code{header-line}, or
+@code{vertical-line}. For the mode line, @var{y} does not have
+meaningful data. For the vertical line, @var{x} does not have
+meaningful data.
In one special case, @var{buffer-pos} is a list containing a symbol (one
of the symbols listed above) instead of just the symbol. This happens
@cindex repeat events
@cindex double-click events
@cindex triple-click events
+@cindex mouse events, repeated
If you press the same mouse button more than once in quick succession
without moving the mouse, Emacs generates special @dfn{repeat} mouse
(not a repeat event), the value is 1.
@end defun
-@defvar double-click-time
+@defvar double-click-fuzz
To generate repeat events, successive mouse button presses must be at
-the same screen position, and the number of milliseconds between
+approximately the same screen position. The value of
+@code{double-click-fuzz} specifies the maximum number of pixels the
+mouse may be moved between two successive clicks to make a
+double-click.
+@end defvar
+
+@defvar double-click-time
+To generate repeat events, the number of milliseconds between
successive button presses 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
This kind of event indicates that the user deiconified @var{frame} using
the window manager. Its standard definition is @code{ignore}; since the
frame has already been made visible, Emacs has no work to do.
+
+@cindex @code{mouse-wheel} event
+@item (mouse-wheel @var{position} @var{delta})
+This kind of event is generated by moving a wheel on a mouse (such as
+the MS Intellimouse). Its effect is typically a kind of scroll or zoom.
+
+The element @var{delta} describes the amount and direction of the wheel
+rotation. Its absolute value is the number of increments by which the
+wheel was rotated. A negative @var{delta} indicates that the wheel was
+rotated backwards, towards the user, and a positive @var{delta}
+indicates that the wheel was rotated forward, away from the user.
+
+The element @var{position} is a list describing the position of the
+event, in the same format as used in a mouse-click event.
+
+This kind of event is generated only on some kinds of systems.
+
+@cindex @code{drag-n-drop} event
+@item (drag-n-drop @var{position} @var{files})
+This kind of event is generated when a group of files is
+selected in an application outside of Emacs, and then dragged and
+dropped onto an Emacs frame.
+
+The element @var{position} is a list describing the position of the
+event, in the same format as used in a mouse-click event, and
+@var{files} is the list of file names that were dragged and dropped.
+The usual way to handle this event is by visiting these files.
+
+This kind of event is generated, at present, only on some kinds of
+systems.
@end table
If one of these events arrives in the middle of a key sequence---that
@node Accessing Events
@subsection Accessing Events
+@cindex mouse events, accessing the data
+@cindex accessing data of mouse events
This section describes convenient functions for accessing the data in
a mouse button or motion event.
position such events have.
@end defun
+@cindex mouse position list, accessing
These five functions take a position list as described above, and
return various parts of it.
@var{x} and @var{y} values actually found in @var{position}.
@end defun
+@cindex mouse event, timestamp
+@cindex timestamp of a mouse event
@defun posn-timestamp position
Return the timestamp in @var{position}.
@end defun
(- (point-max) (point-min))))
@end example
-Recall that scroll bar events have two integers forming ratio in place
+Recall that scroll bar events have two integers forming a ratio, in place
of a pair of x and y coordinates.
@end defun
@node Strings of Events
@subsection Putting Keyboard Events in Strings
+@cindex keyboard events in strings
+@cindex strings with keyboard events
In most of the places where strings are used, we conceptualize the
string as containing text characters---the same kind of characters found
@itemize @bullet
@item
Use vectors instead of strings for key sequences, when you plan to use
-them for anything other than as arguments @code{lookup-key} and
+them for anything other than as arguments to @code{lookup-key} and
@code{define-key}. For example, you can use
@code{read-key-sequence-vector} instead of @code{read-key-sequence}, and
@code{this-command-keys-vector} instead of @code{this-command-keys}.
characters. Now the flag that represents the Meta modifier in a
character is
@tex
-$2^{27}$
+@math{2^{27}}
@end tex
-@ifinfo
+@ifnottex
2**27
-@end ifinfo
+@end ifnottex
and such numbers cannot be included in a string.
To support programs with @samp{\M-} in string constants, there are
special rules for including certain meta characters in a string.
-Here are the rules for interpreting keyboard
+Here are the rules for interpreting a string as a sequence of input
+characters:
@itemize @bullet
@item
@item
The meta variants of those characters, with codes in the range of
@tex
-$2^{27}$
+@math{2^{27}}
@end tex
-@ifinfo
+@ifnottex
2**27
-@end ifinfo
+@end ifnottex
to
@tex
-$2^{27} + 127$,
+@math{2^{27} + 127},
@end tex
-@ifinfo
+@ifnottex
2**27+127,
-@end ifinfo
+@end ifnottex
can also go in the string, but you must change their
numeric values. You must set the
@tex
-$2^{7}$
+@math{2^{7}}
@end tex
-@ifinfo
+@ifnottex
2**7
-@end ifinfo
+@end ifnottex
bit instead of the
@tex
-$2^{27}$
+@math{2^{27}}
@end tex
-@ifinfo
+@ifnottex
2**27
-@end ifinfo
+@end ifnottex
bit, resulting in a value between 128 and 255. Only a unibyte string
can include these codes.
@item
-Non-@sc{ASCII} characters above 256 can be included in a multibyte string.
+Non-@sc{ascii} characters above 256 can be included in a multibyte string.
@item
Other keyboard character events cannot fit in a string. This includes
@menu
* Key Sequence Input:: How to read one key sequence.
* Reading One Event:: How to read just one event.
+* Invoking the Input Method:: How reading an event uses the input method.
* Quoted Character Input:: Asking the user to specify a character.
* Event Input Misc:: How to reread or throw away input events.
@end menu
miscellaneous window events so that they never appear in a key sequence
with any other events.
+@cindex @code{header-line} prefix key
+@cindex @code{mode-line} prefix key
+@cindex @code{vertical-line} prefix key
+@cindex @code{horizontal-scroll-bar} prefix key
+@cindex @code{vertical-scroll-bar} prefix key
+@cindex @code{menu-bar} prefix key
+@cindex mouse events, in special parts of frame
When mouse events occur in special parts of a window, such as a mode
line or a scroll bar, the event type shows nothing special---it is the
same symbol that would normally represent that combination of mouse
button and modifier keys. The information about the window part 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}. You can define meanings for mouse clicks in
-special window parts by defining key sequences using these imaginary
-prefix keys.
+``prefix keys'', all of which are symbols: @code{header-line},
+@code{horizontal-scroll-bar}, @code{menu-bar}, @code{mode-line},
+@code{vertical-line}, and @code{vertical-scroll-bar}. You can define
+meanings for mouse clicks in special window parts by defining key
+sequences using these imaginary prefix keys.
For example, if you call @code{read-key-sequence} and then click the
mouse on the window's mode line, you get two events, like this:
and key sequences read from keyboard macros being executed.
@end defvar
-@tindex num-nonmacro-input-events
@defvar num-nonmacro-input-events
This variable holds the total number of input events received so far
from the terminal---not counting those generated by keyboard macros.
@node Reading One Event
@subsection Reading One Event
+@cindex reading a single event
+@cindex event, reading only one
The lowest level functions for command input are those that read a
single event.
-@defun read-event
+@defun read-event &optional prompt inherit-input-method
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}
-prompts by echoing: it displays descriptions of the events that led to
-or were read by the current command. @xref{The Echo Area}.
+If the optional argument @var{prompt} is non-@code{nil}, it should be a
+string to display in the echo area as a prompt. Otherwise,
+@code{read-event} does not display any message to indicate it is waiting
+for input; instead, it prompts by echoing: it displays descriptions of
+the events that led to or were read by the current command. @xref{The
+Echo Area}.
+
+If @var{inherit-input-method} is non-@code{nil}, then the current input
+method (if any) is employed to make it possible to enter a
+non-@sc{ascii} character. Otherwise, input method handling is disabled
+for reading this event.
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.
+If @code{read-event} gets an event that is defined as a help character, in
+some cases @code{read-event} processes the event directly without
+returning. @xref{Help Functions}. Certain other events, called
+@dfn{special events}, are also processed directly within
+@code{read-event} (@pxref{Special Events}).
+
Here is what happens if you call @code{read-event} and then press the
right-arrow function key:
@end example
@end defun
-@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.
+@defun read-char &optional prompt inherit-input-method
+This function reads and returns a character of command input. If the
+user generates an event which is not a character (i.e. a mouse click or
+function key event), @code{read-char} signals an error. The arguments
+work as in @code{read-event}.
-In the first example, the user types the character @kbd{1} (@sc{ASCII}
+In the first example, the user types the character @kbd{1} (@sc{ascii}
code 49). The second example shows a keyboard macro definition that
calls @code{read-char} from the minibuffer using @code{eval-expression}.
@code{read-char} reads the keyboard macro's very next character, which
@end example
@end defun
+@defun read-char-exclusive &optional prompt inherit-input-method
+This function reads and returns a character of command input. If the
+user generates an event which is not a character,
+@code{read-char-exclusive} ignores it and reads another event, until it
+gets a character. The arguments work as in @code{read-event}.
+@end defun
+
+@node Invoking the Input Method
+@subsection Invoking the Input Method
+
+ The event-reading functions invoke the current input method, if any
+(@pxref{Input Methods}). If the value of @code{input-method-function}
+is non-@code{nil}, it should be a function; when @code{read-event} reads
+a printing character (including @key{SPC}) with no modifier bits, it
+calls that function, passing the character as an argument.
+
+@defvar input-method-function
+If this is non-@code{nil}, its value specifies the current input method
+function.
+
+@strong{Note:} Don't bind this variable with @code{let}. It is often
+buffer-local, and if you bind it around reading input (which is exactly
+when you @emph{would} bind it), switching buffers asynchronously while
+Emacs is waiting will cause the value to be restored in the wrong
+buffer.
+@end defvar
+
+ The input method function should return a list of events which should
+be used as input. (If the list is @code{nil}, that means there is no
+input, so @code{read-event} waits for another event.) These events are
+processed before the events in @code{unread-command-events}
+(@pxref{Event Input Misc}). Events
+returned by the input method function are not passed to the input method
+function again, even if they are printing characters with no modifier
+bits.
+
+ If the input method function calls @code{read-event} or
+@code{read-key-sequence}, it should bind @code{input-method-function} to
+@code{nil} first, to prevent recursion.
+
+ The input method function is not called when reading the second and
+subsequent events of a key sequence. Thus, these characters are not
+subject to input method processing. The input method function should
+test the values of @code{overriding-local-map} and
+@code{overriding-terminal-local-map}; if either of these variables is
+non-@code{nil}, the input method should put its argument into a list and
+return that list with no further processing.
+
@node Quoted Character Input
@subsection Quoted Character Input
@cindex quoted character input
This section describes how to ``peek ahead'' at events without using
them up, how to check for pending input, and how to discard pending
-input.
+input. See also the function @code{read-passwd} (@pxref{Reading a
+Password}).
@defvar unread-command-events
@cindex next input
as part of a command or explicitly by a Lisp program.
In the example below, the Lisp program reads the character @kbd{1},
-@sc{ASCII} code 49. It becomes the value of @code{last-input-event},
+@sc{ascii} code 49. It becomes the value of @code{last-input-event},
while @kbd{C-e} (we assume @kbd{C-x C-e} command is used to evaluate
this expression) remains the value of @code{last-command-event}.
@var{seconds}. If the system doesn't support waiting fractions of a
second, 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)}.
+The expression @code{(sit-for 0)} is a convenient way to request a
+redisplay, without any delay. @xref{Forcing Redisplay}.
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
@emph{next} editing command. Commands such as @code{universal-argument}
that specify prefix arguments for the following command work by setting
this variable.
+@end defvar
+
+@defvar last-prefix-arg
+The raw prefix argument value used by the previous command.
@end defvar
The following commands exist to set up prefix arguments for the
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:
+init file (@pxref{Init 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.
+For a few commands, these properties are present by default (you can
+remove them in your init file if you wish).
If the value of the @code{disabled} property is a string, the message
saying the command is disabled includes that string. For example:
@deffn Command enable-command command
Allow @var{command} to be executed without special confirmation from now
-on, and (if the user confirms) alter the user's @file{.emacs} file so
-that this will apply to future sessions.
+on, and (if the user confirms) alter the user's init file (@pxref{Init
+File}) 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, and
-(if the user confirms) alter the user's @file{.emacs} file so that this
+(if the user confirms) alter the user's init file so that this
will apply to future sessions.
@end deffn
@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}).
+complex commands for the duration of the editing session, but when it
+reaches the maximum size (specified by the variable
+@code{history-length}), the oldest elements are deleted as new ones are
+added.
@example
@group
buffer-local. @xref{Multiple Displays}.
@end defvar
+@defvar kbd-macro-termination-hook
+This normal hook (@pxref{Standard Hooks}) is run when a keyboard
+macro terminates, regardless of what caused it to terminate (reaching
+the macro end or an error which ended the macro prematurely).
+@end defvar