*** empty log message ***

9 files changed, 318 insertions, 204 deletions

diff --git a/lispref/commands.texi b/lispref/commands.texi
index e2878eee00d..c831c9735a5 100644
--- a/lispref/commands.texi
+++ b/lispref/commands.texi
@@ -71,6 +71,7 @@ character causes @dfn{quitting} (@pxref{Quitting}).
 The editor command loop runs this normal hook before each command.  At
 that time, @code{this-command} contains the command that is about to
 run, and @code{last-command} describes the previous command.
+@xref{Hooks}.
 @end defvar
 
 @defvar post-command-hook
@@ -78,9 +79,44 @@ The editor command loop runs this normal hook after each command
 (including commands terminated prematurely by quitting or by errors),
 and also when the command loop is first entered.  At that time,
 @code{this-command} describes the command that just ran, and
-@code{last-command} describes the command before that.
+@code{last-command} describes the command before that.  @xref{Hooks}.
 @end defvar
 
+  An erroneous function in the @code{pre-command-hook} list could easily
+make Emacs go into an infinite loop of errors.  To protect you from this
+sort of painful problem, Emacs sets the hook variable to @code{nil}
+temporarily while running the functions in the hook.  Thus, if a hook
+function gets an error, the hook variable is left as @code{nil}.  Emacs
+does the same thing for @code{post-command-hook}.
+
+  Quitting is suppressed while running @code{pre-command-hook} and
+@code{post-command-hook}; this is because otherwise a quit, happening by
+chance within one of these hooks, would turn off the hook.
+
+  One inconvenient result of these protective features is that you
+cannot have a function in @code{post-command-hook} or
+@code{pre-command-hook} which changes the value of that variable.  But
+that's not a real limitation.  If you want hook functions to change the
+hook, simply add one fixed function to the hook, and code that function
+to look in another hook variable for other functions to call.  Here is
+an example:
+
+@example
+;; @r{Set up the mechanism.}
+(defvar current-post-command-function nil)
+(defun run-current-post-command-function ()
+  (if current-post-command-function
+      (funcall current-post-command-function)))
+(add-hooks 'post-command-hook 
+           'run-current-post-command-function)
+
+;; @r{Here's a hook function which replaces itself}
+;; @r{with a different hook function to run next time.}
+(defun first-post-command-function ()
+  (setq current-post-command-function
+        'second-post-command-function))
+@end example
+
 @node Defining Commands
 @section Defining Commands
 @cindex defining commands
@@ -89,7 +125,7 @@ and also when the command loop is first entered.  At that time,
 @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
+level, a form that 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.
@@ -165,9 +201,10 @@ 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:
+(starting with the first argument) 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
@@ -251,7 +288,7 @@ 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,
+A function name (i.e., a symbol satisfying @code{fboundp}).  Existing,
 Completion, Prompt.
 
 @item b
@@ -262,7 +299,7 @@ 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.
+Default, Prompt.
 
 @item c
 A character.  The cursor does not move into the echo area.  Prompt.
@@ -282,13 +319,13 @@ 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
+More precisely, @samp{e} gets events that 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
+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 which are not lists, such as function keys
+@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.
 
 @item f
@@ -320,16 +357,17 @@ Prompt.
 @item N
 @cindex raw prefix argument usage
 The raw prefix argument.  If the prefix argument is @code{nil}, then
-read a number as with @kbd{n}.  Requires a number.  Prompt.
+read a number as with @kbd{n}.  Requires a number.  @xref{Prefix Command
+Arguments}.  Prompt.
 
 @item p
 @cindex numeric prefix argument usage
 The numeric prefix argument.  (Note that this @samp{p} is lower case.)
-No I/O.@refill
+No I/O.
 
 @item P
-The raw prefix argument.  (Note that this @samp{P} is upper case.)
-@xref{Prefix Command Arguments}.  No I/O.@refill
+The raw prefix argument.  (Note that this @samp{P} is upper case.)  No
+I/O.
 
 @item r
 @cindex region argument
@@ -355,7 +393,7 @@ A variable declared to be a user option (i.e., satisfying the predicate
 Completion, Prompt.
 
 @item x
-A Lisp object specified in printed representation, terminated with a
+A Lisp object, specified with its read syntax, terminated with a
 @key{LFD} or @key{RET}.  The object is not evaluated.  @xref{Object from
 Minibuffer}.  Prompt.
 
@@ -451,9 +489,10 @@ realistic example of using @code{commandp}.
 @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.
+An error is signaled if @var{command} is not a function or if it cannot
+be called interactively (i.e., is not a command).  Note that keyboard
+macros (strings and vectors) are not accepted, even though they are
+considered commands, because they are not functions.
 
 @cindex record command history
 If @var{record-flag} is non-@code{nil}, then this command and its
@@ -505,7 +544,7 @@ part of the prompt.
 @group
 (execute-extended-command 1)
 ---------- Buffer: Minibuffer ----------
-M-x forward-word RET
+1 M-x forward-word RET
 ---------- Buffer: Minibuffer ----------
      @result{} t
 @end group
@@ -622,7 +661,7 @@ if all those events were characters.  @xref{Input Events}.
 @example
 @group
 (this-command-keys)
-;; @r{Now type @kbd{C-u C-x C-e}.}
+;; @r{Now use @kbd{C-u C-x C-e} to evaluate that.}
      @result{} "^U^X^E"
 @end group
 @end example
@@ -646,7 +685,7 @@ character to insert.
 @example
 @group
 last-command-event
-;; @r{Now type @kbd{C-u C-x C-e}.}
+;; @r{Now use @kbd{C-u C-x C-e} to evaluate that.}
      @result{} 5
 @end group
 @end example
@@ -781,7 +820,7 @@ function @code{event-modifiers} (@pxref{Classifying Events}).
 @subsection Function Keys
 
 @cindex function keys
-Most keyboards also have @dfn{function keys}---keys which have names or
+Most keyboards also have @dfn{function keys}---keys that 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, in lower
 case.  For example, pressing a key labeled @key{F1} places the symbol
@@ -790,7 +829,7 @@ case.  For example, pressing a key labeled @key{F1} places the symbol
 The event type of a function key event is the event symbol itself.
 @xref{Classifying Events}.
 
-Here are a few special cases in the symbol naming convention for
+Here are a few special cases in the symbol-naming convention for
 function keys:
 
 @table @asis
@@ -813,19 +852,25 @@ 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{left}, @code{up}, @code{right}, @code{down}
+Cursor arrow keys
 @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
+@item @code{kp-home}, @code{kp-left}, @code{kp-up}, @code{kp-right}, @code{kp-down}
+Keypad arrow keys.  Emacs normally translates these
+into the non-keypad keys @code{home}, @code{left}, @dots{}
+@item @code{kp-prior}, @code{kp-next}, @code{kp-end}, @code{kp-begin}, @code{kp-insert}, @code{kp-delete}
+Additional keypad duplicates of keys ordinarily found elsewhere.  Emacs
+normally translates these into the like-named non-keypad 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:
+You can use the modifier keys @key{ALT}, @key{CTRL}, @key{HYPER},
+@key{META}, @key{SHIFT}, and @key{SUPER} with function keys.  The way to
+represent them is with prefixes in the symbol name:
 
 @table @samp
 @item A-
@@ -905,8 +950,8 @@ describe events by their types; thus, if there is a key binding for
 This is the window in which the click occurred.
 
 @item @var{x}, @var{y}
-These are the pixel-based coordinates of the click, relative to the top
-left corner of @var{window}, which is @code{(0 . 0)}.
+These are the pixel-denominated coordinates of the click, relative to
+the top left corner of @var{window}, which is @code{(0 . 0)}.
 
 @item @var{buffer-pos}
 This is the buffer position of the character clicked on.
@@ -938,10 +983,10 @@ 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.
 
-@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}.
+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
+after the imaginary prefix keys for the event are inserted into the
+input stream.  @xref{Key Sequence Input}.
 
 @node Drag Events
 @subsection Drag Events
@@ -972,7 +1017,7 @@ 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
+If @code{read-key-sequence} receives a drag event that 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
@@ -989,17 +1034,17 @@ 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
+pressed.  They are represented by lists that look exactly like click
 events (@pxref{Click Events}), except that the @var{event-type} symbol
 name contains the prefix @samp{down-}.  The @samp{down-} prefix follows
 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.  @xref{Motion Events}.
+The function @code{read-key-sequence}, and therefore the Emacs command
+loop as well, 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.  @xref{Motion Events}.
 
 @node Repeat Events
 @subsection Repeat Events
@@ -1039,7 +1084,7 @@ 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.
+were an ordinary drag.
 
 Before the double-click or double-drag event, Emacs generates a
 @dfn{double-down} event when the user presses the button down for the
@@ -1050,8 +1095,9 @@ 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.
+away, Emacs generates a down event and a click event for the first
+click, a double-down event when you press the button again, and finally
+either a double-click or a double-drag event.
 
 If you click a button twice and then press it again, all in quick
 succession, Emacs generates a @dfn{triple-down} event, followed by
@@ -1136,14 +1182,14 @@ Focus events are represented in Lisp as lists that look like this:
 @noindent
 where @var{new-frame} is the frame switched to.
 
-Most X window 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 a 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.
+Most X 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 a 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
@@ -1188,12 +1234,12 @@ into another window.  That produces a pair of events like these:
 @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.
+  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 that 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
@@ -1284,7 +1330,7 @@ a mouse button or motion event.
 mouse-button event.  The position is a list of this form:
 
 @example
-(@var{window} @var{buffer-position} (@var{col} . @var{row}) @var{timestamp})
+(@var{window} @var{buffer-position} (@var{x} . @var{y}) @var{timestamp})
 @end example
 
 @defun event-start event
@@ -1304,8 +1350,8 @@ 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.
+  These four functions take a position as described above, and return
+various parts of it.
 
 @defun posn-window position
 Return the window that @var{position} is in.
@@ -1316,8 +1362,8 @@ Return the buffer position in @var{position}.  This is an integer.
 @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})}.
+Return the pixel-based x and y coordinates in @var{position}, as a cons
+cell @code{(@var{x} . @var{y})}.
 @end defun
 
 @defun posn-col-row position
@@ -1330,10 +1376,18 @@ a cons cell @code{(@var{col} . @var{row})}.  These are computed from the
 Return the timestamp in @var{position}.
 @end defun
 
+@defun scroll-bar-event-ratio event
+This function returns the fractional vertical position of a scroll bar
+event within the scroll bar.  The value is a cons cell
+@code{(@var{portion} . @var{whole})} containing two integers whose ratio
+is the fractional 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.  The argument @var{ratio} is not a number, but
-rather a pair @code{(@var{num} . @var{denom})}.
+This function multiplies (in effect) @var{ratio} by @var{total},
+rounding the result to an integer.  The argument @var{ratio} is not a
+number, but rather a pair @code{(@var{num} . @var{denom})}---typically a
+value returned by @code{scroll-bar-event-ratio}.
 
 This function is handy for scaling a position on a scroll bar into a
 buffer position.  Here's how to do that:
@@ -1341,9 +1395,12 @@ buffer position.  Here's how to do that:
 @example
 (+ (point-min)
    (scroll-bar-scale
-      (posn-col-row (event-start event))
+      (posn-x-y (event-start event))
       (- (point-max) (point-min))))
 @end example
+
+Recall that scroll bar events have two integers forming ratio in place
+of a pair of x and y coordinates.
 @end defun
 
 @node Strings of Events
@@ -1351,7 +1408,7 @@ buffer position.  Here's how to do that:
 
   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
+in buffers or files.  Occasionally Lisp programs use strings that
 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
@@ -1407,7 +1464,7 @@ possibility that they might contain meta characters, and by using
 
 @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
+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.
 @end defun
@@ -1485,8 +1542,8 @@ and key sequences read from keyboard macros being executed.
 
 @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 its lower case equivalent has one, then @code{read-key-sequence}
+If an input character is an upper-case letter and has no key binding,
+but its 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.
 
@@ -1522,7 +1579,7 @@ mouse on the window's mode line, you get an event like this:
 @node Reading One Event
 @subsection Reading One Event
 
-  The lowest level functions for command input are those which read a
+  The lowest level functions for command input are those that read a
 single event.
 
 @defun read-event
@@ -1584,10 +1641,10 @@ the echo area.
 @subsection Quoted Character Input
 @cindex quoted character input
 
-  You can use the function @code{read-quoted-char} when to ask 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} uses this function.
+  You can use the function @code{read-quoted-char} to ask the user to
+specify a character, and allow the user to specify a control or meta
+character conveniently, either literally or as an octal character code.
+The command @code{quoted-insert} uses this function.
 
 @defun read-quoted-char &optional prompt
 @cindex octal character input
@@ -1621,8 +1678,7 @@ What character-@kbd{177}
 @end example
 @end defun
 
-@need 3000
-
+@need 2000
 @node Event Input Misc
 @subsection Miscellaneous Event Input Features
 
@@ -1650,8 +1706,8 @@ Likewise, incremental search uses this feature to unread events with no
 special meaning in a search, because these events should exit the search
 and then execute normally.
 
-The reliable and easy way to extract events from a key sequence to put
-them in @code{unread-command-events} is to use
+The reliable and easy way to extract events from a key sequence so as to
+put them in @code{unread-command-events} is to use
 @code{listify-key-sequence} (@pxref{Strings of Events}).
 @end defvar
 
@@ -1780,9 +1836,9 @@ Use @code{sleep-for} when you wish to guarantee a delay.
 @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 a Lisp function is running 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
@@ -1802,13 +1858,13 @@ 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} always quit directly.
 
-  When @kbd{C-g} does directly quit, it does so by the variable
+  When @kbd{C-g} does directly quit, it does so by setting the variable
 @code{quit-flag} to @code{t}.  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, quitting cannot happen just anywhere; only at the
-special places which check @code{quit-flag}.  The reason for this is
+special places that 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.
@@ -1828,13 +1884,12 @@ 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.
+immediately.  This behavior is ideal when you wish to make sure that
+quitting does not happen within a ``critical section'' 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
+handled in a special way that 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
@@ -1884,10 +1939,9 @@ See the function @code{set-input-mode} in @ref{Terminal Input}.
 
   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.
+with prefix keys.)  The prefix argument is at all times represented by a
+value, which may be @code{nil}, meaning there is currently 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
@@ -1964,17 +2018,17 @@ 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
+(@xref{Using Interactive}.)  Alternatively, functions may look at the
 value of the prefix argument directly in the variable
 @code{current-prefix-arg}, but this is less clean.
 
 @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.
+If it is @code{nil}, the value 1 is returned; if it is @code{-}, 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
@@ -2064,12 +2118,12 @@ control returns to the command loop one level up.  This is called
   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.  (The
-@kbd{e} command in Rmail uses this technique.)  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.)
+major mode, which should have a command to go back to the previous mode.
+(The @kbd{e} command in Rmail uses this technique.)  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
@@ -2165,21 +2219,21 @@ programs.
 
 @deffn Command enable-command command
 Allow @var{command} to be executed without special confirmation from now
-on, and optionally 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 @file{.emacs} 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
-optionally alter the user's @file{.emacs} file so that this will apply
-to future sessions.
+(if the user confirms) alter the user's @file{.emacs} file so that this
+will apply to future sessions.
 @end deffn
 
 @defvar disabled-command-hook
 This normal hook is run instead of a disabled command, when the user
 invokes 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.
+command, and thus find the command itself.  @xref{Hooks}.
 
 By default, @code{disabled-command-hook} contains a function that asks
 the user whether to proceed.
diff --git a/lispref/display.texi b/lispref/display.texi
index 165c9bd3259..071b3a569b4 100644
--- a/lispref/display.texi
+++ b/lispref/display.texi
@@ -193,10 +193,14 @@ string.  See @code{format} in @ref{String Conversion}, for the details
 on the conversion specifications.  @code{message} returns the
 constructed string.
 
+In batch mode, @code{message} prints the message text on the standard
+error stream, followed by a newline.
+
 @c Emacs 19 feature
 If @var{string} is @code{nil}, @code{message} clears the echo area.  If
 the minibuffer is active, this brings the minibuffer contents back onto
 the screen immediately.
+
 @example
 @group
 (message "Minibuffer depth is %d."
@@ -881,7 +885,7 @@ The value of @code{blink-paren-function} may be @code{nil}, in which
 case nothing is done.
 
 @quotation
-@strong{Please note:} this variable was named @code{blink-paren-hook} in
+@strong{Please note:} This variable was named @code{blink-paren-hook} in
 older Emacs versions, but since it is not called with the standard
 convention for hooks, it was renamed to @code{blink-paren-function} in
 version 19.
diff --git a/lispref/files.texi b/lispref/files.texi
index 7484de8a4c8..48b63f0e918 100644
--- a/lispref/files.texi
+++ b/lispref/files.texi
@@ -13,6 +13,13 @@ file-related functions of Emacs Lisp, but a few others are described in
 @ref{Buffers}, and those related to backups and auto-saving are
 described in @ref{Backups and Auto-Saving}.
 
+  Many of the file functions take one or more arguments that are file
+names.  A file name is actually a string.  Most of these functions
+expand file name arguments using @code{expand-file-name}, so that
+@file{~} is handled correctly, as are relative file names (including
+@samp{../}).  These functions don't recognize environment variable
+substitutions such as @samp{$HOME}.  @xref{File Name Expansion}.
+
 @menu
 * Visiting Files::           Reading files into Emacs buffers for editing.
 * Saving Buffers::           Writing changed buffers back into files.
@@ -52,7 +59,7 @@ back into the file.
 
   In spite of the distinction between files and buffers, people often
 refer to a file when they mean a buffer and vice-versa.  Indeed, we say,
-``I am editing a file,'' rather than, ``I am editing a buffer which I
+``I am editing a file,'' rather than, ``I am editing a buffer that I
 will soon save as a file of the same name.''  Humans do not usually need
 to make the distinction explicit.  When dealing with a computer program,
 however, it is good to keep the distinction in mind.
@@ -153,7 +160,7 @@ When this command is called interactively, it prompts for
 @end deffn
 
 @deffn Command view-file filename
-This command views @var{filename} in View mode, returning to the
+This command visits @var{filename} in View mode, returning to the
 previous buffer when done.  View mode is a mode that allows you to skim
 rapidly through the file but does not let you modify it.  Entering View
 mode runs the normal hook @code{view-mode-hook}.  @xref{Hooks}.
@@ -256,9 +263,9 @@ Otherwise it does nothing.
 
 @code{save-buffer} is responsible for making backup files.  Normally,
 @var{backup-option} is @code{nil}, and @code{save-buffer} makes a backup
-file only if this is the first save or if the buffer was previously
-modified.  Other values for @var{backup-option} request the making of
-backup files in other circumstances:
+file only if this is the first save since visiting the file.  Other
+values for @var{backup-option} request the making of backup files in
+other circumstances:
 
 @itemize @bullet
 @item
@@ -479,7 +486,7 @@ Normally, @code{write-region} displays a message @samp{Wrote file
 @var{filename}} in the echo area.  If @var{visit} is neither @code{t}
 nor @code{nil} nor a string, then this message is inhibited.  This
 feature is useful for programs that use files for internal purposes,
-files which the user does not need to know about.
+files that the user does not need to know about.
 @end deffn
 
 @node File Locks
@@ -530,7 +537,7 @@ does nothing if the current buffer is not visiting a file.
 
 @defun ask-user-about-lock file other-user
 This function is called when the user tries to modify @var{file}, but it
-is locked by another user name @var{other-user}.  The value it returns
+is locked by another user named @var{other-user}.  The value it returns
 determines what happens next:
 
 @itemize @bullet
@@ -567,19 +574,11 @@ for its usual definition is in @file{userlock.el}.
 @node Information about Files
 @section Information about Files
 
-  The functions described in this section are similar in as much as
-they all operate on strings which are interpreted as file names.  All
-have names that begin with the word @samp{file}.  These functions all
-return information about actual files or directories, so their
-arguments must all exist as actual files or directories unless
-otherwise noted.
-
-  Most of the file-oriented functions take a single argument,
-@var{filename}, which must be a string.  The file name is expanded using
-@code{expand-file-name}, so @file{~} is handled correctly, as are
-relative file names (including @samp{../}).  These functions don't
-recognize environment variable substitutions such as @samp{$HOME}.
-@xref{File Name Expansion}.
+  The functions described in this section all operate on strings that
+designate file names.  All the functions have names that begin with the
+word @samp{file}.  These functions all return information about actual
+files or directories, so their arguments must all exist as actual files
+or directories unless otherwise noted.
 
 @menu
 * Testing Accessibility::   Is a given file readable?  Writable?
@@ -638,11 +637,11 @@ modes permit.
 @end defun
 
 @defun file-writable-p filename
-This function returns @code{t} if the file @var{filename} can be written or
-created by you.  It is writable if the file exists and you can write it.
-It is creatable if the file does not exist, but the specified directory
-does exist and you can write in that directory.  @code{file-writable-p}
-returns @code{nil} otherwise.
+This function returns @code{t} if the file @var{filename} can be written
+or created by you, and @code{nil} otherwise.  A file is writable if the
+file exists and you can write it.  It is creatable if it does not exist,
+but the specified directory does exist and you can write in that
+directory.
 
 In the third example below, @file{foo} is not writable because the
 parent directory does not exist, even though the user could create such
@@ -667,9 +666,10 @@ a directory.
 @c Emacs 19 feature
 @defun file-accessible-directory-p dirname
 This function returns @code{t} if you have permission to open existing
-files in directory @var{dirname}; otherwise (and if there is no such
-directory), it returns @code{nil}.  The value of @var{dirname} may be
-either a directory name or the file name of a directory.
+files in the directory whose name as a file is @var{dirname}; otherwise
+(or if there is no such directory), it returns @code{nil}.  The value
+of @var{dirname} may be either a directory name or the file name of a
+directory.
 
 Example: after the following,
 
@@ -686,14 +686,14 @@ give an error.
 @defun file-newer-than-file-p filename1 filename2
 @cindex file age
 @cindex file modification time
-This functions returns @code{t} if the file @var{filename1} is
+This function returns @code{t} if the file @var{filename1} is
 newer than file @var{filename2}.  If @var{filename1} does not
 exist, it returns @code{nil}.  If @var{filename2} does not exist,
 it returns @code{t}.
 
-In the following example, assume that the file @file{aug-19} was
-written on the 19th, and @file{aug-20} was written on the 20th.  The
-file @file{no-file} doesn't exist at all.
+In the following example, assume that the file @file{aug-19} was written
+on the 19th, @file{aug-20} was written on the 20th, and the file
+@file{no-file} doesn't exist at all.
 
 @example
 @group
@@ -729,8 +729,8 @@ links from ordinary files.
 @cindex file symbolic links
 If the file @var{filename} is a symbolic link, the @code{file-symlink-p}
 function returns the file name to which it is linked.  This may be the
-name of a text file, a directory, or even another symbolic link, or of
-no file at all.
+name of a text file, a directory, or even another symbolic link, or it
+may be a nonexistent file name.
 
 If the file @var{filename} is not a symbolic link (or there is no such file),
 @code{file-symlink-p} returns @code{nil}.  
@@ -822,7 +822,7 @@ and modification.
 This function returns the mode bits of @var{filename}, as an integer.
 The mode bits are also called the file permissions, and they specify
 access control in the usual Unix fashion.  If the low-order bit is 1,
-then the file is executable by all users, if the second lowest-order bit
+then the file is executable by all users, if the second-lowest-order bit
 is 1, then the file is writable by all users, etc.
 
 The highest value returnable is 4095 (7777 octal), meaning that
@@ -920,7 +920,7 @@ The time of last status change as a list of two integers (as above).
 The size of the file in bytes.
 
 @item
-The file's modes, as a string of ten letters or dashes
+The file's modes, as a string of ten letters or dashes,
 as in @samp{ls -l}.
 
 @item
@@ -932,9 +932,9 @@ The file's inode number.
 
 @item
 The file system number of the file system that the file is in.  This
-element together with the file's inode number, give enough information
-to distinguish any two files on the system---no two files can have the
-same values for both of these numbers.
+element and the file's inode number together give enough information to
+distinguish any two files on the system---no two files can have the same
+values for both of these numbers.
 @end enumerate
 
 For example, here are the file attributes for @file{files.texi}:
@@ -1142,9 +1142,9 @@ This command makes a symbolic link to @var{filename}, named
 @var{newname}.  This is like the shell command @samp{ln -s
 @var{filename} @var{newname}}.
 
-In an interactive call, @var{filename} and @var{newname} are read in the
-minibuffer; it requests confirmation if the file @var{newname} already
-exists.
+In an interactive call, this function prompts for @var{filename} and
+@var{newname} in the minibuffer; also, it requests confirmation if
+@var{newname} already exists.
 @end deffn
 
 @defun define-logical-name varname string
@@ -1154,7 +1154,7 @@ This function defines the logical name @var{name} to have the value
 
 @defun set-file-modes filename mode
 This function sets mode bits of @var{filename} to @var{mode} (which must
-be an integer).  Only the 12 low bits of @var{mode} are used.
+be an integer).  Only the low 12 bits of @var{mode} are used.
 @end defun
 
 @c Emacs 19 feature
