Commit caae20c7 authored by Richard M. Stallman's avatar Richard M. Stallman
Browse files

Clarify recent changes.

parent ac7ed642
......@@ -115,7 +115,7 @@ controls the reading of arguments for an interactive call.
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
......@@ -211,12 +211,12 @@ give to that buffer:
@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
......@@ -229,9 +229,9 @@ string (starting with the first character that is not @samp{*} or
@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}
......@@ -747,11 +747,11 @@ input events in a string (@pxref{Strings of Events}).
@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
......
......@@ -199,10 +199,10 @@ its normal size. If the minibuffer is active, this brings the
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
......
......@@ -491,7 +491,6 @@ This parameter describes the range of possible colors that can be used
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}
......@@ -500,6 +499,7 @@ that is the default. The symbol @code{bar} specifies a vertical bar
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
......@@ -1148,10 +1148,13 @@ the top left corner of the inside of @var{frame}.
@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
......@@ -1663,9 +1666,9 @@ supported in some other cases.
@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
......
......@@ -107,13 +107,15 @@ use to print nice-looking hardcopy for the file
@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
......@@ -129,14 +131,18 @@ file @file{etc/DOC}, it is evaluated to obtain a string.
@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
......@@ -382,17 +388,17 @@ about valid events. See also the examples for
@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
......
......@@ -744,7 +744,7 @@ This function selects a coding system for encoding specified text,
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,
......
......@@ -1633,7 +1633,7 @@ they were used as parts of key sequences. Thus, you always get the last
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
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment