This section describes how to write the @code{interactive} form that
makes a Lisp function an interactively-callable command, and how to
-obtain the interactive form of a command.
+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 obtaining interactive form of a function
+@cindex examining the @code{interactive} form
@defun interactive-form function
-This function returns the interactive form of @var{function}. If
+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}
@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 cause the function
-@code{recent-keys} (@pxref{Recording Input}) to return an empty
-vector. This is useful after reading a password, to prevent the
-password from echoing inadvertently as part of the next command in
-certain cases.
+@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
minibuffer contents back onto the screen immediately.
@vindex message-truncate-lines
-Normally, displaying a message that is longer than one line resizes
-the echo area to display the entire message. But if the variable
-@code{message-truncate-lines} is non-@code{nil}, the echo area does
-not resize, and the message is truncated, as in Emacs 20 and before.
+Normally, displaying a long message resizes the echo area to display
+the entire message. But if the variable @code{message-truncate-lines}
+is non-@code{nil}, the echo area does not resize, and the message is
+truncated to fit it, as in Emacs 20 and before.
@example
@group
in this frame. Its value is @code{color}, @code{grayscale} or
@code{mono}.
-@vindex cursor-type
@item cursor-type
The way to display the cursor. The legitimate values are @code{bar},
@code{box}, and @code{(bar . @var{width})}. The symbol @code{box}
between characters as the cursor. @code{(bar . @var{width})} specifies
a bar @var{width} pixels wide.
+@vindex cursor-type
The buffer-local variable @code{cursor-type} overrides the value of
the @code{cursor-type} frame parameter, and can in addition have
values @code{t} (use the cursor specified for the frame) and
@end defun
@defvar mouse-position-function
-If non-nil, the value of this variable is a function applied to the
-normal result of @code{mouse-position}. This abnormal hook exists for
-the benefit of packages like XTerm-mouse which need to do mouse
-handling at the Lisp level.
+If non-@code{nil}, the value of this variable is a function for
+@code{mouse-position} to call. @code{mouse-position} calls this
+function just before returning, with its normal return value as the
+sole argument, and it returns whatever this function returns to it.
+
+This abnormal hook exists for the benefit of packages like
+@file{xt-mouse.el} that need to do mouse handling at the Lisp level.
@end defvar
@defun set-mouse-position frame x y
@defun display-images-p &optional display
This function returns @code{t} if @var{display} can display images.
-Windowed displays normally can display images, but some systems can
-lack the necessary support for that. If images aren't supported, the
-tool bar cannot be displayed.
+Windowed displays ought in principle to handle images, but some
+systems lack the support for that. On a display that does not support
+images, Emacs cannot display a tool bar.
@end defun
@defun display-screens &optional display
@section Access to Documentation Strings
@defun documentation-property symbol property &optional verbatim
-This function returns the documentation string that is recorded
-in @var{symbol}'s property list under property @var{property}. It
-retrieves the text from a file if necessary, and runs
-@code{substitute-command-keys} to substitute actual key bindings. (This
-substitution is not done if @var{verbatim} is non-@code{nil}.) If
-@var{property} isn't a string and doesn't refer to the documentation
-file @file{etc/DOC}, it is evaluated to obtain a string.
+This function returns the documentation string that is recorded in
+@var{symbol}'s property list under property @var{property}. It
+retrieves the text from a file if the value calls for that. If the
+property value isn't @code{nil}, isn't a string, and doesn't refer to
+text in a file, then it is evaluated to obtain a string.
+
+Finally, @code{documentation-property} passes the string through
+@code{substitute-command-keys} to substitute actual key bindings,
+unless @var{verbatim} is non-@code{nil}.
@smallexample
@group
@end defun
@defun documentation function &optional verbatim
-This function returns the documentation string of @var{function}. If
-@var{function} is a symbol, this function looks for a
-@code{function-documentation'} property of that symbol; if it has a
-non-@code{nil} value, the documentation is taken from that value (if
-the value is not a string, it is evaluated). Alternatively,
-@code{documentation} reads the text from a file if necessary. Then
-(unless @var{verbatim} is non-@code{nil}) it calls
-@code{substitute-command-keys}, to return a value containing the
+This function returns the documentation string of @var{function}.
+
+If @var{function} is a symbol, this function first looks for the
+@code{function-documentation} property of that symbol; if that has a
+non-@code{nil} value, the documentation comes from that value (if the
+value is not a string, it is evaluated). If @var{function} is not a
+symbol, or if it has no @code{function-documentation} property, then
+@code{documentation} extracts the documentation string from the actual
+function definition, reading it from a file if called for.
+
+Finally, unless @var{verbatim} is non-@code{nil}, it calls
+@code{substitute-command-keys} so as to return a value containing the
actual (current) key bindings.
The function @code{documentation} signals a @code{void-function} error
@cindex control character printing
@cindex meta character printing
This function returns a string describing @var{event} in the standard
-Emacs notation for keyboard input. A normal printing character appears
-as itself, but a control character turns into a string starting with
-@samp{C-}, a meta character turns into a string starting with @samp{M-},
-and space, tab, etc.@: appear as @samp{SPC}, @samp{TAB}, etc. A
-function key symbol appears as itsels, but inside angle brackets
-@samp{<>}. An event that is a list appears as the name of the symbol
-in the @sc{car} of the list, inside angle brackets.
+Emacs notation for keyboard input. A normal printing character
+appears as itself, but a control character turns into a string
+starting with @samp{C-}, a meta character turns into a string starting
+with @samp{M-}, and space, tab, etc.@: appear as @samp{SPC},
+@samp{TAB}, etc. A function key symbol appears inside angle brackets
+@samp{<@dots{}>}. An event that is a list appears as the name of the
+symbol in the @sc{car} of the list, inside angle brackets.
If the optional argument @var{no-angles} is non-@code{nil}, the angle
brackets around function keys and event symbols are omitted; this is
-for compatibility with old versions of Emacs which didn't print the
+for compatibility with old versions of Emacs which didn't use the
brackets.
@smallexample
asking the user to choose if necessary. Normally the specified text
is the text in the current buffer between @var{from} and @var{to},
defaulting to the whole buffer if they are @code{nil}. If @var{from}
-is a string, the string is the target text, and @var{to} is ignored.
+is a string, the string is the specified text, and @var{to} is ignored.
If @var{default-coding-system} is non-@code{nil}, that is the first
coding system to try; if that can handle the text,
should be enough to see the events that invoked the macros.)
A call to @code{clear-this-command-keys} (@pxref{Command Loop Info})
-causes this function to return an empty vector.
+causes this function to return an empty vector immediately afterward.
@end defun
@deffn Command open-dribble-file filename