@@ -1164,7 +1164,7 @@ Emacs and its subprocesses.  Every file created with Emacs initially has
 this protection.  On Unix, the default protection is the bitwise
 complement of the ``umask'' value.
 
-The argument @var{mode} must be an integer.  Only the 9 low bits of
+The argument @var{mode} must be an integer.  Only the low 9 bits of
 @var{mode} are used.
 
 Saving a modified version of an existing file does not count as creating
@@ -1200,10 +1200,10 @@ how to manipulate file names.
 can operate on file names that do not refer to an existing file or
 directory.
 
-  On VMS, all these functions understand both VMS file name syntax and
+  On VMS, all these functions understand both VMS file-name syntax and
 Unix syntax.  This is so that all the standard Lisp libraries can
 specify file names in Unix syntax and work properly on VMS without
-change.  On MS-DOS, these functions understand MS-DOS file name syntax
+change.  On MS-DOS, these functions understand MS-DOS file-name syntax
 as well as Unix syntax.
 
 @menu
@@ -1223,11 +1223,11 @@ as well as Unix syntax.
 @cindex version number (in file name)
 
   The operating system groups files into directories.  To specify a
-file, you must specify the directory, and the file's name in that
-directory.  Therefore, a file name in Emacs is considered to have two
-main parts: the @dfn{directory name} part, and the @dfn{nondirectory}
-part (or @dfn{file name within the directory}).  Either part may be
-empty.  Concatenating these two parts reproduces the original file name.
+file, you must specify the directory and the file's name within that
+directory.  Therefore, Emacs considers a file name as having two main
+parts: the @dfn{directory name} part, and the @dfn{nondirectory} part
+(or @dfn{file name within the directory}).  Either part may be empty.
+Concatenating these two parts reproduces the original file name.
 
   On Unix, the directory part is everything up to and including the last
 slash; the nondirectory part is the rest.  The rules in VMS syntax are
