Clarify recent changes.

6 files changed, 56 insertions, 47 deletions

diff --git a/lispref/commands.texi b/lispref/commands.texi
index 5882f261615..343617c6169 100644
--- a/lispref/commands.texi
+++ b/lispref/commands.texi
@@ -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
diff --git a/lispref/display.texi b/lispref/display.texi
index 5198657c273..b6d5a54ae62 100644
--- a/lispref/display.texi
+++ b/lispref/display.texi
@@ -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
diff --git a/lispref/frames.texi b/lispref/frames.texi
index 3a769695f49..0e78b88aa8a 100644
--- a/lispref/frames.texi
+++ b/lispref/frames.texi
@@ -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
diff --git a/lispref/help.texi b/lispref/help.texi
index a601825d053..eb9dc0a75d7 100644
--- a/lispref/help.texi
+++ b/lispref/help.texi
@@ -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
diff --git a/lispref/nonascii.texi b/lispref/nonascii.texi
index d412555eef4..0e67bcb0c4e 100644
--- a/lispref/nonascii.texi
+++ b/lispref/nonascii.texi
@@ -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,
diff --git a/lispref/os.texi b/lispref/os.texi
index fcab89e72ef..6c4a86e3bbe 100644
--- a/lispref/os.texi
+++ b/lispref/os.texi
@@ -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