@@ -1327,9 +1327,9 @@ subtle but crucial.  When an Emacs variable or function argument is
 described as being a directory name, a file name of a directory is not
 acceptable.
 
-  These two functions convert between directory names and file names.
-They do nothing special with environment variable substitutions such as
-@samp{$HOME}, and the constructs @samp{~}, and @samp{..}.
+  The following two functions convert between directory names and file
+names.  They do nothing special with environment variable substitutions
+such as @samp{$HOME}, and the constructs @samp{~}, and @samp{..}.
 
 @defun file-name-as-directory filename
 This function returns a string representing @var{filename} in a form
@@ -1510,7 +1510,7 @@ variables; only @code{substitute-in-file-name} does that.
 @c Emacs 19 feature
 @defun file-relative-name filename directory
 This function does the inverse of expansion---it tries to return a
-relative name which is equivalent to @var{filename} when interpreted
+relative name that is equivalent to @var{filename} when interpreted
 relative to @var{directory}.  (If such a relative name would be longer
 than the absolute name, it returns the absolute name instead.)
 
@@ -1598,8 +1598,8 @@ the same name.
 
 @defun make-temp-name string
 This function generates string that can be used as a unique name.  The
-name starts with the prefix @var{string}, and ends with a number that
-is different in each Emacs job.
+name starts with @var{string}, and ends with a number that is different
+in each Emacs job.
 
 @example
 @group
@@ -1756,18 +1756,20 @@ This function returns a list of all versions of the file named
 @end defun
 
 @defun insert-directory file switches &optional wildcard full-directory-p
-This function inserts a directory listing for directory @var{dir},
-formatted with @code{ls} according to @var{switches}.  It leaves point
-after the inserted text.
+This function inserts (in the current buffer) a directory listing for
+directory @var{file}, formatted with @code{ls} according to
+@var{switches}.  It leaves point after the inserted text.
 
-The argument @var{dir} may be either a directory name or a file
+The argument @var{file} may be either a directory name or a file
 specification including wildcard characters.  If @var{wildcard} is
 non-@code{nil}, that means treat @var{file} as a file specification with
 wildcards.
 
 If @var{full-directory-p} is non-@code{nil}, that means @var{file} is a
-directory and switches do not contain @samp{d}, so that a full listing
-is expected.
+directory and switches do not contain @samp{-d}, so that the listing
+should show the full contents of the directory.  (The @samp{-d} option
+to @code{ls} says to describe a directory itself rather than its
+contents.)
 
 This function works by running a directory listing program whose name is
 in the variable @code{insert-directory-program}.  If @var{wildcard} is
@@ -1784,6 +1786,11 @@ for the function @code{insert-directory}.
 @section Creating and Deleting Directories
 @c Emacs 19 features
 
+  Most Emacs Lisp file-manipulation functions get errors when used on
+files that are directories.  For example, you cannot delete a directory
+with @code{delete-file}.  These special functions exist to create and
+delete directories.
+
 @defun make-directory dirname
 This function creates a directory named @var{dirname}.
 @end defun
@@ -1801,11 +1808,11 @@ must use @code{delete-directory} in that case.
 @c Emacs 19 feature
 You can implement special handling for certain file names.  This is
 called making those names @dfn{magic}.  You must supply a regular
-expression to define the class of names (all those which match the
+expression to define the class of names (all those that match the
 regular expression), plus a handler that implements all the primitive
 Emacs file operations for file names that do match.
 
-The value of @code{file-name-handler-alist} is a list of handlers,
+The variable @code{file-name-handler-alist} holds a list of handlers,
 together with regular expressions that determine when to apply each
 handler.  Each element has this form:
 
@@ -1836,7 +1843,7 @@ called like this:
 (funcall @var{handler} 'file-exists-p @var{filename})
 @end example
 
-Here are the operations that you can handle for a magic file name:
+Here are the operations that a magic file name handler gets to handle:
 
 @noindent
 @code{add-name-to-file}, @code{copy-file}, @code{delete-directory},
@@ -1853,17 +1860,18 @@ Here are the operations that you can handle for a magic file name:
 @code{file-name-directory}, @code{file-name-nondirectory},
 @code{file-name-sans-versions}, @code{file-newer-than-file-p},
 @code{file-readable-p}, @code{file-symlink-p}, @code{file-truename},
-@code{file-writable-p},@*
-@code{insert-directory},
+@code{file-writable-p}, @code{insert-directory},@*
 @code{insert-file-contents}, @code{load}, @code{make-directory},
 @code{make-symbolic-link}, @code{rename-file}, @code{set-file-modes},
 @code{set-visited-file-modtime}, @code{unhandled-file-name-directory},
 @code{verify-visited-file-modtime}, @code{write-region}.
 
 The handler function must handle all of the above operations, and
-possibly others to be added in the future.  Therefore, it should always
-reinvoke the ordinary Lisp primitive when it receives an operation it
-does not recognize.  Here's one way to do this:
+possibly others to be added in the future.  It need not implement all
+these operations itself---when it has nothing special to do for a
+certain operation, it can reinvoke the primitive, to handle the
+operation ``in the usual way''.  It should always reinvoke the primitive
+for an operation it does not recognize.  Here's one way to do this:
 
 @smallexample
 (defun my-file-handler (operation &rest args)
@@ -1874,7 +1882,7 @@ does not recognize.  Here's one way to do this:
         @dots{}
         ;; @r{Handle any operation we don't know about.}
         (t (let ((inhibit-file-name-handlers
-                 (cons 'ange-ftp-file-handler 
+                 (cons 'my-file-handler 
                        (and (eq inhibit-file-name-operation operation)
                             inhibit-file-name-handlers)))
                 (inhibit-file-name-operation operation))
@@ -1909,10 +1917,12 @@ for comparison with @code{inhibit-file-name-operation}.
 @end defun
 
 @defun file-local-copy filename
-This function copies file @var{filename} to the local site, if it isn't
-there already.  If @var{filename} specifies a ``magic'' file name which
-programs outside Emacs cannot directly read or write, this copies the
-contents to an ordinary file and returns that file's name.
+This function copies file @var{filename} to an ordinary non-magic file,
+if it isn't one already.
+
+If @var{filename} specifies a ``magic'' file name, which programs
+outside Emacs cannot directly read or write, this copies the contents to
+an ordinary file and returns that file's name.
 
 If @var{filename} is an ordinary file name, not magic, then this function
 does nothing and returns @code{nil}.
@@ -1936,18 +1946,21 @@ is a good way to come up with one.
 @cindex binary files and text files
 
   Emacs on MS-DOS makes a distinction between text files and binary
-files.  This is necessary because ordinary text files on MS-DOS use two
-characters between lines: carriage-return and linefeed.  Emacs expects
-just a newline character (a linefeed) between lines.  When Emacs reads
-or writes a text file on MS-DOS, it needs to convert the line
-separators.  This means it needs to know which files are text files and
-which are binary.  It makes this decision when visiting a file, and
-records the decision in the variable @code{buffer-file-type} for when
-the file is saved.
+files.  This is necessary because ordinary text files on MS-DOS use a
+two character sequence between lines: carriage-return and linefeed
+(CRLF).  Emacs expects just a newline character (a linefeed) between
+lines.  When Emacs reads or writes a text file on MS-DOS, it needs to
+convert the line separators.  This means it needs to know which files
+are text files and which are binary.  It makes this decision when
+visiting a file, and records the decision in the variable
+@code{buffer-file-type} for use when the file is saved.
+
+  @xref{MS-DOS Subprocesses}, for a related feature for subprocesses.
 
 @defvar buffer-file-type
 This variable, automatically local in each buffer, records the file type
-of the buffer's visited file.
+of the buffer's visited file.  The value is @code{nil} for text,
+@code{t} for binary.
 @end defvar
 
 @defun find-buffer-file-type filename
diff --git a/lispref/modes.texi b/lispref/modes.texi
index 69649c4b665..953f71d0740 100644
--- a/lispref/modes.texi
+++ b/lispref/modes.texi
@@ -1311,10 +1311,10 @@ have very long file names or display the time and load.)
 (add-hook 'text-mode-hook
   (function (lambda ()
               (setq mode-line-format
+@end group
                     '(mode-line-modified
                       "Emacs: %14b"
                       "  "  
-@end group
                       default-directory
                       " "
                       global-mode-string
diff --git a/lispref/processes.texi b/lispref/processes.texi
index 4d89ed41fd1..ec0663cac83 100644
--- a/lispref/processes.texi
+++ b/lispref/processes.texi
@@ -93,7 +93,7 @@ supplied to @var{program} as separate command line arguments.  Wildcard
 characters and other shell constructs are not allowed in these strings,
 since they are passed directly to the specified program.  
 
-  @strong{Please note:} the argument @var{program} contains only the
+  @strong{Please note:} The argument @var{program} contains only the
 name of the program; it may not contain any command-line arguments.  You
 must use @var{args} to provide those.
 
diff --git a/lispref/searching.texi b/lispref/searching.texi
index f9faf1b0221..be43dc387ba 100644
--- a/lispref/searching.texi
+++ b/lispref/searching.texi
@@ -318,7 +318,7 @@ example, the regular expression that matches the @samp{\} character is
 @samp{\} is @code{"\\\\"}.@refill
 @end table
 
-@strong{Please note:} for historical compatibility, special characters
+@strong{Please note:} For historical compatibility, special characters
 are treated as ordinary ones if they are in contexts where their special
 meanings make no sense.  For example, @samp{*foo} treats @samp{*} as
 ordinary since there is no preceding expression on which the @samp{*}
diff --git a/lispref/text.texi b/lispref/text.texi
index 54ba73353ab..7d33a1c5d14 100644
--- a/lispref/text.texi
+++ b/lispref/text.texi
@@ -48,6 +48,7 @@ buffer.
 * Case Changes::     Case conversion of parts of the buffer.
 * Text Properties::  Assigning Lisp property lists to text characters.
 * Substitution::     Replacing a given character wherever it appears.
+* Transposition::    Swapping two portions of a buffer.
 * Registers::        How registers are implemented.  Accessing the text or
                        position stored in a register.
 * Change Hooks::     Supplying functions to be run when text is changed.
@@ -520,17 +521,21 @@ In the example below, point is located on the line starting
 in the preceding line.
 
 @smallexample
+@group
 ---------- Buffer: foo ----------
 When in the course of human
 @point{}    events, it becomes necessary
 ---------- Buffer: foo ----------
+@end group
 
 (delete-indentation)
      @result{} nil
 
+@group
 ---------- Buffer: foo ----------
 When in the course of human@point{} events, it becomes necessary
 ---------- Buffer: foo ----------
+@end group
 @end smallexample
 
 After the lines are joined, the function @code{fixup-whitespace} is
@@ -2615,6 +2620,25 @@ This function stores the current frame configuration in register
 @end deffn
 @end ignore
 
+@node Transposition
+@section Transposition of Text
+
+  This subroutine is used by the transposition commands.
+
+@defun transpose-regions start1 end1 start2 end2 &optional leave-markers
+This function exchanges two nonoverlapping portions of the buffer.
+Arguments @var{start1} and @var{end1} specify the bounds of one portion
+and arguments @var{start2} and @var{end2} specify the bounds of the
+other portion.
+
+Normally, @code{transpose-regions} relocates markers with the transposed
+text; a marker previously positioned within one of the two transposed
+portions moves along with that portion, thus remaining between the same
+two characters in their new position.  However, if @var{leave-markers}
+is non-@code{nil}, @code{transpose-regions} does not do this---it leaves
+all markers unrelocated.
+@end defun
+
 @node Change Hooks
 @section Change Hooks
 @cindex change hooks
@@ -2665,6 +2689,25 @@ functions.  If you do want a hook function to make changes that run
 these functions, make it bind these variables back to their usual
 values.
 
+One inconvenient result of this protective feature is that you cannot
+have a function in @code{after-change-functions} or
+@code{before-change-functions} which changes the value of that variable.
+But that's not a real limitation.  If you want those functions to change
+the list of functions to run, simply add one fixed function to the hook,
+and code that function to look in another variable for other functions
+to call.  Here is an example:
+
+@example
+(setq my-own-after-change-functions nil)
+(defun indirect-after-change-function (beg end len)
+  (let ((list my-own-after-change-functions))
+    (while list
+      (funcall (car list) beg end len)
+      (setq list (cdr list)))))
+(add-hooks 'after-change-functions
+           'indirect-after-change-function)
+@end example
+
 @defvar first-change-hook
 This variable is a normal hook that is run whenever a buffer is changed
 that was previously in the unmodified state.
diff --git a/lispref/variables.texi b/lispref/variables.texi
index ffee1a39c45..a7fbb56e590 100644
--- a/lispref/variables.texi
+++ b/lispref/variables.texi
@@ -492,7 +492,7 @@ of @var{symbol} to the result, provided @var{value} is given.  If
 @var{symbol} has a buffer-local binding in the current buffer,
 @code{defconst} sets the default value, not the local value.
 
-@strong{Please note:} don't use @code{defconst} for user option
+@strong{Please note:} Don't use @code{defconst} for user option
 variables in libraries that are not standardly preloaded.  The user
 should be able to specify a value for such a variable in the
 @file{.emacs} file, so that it will be in effect if and when the library
@@ -536,7 +536,7 @@ then the variable is a user option.
 the variable.  The property's value is used as if it were the argument
 to @code{interactive}.
 
-  @strong{Warning:} if the @code{defconst} and @code{defvar} special
+  @strong{Warning:} If the @code{defconst} and @code{defvar} special
 forms are used while the variable has a local binding, they set the
 local binding's value; the global binding is not changed.  This is not
 what we really want.  To prevent it, use these special forms at top
@@ -734,7 +734,7 @@ located textually within the function or block that binds the variable.
 
 @cindex CL note---special variables
 @quotation
-@b{Common Lisp note:} variables declared ``special'' in Common Lisp
+@b{Common Lisp note:} Variables declared ``special'' in Common Lisp
 are dynamically scoped, like variables in Emacs Lisp.
 @end quotation
 
@@ -973,7 +973,7 @@ the (default) global binding untouched.  The global value can no longer
 be changed with @code{setq}; you need to use @code{setq-default} to do
 that.
 
-  @strong{Warning:} when a variable has local values in one or more
+  @strong{Warning:} When a variable has local values in one or more
 buffers, you can get Emacs very confused by binding the variable with
 @code{let}, changing to a different current buffer in which a different
 binding is in effect, and then exiting the @code{let}.  This can
diff --git a/lispref/windows.texi b/lispref/windows.texi
index ec16940b07a..b701492defd 100644
--- a/lispref/windows.texi
+++ b/lispref/windows.texi
@@ -321,7 +321,7 @@ among all the siblings.)
 This function returns @code{nil} if @var{window} is deleted, and
 @code{t} otherwise.
 
-@strong{Warning:} erroneous information or fatal errors may result from
+@strong{Warning:} Erroneous information or fatal errors may result from
 using a deleted window as if it were live.
 @end defun