*** empty log message ***

45 files changed, 2392 insertions, 1180 deletions

diff --git a/lispref/advice.texi b/lispref/advice.texi
index ffa6606f874..3d61ae41c38 100644
--- a/lispref/advice.texi
+++ b/lispref/advice.texi
@@ -8,25 +8,96 @@
 @cindex advising functions
 
   The @dfn{advice} feature lets you add to the existing definition of a
-function, by @dfn{advising the function}.  This a clean method for a
+function, by @dfn{advising the function}.  This is a clean method for a
 library to customize functions defined by other parts of Emacs---cleaner
-than redefining the function in the usual way.
+than redefining the whole function.
 
   Each piece of advice can be enabled or disabled explicitly.  The
 enabled pieces of advice for any given function actually take effect
 when you activate advice for that function, or when that function is
 subsequently defined or redefined.
 
+  @strong{Usage Note:} Advice is useful for altering the behavior of
+existing calls to an existing function.  If you want the new behavior
+for new calls, or for key bindings, it is cleaner to define a new
+function (or a new command) which uses the existing function.
+
 @menu
-* Defining Advice::
-* Computed Advice::
-* Activation of Advice::
-* Enabling Advice::
-* Preactivation::
-* Argument Access in Advice::
-* Combined Definition::
+* Simple Advice::           A simple example to explain the basics of advice.
+* Defining Advice::         Detailed description of @code{defadvice}.
+* Computed Advice::         ...is to @code{defadvice} as @code{fset} is to @code{defun}.
+* Activation of Advice::    Advice doesn't do anything until you activate it.
+* Enabling Advice::         You can enable or disable each piece of advice.
+* Preactivation::           Preactivation is a way of speeding up the
+                              loading of compiled advice.
+* Argument Access::         How advice can access the function's arguments.
+* Subr Arguments::          Accessing arguments when advising a primitive.
+* Combined Definition::     How advice is implemented.
 @end menu
 
+@node Simple Advice
+@section A Simple Advice Example
+
+  The command @code{next-line} moves point down vertically one or more
+lines; it is the standard binding of @kbd{C-n}.  When used on the last
+line of the buffer, this command inserts a newline to create a line to
+move to (if @code{next-line-add-newlines} is non-@code{nil}).
+
+  Suppose you wanted to add a similar feature to @code{previous-line},
+which would insert a new line at the beginning of the buffer for the
+command to move to.  How could you do this?
+
+  You could do it by redefining the whole function, but that is not
+modular.  The advice feature provides a cleaner alternative: you can
+effectively add your code to the existing function definition, without
+actually changing or even seeing that definition.  Here is how to do
+this:
+
+@example
+(defadvice previous-line (before next-line-at-end (arg))
+  "Insert an empty line when moving up from the top line."
+  (if (and next-line-add-newlines (= arg 1)
+           (save-excursion (beginning-of-line) (bobp)))
+      (progn
+        (beginning-of-line)
+        (newline))))
+@end example
+
+@cindex piece of advice
+  This expression defines a @dfn{piece of advice} for the function
+@code{previous-line}.  This piece of advice is named
+@code{next-line-at-end}, and the symbol @code{before} says that it is
+@dfn{before-advice} which should run before the regular definition of
+@code{previous-line}.  @code{(arg)} specifies how the advice code can
+refer to the function's arguments.
+
+  When this piece of advice runs, it creates an additional line, in the
+situation where that is appropriate, but does not move point to that
+line.  This is the correct way to write the advice, because the normal
+definition will run afterward and will move back to the newly inserted
+line.
+
+  Defining the advice doesn't immediately change the function
+@code{previous-line}.  That happens when you @dfn{activate} the advice,
+like this:
+
+@example
+(ad-activate 'previous-line)
+@end example
+
+@noindent
+This is what actually begins to use the advice that has been defined so
+far for the function @code{previous-line}.  Henceforth, whenever that
+function is run, whether invoked by the user with @kbd{C-p} or
+@kbd{M-x}, or called from Lisp, it runs the advice first, and its
+regular definition second.
+
+  This example illustrates before-advice, which is one @dfn{class} of
+advice: it runs before the function's base definition.  There are two
+other advice classes: @dfn{after-advice}, which runs after the base
+definition, and @dfn{around-advice}, which lets you specify an
+expression to wrap around the invocation of the base definition.
+
 @node Defining Advice
 @section Defining Advice
 
@@ -50,16 +121,11 @@ form) to be advised.  From now on, we will write just ``function'' when
 describing the entity being advised, but this always includes macros and
 special forms.
 
-The argument @var{name} is the name of the advice, a non-@code{nil}
-symbol.  The advice name uniquely identifies one piece of advice, within all
-the pieces of advice in a particular class for a particular
-@var{function}.  The name allows you to refer to the piece of
-advice---to redefine it, or to enable or disable it.
-
-Where an ordinary definition has an argument list, an advice definition
-needs several kinds of information.
-
-@var{class} specifies the class of the advice---one of @code{before},
+@cindex class of advice
+@cindex before-advice
+@cindex after-advice
+@cindex around-advice
+@var{class} specifies the @dfn{class} of the advice---one of @code{before},
 @code{after}, or @code{around}.  Before-advice runs before the function
 itself; after-advice runs after the function itself; around-advice is
 wrapped around the execution of the function itself.  After-advice and
@@ -75,6 +141,15 @@ definition is never run.  This provides a way to override the original
 definition completely.  (It also overrides lower-positioned pieces of
 around-advice).
 
+The argument @var{name} is the name of the advice, a non-@code{nil}
+symbol.  The advice name uniquely identifies one piece of advice, within all
+the pieces of advice in a particular class for a particular
+@var{function}.  The name allows you to refer to the piece of
+advice---to redefine it, or to enable or disable it.
+
+In place of the argument list in an ordinary definition, an advice
+definition calls for several different pieces of information.
+
 The optional @var{position} specifies where, in the current list of
 advice of the specified @var{class}, this new advice should be placed.
 It should be either @code{first}, @code{last} or a number that
@@ -84,35 +159,49 @@ no position is specified, the default is @code{first}.  The
 advice.
 
 The optional @var{arglist} can be used to define the argument list for
-the sake of advice.  This argument list should of course be compatible
-with the argument list of the original function, otherwise functions
-that call the advised function with the original argument list in mind
-will break.  If more than one piece of advice specifies an argument
+the sake of advice.  This becomes the argument list of the combined
+definition that is generated in order to run the advice (@pxref{Combined
+Definition}).  Therefore, the advice expressions can use the argument
+variables in this list to access argument values.
+
+This argument list must be compatible with the argument list of the
+original function, so that it can handle the ways the function is
+actually called.  If more than one piece of advice specifies an argument
 list, then the first one (the one with the smallest position) found in
-the list of all classes of advice will be used.
+the list of all classes of advice is used.  Numbers outside the range
+are mapped to the beginning or the end, whichever is closer.
 
-@var{flags} is a list of symbols that specify further information about
-how to use this piece of advice.  Here are the valid symbols and their
-meanings:
+The remaining elements, @var{flags}, is a list of symbols that specify
+further information about how to use this piece of advice.  Here are the
+valid symbols and their meanings:
 
 @table @code
 @item activate
-Activate all the advice for @var{function} after making this definition.
-This is ignored when @var{function} itself is not defined yet (which is
-known as @dfn{forward advice}).
+Activate the advice for @var{function} now.  Changes in a function's
+advice always take effect the next time you activate advice for the
+function; this flag says to do so, for @var{function}, immediately after
+defining this piece of advice.
+
+@cindex forward advice
+This flag has no effect if @var{function} itself is not defined yet (a
+situation known as @dfn{forward advice}), because it is impossible to
+activate an undefined function's advice.  However, defining
+@var{function} will automatically activate its advice.
 
 @item protect
 Protect this piece of advice against non-local exits and errors in
-preceding code and advice.
+preceding code and advice.  Protecting advice makes it a cleanup in an
+@code{unwind-protect} form, so that it will execute even if the
+previous code gets an error or uses @code{throw}.  @xref{Cleanups}.
 
 @item compile
-Says that the combined definition which implements advice should be
-byte-compiled.  This flag is ignored unless @code{activate} is also
-specified.
+Compile the combined definition that is used to run the advice.  This
+flag is ignored unless @code{activate} is also specified.
+@xref{Combined Definition}.
 
 @item disable
-Disable this piece of advice, so that it will not be used
-unless subsequently explicitly enabled.
+Initially disable this piece of advice, so that it will not be used
+unless subsequently explicitly enabled.  @xref{Enabling Advice}.
 
 @item preactivate
 Activate advice for @var{function} when this @code{defadvice} is
@@ -124,10 +213,10 @@ This is useful only if this @code{defadvice} is byte-compiled.
 @end table
 
 The optional @var{documentation-string} serves to document this piece of
-advice.  If the @code{documentation} function gets the documentation
-for @var{function} when its advice is active, the result will combine
-the documentation strings of all the advice with that of the original
-function.
+advice.  When advice is active for @var{function}, the documentation for
+@var{function} (as returned by @code{documentation}) combines the
+documentation strings of all the advice for @var{function} with the
+documentation string of its original function definition.
 
 The optional @var{interactive-form} form can be supplied to change the
 interactive behavior of the original function.  If more than one piece
@@ -162,7 +251,9 @@ this form:
 @end example
 
 Here @var{protected} and @var{enabled} are flags, and @var{definition}
-is an expression that says what the advice should do.
+is the expression that says what the advice should do.  If @var{enabled}
+is @code{nil}, this piece of advice is initially disabled
+(@pxref{Enabling Advice}).
 
 If @var{function} already has one or more pieces of advice in the
 specified @var{class}, then @var{position} specifies where in the list
@@ -194,11 +285,12 @@ redefining the function over and over as each advice is added.  More
 importantly, it permits defining advice for a function before that
 function is actually defined.
 
-When a function is first activated, its original definition is saved,
-and all enabled pieces of advice for that function are combined with the
-original definition to make a new definition.  This definition is
-installed, and optionally byte-compiled as well, depending on conditions
-described below.
+When a function's advice is first activated, the function's original
+definition is saved, and all enabled pieces of advice for that function
+are combined with the original definition to make a new definition.
+(Pieces of advice that are currently disabled are not used; see
+@ref{Enabling Advice}.)  This definition is installed, and optionally
+byte-compiled as well, depending on conditions described below.
 
 In all of the commands to activate advice, if @var{compile} is @code{t},
 the command also compiles the combined definition which implements the
@@ -208,9 +300,9 @@ advice.
 This command activates the advice for @var{function}.
 @end deffn
 
-To activate a function whose advice is already active is not a no-op.
-It is a useful operation which puts into effect any changes in advice
-since the previous activation of the same function.
+To activate advice for a function whose advice is already active is not
+a no-op.  It is a useful operation which puts into effect any changes in
+advice since the previous activation of that function's advice.
 
 @deffn Command ad-deactivate function
 This command deactivates the advice for @var{function}.
@@ -239,15 +331,21 @@ function which has at least one piece of advice that matches
 
 @deffn Command ad-update-regexp regexp &optional compile
 This command activates pieces of advice whose names match @var{regexp},
-but only those that are already activated.
-@end deffn
+but only those for functions whose advice is already activated.
 
-@deffn Command ad-stop-advice
-Turn off automatic advice activation when a function is defined or
-redefined.
+Reactivating a function's advice is useful for putting into effect all
+the changes that have been made in its advice (including enabling and
+disabling specific pieces of advice; @pxref{Enabling Advice}) since the
+last time it was activated.
 @end deffn
 
 @deffn Command ad-start-advice
+Turn on automatic advice activation when a function is defined or
+redefined.  If you turn on this mode, then advice really does
+take effect immediately when defined.
+@end deffn
+
+@deffn Command ad-stop-advice
 Turn off automatic advice activation when a function is defined or
 redefined.
 @end deffn
@@ -275,8 +373,8 @@ the function @code{foo}:
 (ad-disable-advice 'foo 'before 'my-advice)
 @end example
 
-  This call by itself only changes the enable flag for this piece of
-advice.  To make this change take effect in the advised definition, you
+This function by itself only changes the enable flag for a piece of
+advice.  To make the change take effect in the advised definition, you
 must activate the advice for @code{foo} again:
 
 @example
@@ -293,8 +391,10 @@ This command enables the piece of advice named @var{name} in class
 @var{class} on @var{function}.
 @end deffn
 
-  You can also disable many pieces of advice at once using a regular
-expression.
+  You can also disable many pieces of advice at once, for various
+functions, using a regular expression.  As always, the changes take real
+effect only when you next reactivate advice for the functions in
+question.
 
 @deffn Command ad-disable-regexp regexp
 This command disables all pieces of advice whose names match
@@ -322,12 +422,12 @@ same function, and the function's own definition.  If the
 @code{defadvice} is compiled, that compiles the combined definition
 also.
 
-  When the function is subsequently activated, if the enabled advice for
-the function matches what was used to make this combined
-definition. then the existing combined definition is used, and there is
-no need to construct one.  Thus, preactivation never causes wrong
+  When the function's advice is subsequently activated, if the enabled
+advice for the function matches what was used to make this combined
+definition, then the existing combined definition is used, thus avoiding
+the need to construct one.  Thus, preactivation never causes wrong
 results---but it may fail to do any good, if the enabled advice at the
-time of activation doesn't match.
+time of activation doesn't match what was used for preactivation.
 
   Here are some symptoms that can indicate that a preactivation did not
 work properly, because of a mismatch.
@@ -351,8 +451,8 @@ when you @emph{compile} the preactivated advice.
 There is no elegant way to find out why preactivated advice is not being
 used.  What you can do is to trace the function
 @code{ad-cache-id-verification-code} (with the function
-@code{trace-function-background}) before the advised function is
-activated.  After activation, check the value returned by
+@code{trace-function-background}) before the advised function's advice
+is activated.  After activation, check the value returned by
 @code{ad-cache-id-verification-code} for that function: @code{verified}
 means that the preactivated advice was used, while other values give
 some information about why they were considered inappropriate.
@@ -376,6 +476,13 @@ disadvantage: it is not robust, because it hard-codes the argument names
 into the advice.  If the definition of the original function changes,
 the advice might break.
 
+  Another method is to specify an argument list in the advice itself.
+This avoids the need to know the original function definition's argument
+names, but it has a limitation: all the advice on any particular
+function must use the same argument list, because the argument list
+actually used for all the advice comes from the first piece of advice
+for that function.
+
   A more robust method is to use macros that are translated into the
 proper access forms at activation time, i.e., when constructing the
 advised definition.  Access macros access actual arguments by position
@@ -456,7 +563,8 @@ will be 3, and @var{r} will be @code{(2 1 0)} inside the body of
   These argument constructs are not really implemented as Lisp macros.
 Instead they are implemented specially by the advice mechanism.
 
-@subsection Definition of Subr Argument Lists
+@node Subr Arguments
+@section Definition of Subr Argument Lists
 
   When the advice facility constructs the combined definition, it needs
 to know the argument list of the original function.  This is not always
diff --git a/lispref/anti.texi b/lispref/anti.texi
index df81194f29d..d93e99cf962 100644
--- a/lispref/anti.texi
+++ b/lispref/anti.texi
@@ -7,7 +7,7 @@
 
 For those users who live backwards in time, here is information about
 downgrading to Emacs version 19.34.  We hope you will enjoy the greater
-simplicity that results from the absence of many Emacs 19 features.  In
+simplicity that results from the absence of many Emacs 20 features.  In
 the following section, we carry this information back as far as Emacs
 19.29, for which the previous printed edition of this manual was made.
 
@@ -29,9 +29,10 @@ Within this range, there are no invalid character codes.
 @item
 The Custom facility has been replaced with a much simpler and more
 general method of defining user option variables.  Instead of
-@code{defcustom}, which requires you to specify each user option's
-data type and classify them into groups, all you have to do is write
-a @code{defvar} and start the documentation string with @samp{*}.
+@code{defcustom}, which requires you to specify each user option's data
+type and classify options into groups, all you have to do is write a
+@code{defvar}.  You should still start the documentation string with
+@samp{*}, though.
 @end itemize
 
 Here are changes in the Lisp language itself:
@@ -138,7 +139,7 @@ directory name from the beginning of the file name---just like
 We have got rid of the function @code{access-file}.
 
 @item
-Most of the minibuffer input functions, no longer take a default value as
+Most of the minibuffer input functions no longer take a default value as
 an argument.  Also, they do not discard text properties from the result.
 This means that if you insert text with text properties into the minibuffer,
 the minibuffer value really will contain text properties.
diff --git a/lispref/backups.texi b/lispref/backups.texi
index 9707ade9eef..3cdd88d5c08 100644
--- a/lispref/backups.texi
+++ b/lispref/backups.texi
@@ -289,7 +289,8 @@ This function returns a string that is the name to use for a
 non-numbered backup file for file @var{filename}.  On Unix, this is just
 @var{filename} with a tilde appended.
 
-The standard definition of this function is as follows:
+The standard definition of this function, on most operating systems, is
+as follows:
 
 @smallexample
 @group
@@ -306,7 +307,9 @@ to prepend a @samp{.} in addition to appending a tilde:
 @smallexample
 @group
 (defun make-backup-file-name (filename)
-  (concat "." filename "~"))
+  (expand-file-name
+    (concat "." (file-name-nondirectory filename) "~")
+    (file-name-directory filename)))
 @end group
 
 @group
@@ -314,6 +317,11 @@ to prepend a @samp{.} in addition to appending a tilde:
      @result{} ".backups.texi~"
 @end group
 @end smallexample
+
+Some parts of Emacs, including some Dired commands, assume that backup
+file names end with @samp{~}.  If you do not follow that convention, it
+will not cause serious problems, but these commands may give
+less-than-desirable results.
 @end defun
 
 @defun find-backup-file-name filename
diff --git a/lispref/buffers.texi b/lispref/buffers.texi
index 600ff3e54b5..c54f1e6b9b0 100644
--- a/lispref/buffers.texi
+++ b/lispref/buffers.texi
@@ -47,9 +47,9 @@ not be displayed in any windows.
 
   Buffers in Emacs editing are objects that have distinct names and hold
 text that can be edited.  Buffers appear to Lisp programs as a special
-data type.  You can think of the contents of a buffer as an extendable
-string; insertions and deletions may occur in any part of the buffer.
-@xref{Text}.
+data type.  You can think of the contents of a buffer as a string that
+you can extend; insertions and deletions may occur in any part of the
+buffer.  @xref{Text}.
 
   A Lisp buffer object contains numerous pieces of information.  Some of
 this information is directly accessible to the programmer through
@@ -112,7 +112,7 @@ the subroutine does not change which buffer is current (unless, of
 course, that is the subroutine's purpose).  Therefore, you should
 normally use @code{set-buffer} within a @code{save-current-buffer} or
 @code{save-excursion} (@pxref{Excursions}) form that will restore the
-current buffer when your function is done .  Here is an example, the
+current buffer when your function is done.  Here is an example, the
 code for the command @code{append-to-buffer} (with the documentation
 string abridged):
 
@@ -201,8 +201,8 @@ An error is signaled if @var{buffer-or-name} does not identify an
 existing buffer.
 @end defun
 
+@defspec save-current-buffer body...
 @tindex save-current-buffer
-@defmac save-current-buffer body...
 The @code{save-current-buffer} macro saves the identity of the current
 buffer, evaluates the @var{body} forms, and finally restores that buffer
 as current.  The return value is the value of the last form in
@@ -215,8 +215,8 @@ of course.  Instead, whichever buffer was current just before exit
 remains current.
 @end defmac
 
-@tindex with-current-buffer
 @defmac with-current-buffer buffer body...
+@tindex with-current-buffer
 The @code{with-current-buffer} macro saves the identity of the current
 buffer, makes @var{buffer} current, evaluates the @var{body} forms, and
 finally restores the buffer.  The return value is the value of the last
@@ -224,8 +224,8 @@ form in @var{body}.  The current buffer is restored even in case of an
 abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}).
 @end defmac
 
-@tindex with-temp-buffer
 @defmac with-temp-buffer body...
+@tindex with-temp-buffer
 The @code{with-temp-buffer} macro evaluates the @var{body} forms
 with a temporary buffer as the current buffer.  It saves the identity of
 the current buffer, creates a temporary buffer and makes it current,
diff --git a/lispref/commands.texi b/lispref/commands.texi
index 29e43d4dfc7..49c9d3c16e3 100644
--- a/lispref/commands.texi
+++ b/lispref/commands.texi
@@ -332,6 +332,10 @@ Prompt.
 @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
@@ -408,6 +412,16 @@ Minibuffer}.  Prompt.
 @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
@@ -758,8 +772,15 @@ are characters or symbols; mouse events are always lists.  This section
 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
@@ -1314,6 +1335,36 @@ want 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
@@ -1559,7 +1610,7 @@ by not storing keyboard events in strings.  Here is how to do that:
 @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}.
@@ -1776,8 +1827,8 @@ this Emacs session.  This includes key sequences read from the terminal
 and key sequences read from keyboard macros being executed.
 @end defvar
 
-@tindex num-nonmacro-input-events
 @defvar num-nonmacro-input-events
+@tindex 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.
 @end defvar
@@ -1803,6 +1854,12 @@ 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 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:
 
@@ -2506,9 +2563,10 @@ the command to be considered complex.
 @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
diff --git a/lispref/compile.texi b/lispref/compile.texi
index 007a4a6b094..001466d500d 100644
--- a/lispref/compile.texi
+++ b/lispref/compile.texi
@@ -3,7 +3,7 @@
 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. 
 @c See the file elisp.texi for copying conditions.
 @setfilename ../info/compile
-@node Byte Compilation, Advising, Loading, Top
+@node Byte Compilation, Advising Functions, Loading, Top
 @chapter Byte Compilation
 @cindex byte-code
 @cindex compilation
@@ -20,6 +20,12 @@ hardware (as true compiled code is), byte-code is completely
 transportable from machine to machine without recompilation.  It is not,
 however, as fast as true compiled code.
 
+  Compiling a Lisp file with the Emacs byte compiler always reads the
+file as multibyte text, even if Emacs was started with @samp{--unibyte},
+unless the file specifies otherwise.  This is so that compilation gives
+results compatible with running the same file without compilation.
+@xref{Loading Non-ASCII}.
+
   In general, any version of Emacs can run byte-compiled code produced
 by recent earlier versions of Emacs, but the reverse is not true.  A
 major incompatible change was introduced in Emacs version 19.29, and
@@ -164,9 +170,10 @@ function.
 @end deffn
 
 @deffn Command byte-compile-file filename
-This function compiles a file of Lisp code named @var{filename} into
-a file of byte-code.  The output file's name is made by appending
-@samp{c} to the end of @var{filename}.
+This function compiles a file of Lisp code named @var{filename} into a
+file of byte-code.  The output file's name is made by changing the
+@samp{.el} suffix into @samp{.elc}; if @var{filename} does not end in
+@samp{.el}, it adds @samp{.elc} to the end of @var{filename}.
 
 Compilation works by reading the input file one form at a time.  If it
 is a definition of a function or macro, the compiled function or macro
diff --git a/lispref/control.texi b/lispref/control.texi
index 1fbb668da0f..a824e79f6f2 100644
--- a/lispref/control.texi
+++ b/lispref/control.texi
@@ -172,8 +172,8 @@ never evaluated---it is ignored.  Thus, in the example below,
 @end example
 @end defspec
 
-@tindex when
 @defmac when condition then-forms@dots{}
+@tindex when
 This is a variant of @code{if} where there are no @var{else-forms},
 and possibly several @var{then-forms}.  In particular,
 
@@ -189,8 +189,8 @@ is entirely equivalent to
 @end example
 @end defmac
 
-@tindex condition
 @defmac unless condition forms@dots{}
+@tindex condition
 This is a variant of @code{if} where there is no @var{then-form}:
 
 @example
@@ -550,10 +550,10 @@ have several ways of transferring control nonsequentially: @code{return},
 
 @defspec catch tag body@dots{}
 @cindex tag on run time stack
-@code{catch} establishes a return point for the @code{throw} function.  The
-return point is distinguished from other such return points by @var{tag},
-which may be any Lisp object.  The argument @var{tag} is evaluated normally
-before the return point is established.
+@code{catch} establishes a return point for the @code{throw} function.
+The return point is distinguished from other such return points by
+@var{tag}, which may be any Lisp object except @code{nil}.  The argument
+@var{tag} is evaluated normally before the return point is established.
 
 With the return point in effect, @code{catch} evaluates the forms of the
 @var{body} in textual order.  If the forms execute normally, without
diff --git a/lispref/customize.texi b/lispref/customize.texi
index 2b61848d643..dffd3de49a3 100644
--- a/lispref/customize.texi
+++ b/lispref/customize.texi
@@ -31,6 +31,10 @@ The keyword @code{:tag} is an exception because any given item can only
 display one name.
 
 @table @code
+@item :tag @var{name}
+Use @var{name}, a string, instead of the item's name, to label the item
+in customization menus and buffers.
+
 @item :group @var{group}
 Put this customization item in group @var{group}.  When you use
 @code{:group} in a @code{defgroup}, it makes the new group a subgroup of
@@ -48,10 +52,6 @@ other documentation.
 There are three alternatives you can use for @var{link-data}:
 
 @table @code
-@item :tag @var{name}
-Use @var{name}, a string, instead of the item's name, to label the item
-in customization menus and buffers.
-
 @item (custom-manual @var{info-node})
 Link to an Info node; @var{info-node} is a string which specifies the
 node name, as in @code{"(emacs)Top"}.  The link appears as
@@ -109,23 +109,22 @@ keyword.
 
   The way to declare new customization groups is with @code{defgroup}.
 
-@tindex defgroup
 @defmac defgroup group members doc [keyword value]...
+@tindex defgroup
 Declare @var{group} as a customization group containing @var{members}.
 Do not quote the symbol @var{group}.  The argument @var{doc} specifies
 the documentation string for the group.
 
-The arguments @var{members} can be an alist whose elements specify
-customization items to be members of the group; however, normally
+The argument @var{members} is a list specifying an initial set of
+customization items to be members of the group.  However, most often
 @var{members} is @code{nil}, and you specify the group's members by
 using the @code{:group} keyword when defining those members.
 
-@ignore
-@code{(@var{name} @var{widget})}.  Here @var{name} is a symbol, and
-@var{widget} is a widget for editing that symbol.  Useful widgets are
-@code{custom-variable} for editing variables, @code{custom-face} for
-editing faces, and @code{custom-group} for editing groups.
-@end ignore
+If you want to specify group members through @var{members}, each element
+should have the form @code{(@var{name} @var{widget})}.  Here @var{name}
+is a symbol, and @var{widget} is a widget type for editing that symbol.
+Useful widgets are @code{custom-variable} for a variable,
+@code{custom-face} for a face, and @code{custom-group} for a group.
 
 In addition to the common keywords (@pxref{Common Keywords}), you can
 use this keyword in @code{defgroup}:
@@ -162,18 +161,18 @@ turn this feature back on, if someone would like to do the work.
 
   Use @code{defcustom} to declare user-editable variables.
 
-@tindex defcustom
 @defmac defcustom option default doc [keyword value]...
+@tindex defcustom
 Declare @var{option} as a customizable user option variable.  Do not
 quote @var{option}.  The argument @var{doc} specifies the documentation
 string for the variable.
 
 If @var{option} is void, @code{defcustom} initializes it to
 @var{default}.  @var{default} should be an expression to compute the
-value; be careful in writing it, because it can be be evaluated on more
+value; be careful in writing it, because it can be evaluated on more
 than one occasion.
 
-The following additional keywords are defined:
+The following additional keywords are accepted:
 
 @table @code
 @item :type @var{type}
@@ -191,8 +190,9 @@ elements of the hook value.  The user is not restricted to using only
 these functions, but they are offered as convenient alternatives.
 
 @item :version @var{version}
-This option specifies that the variable's default value was changed in
-Emacs version @var{version}.  For example,
+This option specifies that the variable was first introduced, or its
+default value was changed, in Emacs version @var{version}.  The value
+@var{version} must be a string.  For example,
 
 @example
 (defcustom foo-max 34
@@ -260,7 +260,7 @@ Keywords}.  Here is an example, from the library @file{paren.el}:
 (defcustom show-paren-mode nil
   "Toggle Show Paren mode@enddots{}"
   :set (lambda (symbol value)
-	 (show-paren-mode (or value 0)))
+         (show-paren-mode (or value 0)))
   :initialize 'custom-initialize-default
   :type 'boolean
   :group 'paren-showing
@@ -369,6 +369,13 @@ completion with @kbd{M-@key{TAB}}.
 The value must be a directory name, and you can do completion with
 @kbd{M-@key{TAB}}.
 
+@item hook
+The value must be a list of functions (or a single function, but that is
+obsolete usage).  This customization type is used for hook variables.
+You can use the @code{:option} in the @code{defcustom} for a hook
+variable to specify functions recommended for use in the hook;
+see @ref{Variable Definitions}.
+
 @item symbol
 The value must be a symbol.  It appears in the customization buffer as
 the name of the symbol.
@@ -381,6 +388,10 @@ it is a function name, you can do completion with @kbd{M-@key{TAB}}.
 The value must be a variable name, and you can do completion with
 @kbd{M-@key{TAB}}.
 
+@item face
+The value must be a symbol which is a face name, and you can do
+completion with @kbd{M-@key{TAB}}.
+
 @item boolean
 The value is boolean---either @code{nil} or @code{t}.  Note that by
 using @code{choice} and @code{const} together (see the next section),
@@ -399,24 +410,26 @@ doing that:
 @table @code
 @item (restricted-sexp :match-alternatives @var{criteria})
 The value may be any Lisp object that satisfies one of @var{criteria}.
-@var{criteria} should be a list, and each elements should be
+@var{criteria} should be a list, and each element should be
 one of these possibilities:
 
 @itemize @bullet
 @item
-A predicate---that is, a function of one argument that returns non-@code{nil}
-if the argument fits a certain type.  This means that objects of that type
-are acceptable.
+A predicate---that is, a function of one argument that has no side
+effects, and returns either @code{nil} or non-@code{nil} according to
+the argument.  Using a predicate in the list says that objects for which
+the predicate returns non-@code{nil} are acceptable.
 
 @item
-A quoted constant---that is, @code{'@var{object}}.  This means that
-@var{object} itself is an acceptable value.
+A quoted constant---that is, @code{'@var{object}}.  This sort of element
+in the list says that @var{object} itself is an acceptable value.
 @end itemize
 
 For example,
 
 @example
-(restricted-sexp :match-alternatives (integerp 't 'nil))
+(restricted-sexp :match-alternatives
+                 (integerp 't 'nil))
 @end example
 
 @noindent
@@ -427,7 +440,7 @@ syntax, and the user edits them textually.
 
 @item (cons @var{car-type} @var{cdr-type})
 The value must be a cons cell, its @sc{car} must fit @var{car-type}, and
-its @sc{cdr} must fit @var{cdr-type}.  For example, @code{(const string
+its @sc{cdr} must fit @var{cdr-type}.  For example, @code{(cons string
 symbol)} is a customization type which matches values such as
 @code{("foo" . foo)}.
 
@@ -444,7 +457,7 @@ For example, @code{(list integer string function)} describes a list of
 three elements; the first element must be an integer, the second a
 string, and the third a function.
 
-In the customization buffer, the each element is displayed and edited
+In the customization buffer, each element is displayed and edited
 separately, according to the type specified for it.
 
 @item (vector @var{element-types}@dots{})
@@ -466,10 +479,10 @@ including the @code{:tag} keyword in the alternatives.  For example, if
 an integer stands for a number of spaces, while a string is text to use
 verbatim, you might write the customization type this way,
 
-@smallexample
+@example
 (choice (integer :tag "Number of spaces")
         (string :tag "Literal text"))
-@end smallexample
+@end example
 
 @noindent
 so that the menu offers @samp{Number of spaces} and @samp{Literal Text}.
@@ -488,11 +501,11 @@ The main use of @code{const} is inside of @code{choice}.  For example,
 @code{:tag} is often used with @code{const}, inside of @code{choice}.
 For example,
 
-@smallexample
+@example
 (choice (const :tag "Yes" t)
         (const :tag "No" nil)
         (const :tag "Ask" foo))
-@end smallexample
+@end example
 
 @item (function-item @var{function})
 Like @code{const}, but used for values which are functions.  This
@@ -733,7 +746,7 @@ in the buffer with a positive tabbing order, or @code{nil}
 @end enumerate
 
 @item :parent
-The parent of a nested widget (e.g. a @code{menu-choice} item or an
+The parent of a nested widget (e.g., a @code{menu-choice} item or an
 element of a @code{editable-list} widget).
 
 @item :sibling-args
diff --git a/lispref/debugging.texi b/lispref/debugging.texi
index 9c7a4fd7be7..8e5ed2834a5 100644
--- a/lispref/debugging.texi
+++ b/lispref/debugging.texi
@@ -3,7 +3,7 @@
 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998 Free Software Foundation, Inc. 
 @c See the file elisp.texi for copying conditions.
 @setfilename ../info/debugging
-@node Debugging, Read and Print, Advising, Top
+@node Debugging, Read and Print, Advising Functions, Top
 @chapter Debugging Lisp Programs
 
   There are three ways to investigate a problem in an Emacs Lisp program,
@@ -12,8 +12,9 @@ depending on what you are doing with the program when the problem appears.
 @itemize @bullet
 @item
 If the problem occurs when you run the program, you can use a Lisp
-debugger (either the default debugger or Edebug) to investigate what is
-happening during execution.
+debugger to investigate what is happening during execution.  In addition
+to the ordinary debugger, Emacs comes with a source level debugger,
+Edebug.  This chapter describes both of them.
 
 @item
 If the problem is syntactic, so that Lisp cannot even read the program,
@@ -26,9 +27,9 @@ compiler, you need to know how to examine the compiler's input buffer.
 
 @menu
 * Debugger::            How the Emacs Lisp debugger is implemented.
+* Edebug::		A source-level Emacs Lisp debugger.
 * Syntax Errors::       How to find syntax errors.
 * Compilation Errors::  How to find errors that show up in byte compilation.
-* Edebug::		A source-level Emacs Lisp debugger.
 @end menu
 
   Another useful debugging tool is the dribble file.  When a dribble
@@ -45,13 +46,13 @@ Afterward, you can examine the file to find out what input was used.
 @cindex Lisp debugger
 @cindex break
 
-  The @dfn{Lisp debugger} provides the ability to suspend evaluation of
-a form.  While evaluation is suspended (a state that is commonly known
-as a @dfn{break}), you may examine the run time stack, examine the
-values of local or global variables, or change those values.  Since a
-break is a recursive edit, all the usual editing facilities of Emacs are
-available; you can even run programs that will enter the debugger
-recursively.  @xref{Recursive Editing}.
+  The ordinary @dfn{Lisp debugger} provides the ability to suspend
+evaluation of a form.  While evaluation is suspended (a state that is
+commonly known as a @dfn{break}), you may examine the run time stack,
+examine the values of local or global variables, or change those values.
+Since a break is a recursive edit, all the usual editing facilities of
+Emacs are available; you can even run programs that will enter the
+debugger recursively.  @xref{Recursive Editing}.
 
 @menu
 * Error Debugging::       Entering the debugger when an error happens.
@@ -74,25 +75,28 @@ happens.  This allows you to investigate the immediate causes of the
 error.
 
   However, entry to the debugger is not a normal consequence of an
-error.  Many commands frequently get Lisp errors when invoked in
-inappropriate contexts (such as @kbd{C-f} at the end of the buffer) and
-during ordinary editing it would be very unpleasant to enter the
-debugger each time this happens.  If you want errors to enter the
-debugger, set the variable @code{debug-on-error} to non-@code{nil}.
+error.  Many commands frequently cause Lisp errors when invoked
+inappropriately (such as @kbd{C-f} at the end of the buffer), and during
+ordinary editing it would be very inconvenient to enter the debugger
+each time this happens.  So if you want errors to enter the debugger, set
+the variable @code{debug-on-error} to non-@code{nil}.  (The command
+@code{toggle-debug-on-error} provides an easy way to do this.)
 
 @defopt debug-on-error
 This variable determines whether the debugger is called when an error is
 signaled and not handled.  If @code{debug-on-error} is @code{t}, all
-errors call the debugger.  If it is @code{nil}, none call the debugger.
+kinds of errors call the debugger (except those listed in
+@code{debug-ignored-errors}).  If it is @code{nil}, none call the
+debugger.
 
 The value can also be a list of error conditions that should call the
 debugger.  For example, if you set it to the list
 @code{(void-variable)}, then only errors about a variable that has no
 value invoke the debugger.
 
-When this variable is non-@code{nil}, Emacs does not catch errors that
-happen in process filter functions and sentinels.  Therefore, these
-errors also can invoke the debugger.  @xref{Processes}.
+When this variable is non-@code{nil}, Emacs does not create an error
+handler around process filter functions and sentinels.  Therefore,
+errors in these functions also invoke the debugger.  @xref{Processes}.
 @end defopt
 
 @defopt debug-ignored-errors
@@ -117,10 +121,10 @@ debugger, even if @code{debug-on-error} is non-@code{nil}.  In other
 words, @code{condition-case} gets a chance to handle the error before
 the debugger gets a chance.
 
-If you set @code{debug-on-signal} non-@code{nil}, then the debugger gets
-first chance at every error; an error will invoke the debugger
-regardless of any @code{condition-case}, if the fits the criterion
-specified by the values of @code{debug-on-error} and
+If you set @code{debug-on-signal} to a non-@code{nil} value, then the
+debugger gets the first chance at every error; an error will invoke the
+debugger regardless of any @code{condition-case}, if it fits the
+criterion specified by the values of @code{debug-on-error} and
 @code{debug-ignored-errors}.
 
 @strong{Warning:} This variable is strong medicine!  Various parts of
@@ -134,13 +138,14 @@ enter the debugger.
 @end defopt
 
   To debug an error that happens during loading of the @file{.emacs}
-file, use the option @samp{-debug-init}, which binds
-@code{debug-on-error} to @code{t} while @file{.emacs} is loaded and
-inhibits use of @code{condition-case} to catch init-file errors.
+file, use the option @samp{--debug-init}, which binds
+@code{debug-on-error} to @code{t} while @file{.emacs} is loaded, and
+bypasses the @code{condition-case} which normally catches errors in the
+init-file.
 
   If your @file{.emacs} file sets @code{debug-on-error}, the effect may
 not last past the end of loading @file{.emacs}.  (This is an undesirable
-byproduct of the code that implements the @samp{-debug-init} command
+byproduct of the code that implements the @samp{--debug-init} command
 line option.)  The best way to make @file{.emacs} set
 @code{debug-on-error} permanently is with @code{after-init-hook}, like
 this:
@@ -269,8 +274,9 @@ not currently set up to break on entry.  It always returns
   You can cause the debugger to be called at a certain point in your
 program by writing the expression @code{(debug)} at that point.  To do
 this, visit the source file, insert the text @samp{(debug)} at the
-proper place, and type @kbd{C-M-x}.  Be sure to undo this insertion
-before you save the file!
+proper place, and type @kbd{C-M-x}.  @strong{Warning:} if you do this
+for temporary debugging purposes, be sure to undo this insertion before
+you save the file!
 
   The place where you insert @samp{(debug)} must be a place where an
 additional form can be evaluated and its value ignored.  (If the value
@@ -339,8 +345,8 @@ same function.  (To do this, visit the source for the function and type
 @item c
 Exit the debugger and continue execution.  When continuing is possible,
 it resumes execution of the program as if the debugger had never been
-entered (aside from the effect of any variables or data structures you
-may have changed while inside the debugger).
+entered (aside from any side-effects that you caused by changing
+variable values or data structures while inside the debugger).
 
 Continuing is possible after entry to the debugger due to function entry
 or exit, explicit invocation, or quitting.  You cannot continue if the
@@ -371,10 +377,10 @@ remove the star from the line in the backtrace buffer.
 Read a Lisp expression in the minibuffer, evaluate it, and print the
 value in the echo area.  The debugger alters certain important
 variables, and the current buffer, as part of its operation; @kbd{e}
-temporarily restores their outside-the-debugger values so you can
-examine them.  This makes the debugger more transparent.  By contrast,
-@kbd{M-:} does nothing special in the debugger; it shows you the
-variable values within the debugger.
+temporarily restores their values from outside the debugger, so you can
+examine and change them.  This makes the debugger more transparent.  By
+contrast, @kbd{M-:} does nothing special in the debugger; it shows you
+the variable values within the debugger.
 
 @item R
 Like @kbd{e}, but also save the result of evaluation in the
@@ -404,7 +410,8 @@ You can't use @kbd{r} when the debugger was entered due to an error.
 @node Invoking the Debugger
 @subsection Invoking the Debugger
 
-  Here we describe fully the function used to invoke the debugger.
+  Here we describe in full detail the function @code{debug} that is used
+to invoke the debugger.
 
 @defun debug &rest debugger-args
 This function enters the debugger.  It switches buffers to a buffer
@@ -418,18 +425,15 @@ then @code{debug} switches back to the previous buffer and returns to
 whatever called @code{debug}.  This is the only way the function
 @code{debug} can return to its caller.
 
-If the first of the @var{debugger-args} passed to @code{debug} is
-@code{nil} (or if it is not one of the special values in the table
-below), then @code{debug} displays the rest of its arguments at the
-top of the @samp{*Backtrace*} buffer.  This mechanism is used to display
-a message to the user.
-
-However, if the first argument passed to @code{debug} is one of the
-following special values, then it has special significance.  Normally,
-these values are passed to @code{debug} only by the internals of Emacs
-and the debugger, and not by programmers calling @code{debug}.
+The use of the @var{debugger-args} is that @code{debug} displays the
+rest of its arguments at the top of the @samp{*Backtrace*} buffer, so
+that the user can see them.  Except as described below, this is the
+@emph{only} way these arguments are used.
 
-The special values are:
+However, certain values for first argument to @code{debug} have a
+special significance.  (Normally, these values are used only by the
+internals of Emacs, and not by programmers calling @code{debug}.)  Here
+is a table of these special values:
 
 @table @code
 @item lambda
@@ -640,6 +644,8 @@ If @var{frame-number} is out of range, @code{backtrace-frame} returns
 @code{nil}.
 @end defun
 
+@include edebug.texi
+
 @node Syntax Errors
 @section Debugging Invalid Lisp Syntax
 
@@ -658,7 +664,9 @@ if it goes to the place where that defun appears to end.  If it does
 not, there is a problem in that defun.
 
   However, unmatched parentheses are the most common syntax errors in
-Lisp, and we can give further advice for those cases.
+Lisp, and we can give further advice for those cases.  (In addition,
+just moving point through the code with Show Paren mode enabled might
+find the mismatch.)
 
 @menu
 * Excess Open::     How to find a spurious open paren or missing close.
@@ -753,5 +761,3 @@ the error.
 successfully, then point is located at the end of the form.  In this
 case, this technique can't localize the error precisely, but can still
 show you which function to check.
-
-@include edebug.texi
diff --git a/lispref/display.texi b/lispref/display.texi
index 59782034ca6..4b09a8b3372 100644
--- a/lispref/display.texi
+++ b/lispref/display.texi
@@ -167,6 +167,9 @@ If it is non-@code{nil}, these lines are truncated; otherwise,
 @code{truncate-lines} says what to do with them.
 @end defopt
 
+  When horizontal scrolling (@pxref{Horizontal Scrolling}) is in use in
+a window, that forces truncation.
+
   You can override the glyphs that indicate continuation or truncation
 using the display table; see @ref{Display Tables}.
 
@@ -236,8 +239,8 @@ Minibuffer depth is 0.
 @end example
 @end defun
 
-@tindex current-message
 @defun current-message
+@tindex current-message
 This function returns the message currently being displayed in the
 echo area, or @code{nil} if there is none.
 @end defun
@@ -252,8 +255,8 @@ The value is normally @code{nil}; Lisp programs bind it to @code{t}
 for brief periods of time.
 @end defvar
 
-@tindex echo-area-clear-hook
 @defvar echo-area-clear-hook
+@tindex echo-area-clear-hook
 This normal hook is run whenever the echo area is cleared---either by
 @code{(message nil)} or for any other reason.
 @end defvar
@@ -278,8 +281,9 @@ This variable determines how much time should elapse before command
 characters echo.  Its value must be an integer, which specifies the
 number of seconds to wait before echoing.  If the user types a prefix
 key (such as @kbd{C-x}) and then delays this many seconds before
-continuing, the prefix key is echoed in the echo area.  Any subsequent
-characters in the same command will be echoed as well.
+continuing, the prefix key is echoed in the echo area.  (Once echoing
+begins in a key sequence, all subsequent characters in the same key
+sequence are echoed immediately.)
 
 If the value is zero, then command input is not echoed.
 @end defvar
@@ -290,7 +294,8 @@ If the value is zero, then command input is not echoed.
 @cindex invisible text
 You can make characters @dfn{invisible}, so that they do not appear on
 the screen, with the @code{invisible} property.  This can be either a
-text property or a property of an overlay.
+text property (@pxref{Text Properties}) or a property of an overlay
+(@pxref{Overlays}).
 
 In the simplest case, any non-@code{nil} @code{invisible} property makes
 a character invisible.  This is the default case---if you don't alter
@@ -342,14 +347,14 @@ by a visible newline, it displays an ellipsis.
   Two functions are specifically provided for adding elements to
 @code{buffer-invisibility-spec} and removing elements from it.
 
-@tindex add-to-invisibility-spec
 @defun add-to-invisibility-spec element
+@tindex add-to-invisibility-spec
 Add the element @var{element} to @code{buffer-invisibility-spec}
 (if it is not already present in that list).
 @end defun
 
-@tindex remove-from-invisibility-spec
 @defun remove-from-invisibility-spec element
+@tindex remove-from-invisibility-spec
 Remove the element @var{element} from @code{buffer-invisibility-spec}.
 @end defun
 
@@ -393,8 +398,8 @@ temporarily modifying their invisible and intangible properties.  If you
 want this to be done differently for a certain overlays, give it a
 @code{isearch-open-invisible-temporary} property which is a function.
 The function is called with two arguments: the first is the overlay, and
-the second is @code{nil} to make the overlay visible or @code{t} to make
-it invisible again.
+the second is @code{t} to make the overlay visible, or @code{nil} to
+make it invisible again.
 
 @node Selective Display
 @section Selective Display
@@ -598,6 +603,17 @@ The value of the last form in @var{forms} is returned.
 If this variable is non-@code{nil}, @code{with-output-to-temp-buffer}
 calls it as a function to do the job of displaying a help buffer.  The
 function gets one argument, which is the buffer it should display.
+
+It is a good idea for this function to run @code{temp-buffer-show-hook}
+just as @code{with-output-to-temp-buffer} normally would, inside of
+@code{save-window-excursion} and with the chosen window and buffer
+selected.
+@end defvar
+
+@defvar temp-buffer-show-hook
+This normal hook is run by @code{with-output-to-temp-buffer} after
+displaying the help buffer.  When the hook runs, the help buffer is
+current, and the window it was displayed in is selected.
 @end defvar
 
 @defun momentary-string-display string position &optional char message
@@ -675,15 +691,16 @@ these affect the display of the text within the overlay.
 @node Overlay Properties
 @subsection Overlay Properties
 
-Overlay properties are like text properties in some respects, but the
-differences are more important than the similarities.  Text properties
-are considered a part of the text; overlays are specifically considered
-not to be part of the text.  Thus, copying text between various buffers
-and strings preserves text properties, but does not try to preserve
-overlays.  Changing a buffer's text properties marks the buffer as
-modified, while moving an overlay or changing its properties does not.
-Unlike text property changes, overlay changes are not recorded in the
-buffer's undo list.
+Overlay properties are like text properties in that the properties that
+alter how a character is displayed can come from either source.  But in
+most respects they are different.  Text properties are considered a part
+of the text; overlays are specifically considered not to be part of the
+text.  Thus, copying text between various buffers and strings preserves
+text properties, but does not try to preserve overlays.  Changing a
+buffer's text properties marks the buffer as modified, while moving an
+overlay or changing its properties does not.  Unlike text property
+changes, overlay changes are not recorded in the buffer's undo list.
+@xref{Text Properties}, for comparison.
 
 @table @code
 @item priority
@@ -773,11 +790,14 @@ The @code{intangible} property on an overlay works just like the
 @code{intangible} text property.  @xref{Special Properties}, for details.
 
 @item isearch-open-invisible
-@itemx isearch-open-invisible-temporary
-These properties control how incremental search should make invisible an
-overlay visible, either permanently or temporarily.  @xref{Invisible
+This property tells incremental search how to make an invisible overlay
+visible, permanently, if the final match overlaps it.  @xref{Invisible
 Text}.
 
+@item isearch-open-invisible-temporary
+This property tells incremental search how to make an invisible overlay
+visible, temporarily, during the search.  @xref{Invisible Text}.
+
 @item before-string
 @kindex before-string @r{(overlay property)}
 This property's value is a string to add to the display at the beginning
@@ -861,8 +881,11 @@ This function returns the buffer that @var{overlay} belongs to.
 
 @defun delete-overlay overlay
 This function deletes @var{overlay}.  The overlay continues to exist as
-a Lisp object, but ceases to be part of the buffer it belonged to, and
-ceases to have any effect on display.
+a Lisp object, but ceases to be attached to the buffer it belonged to,
+and ceases to have any effect on display.
+
+A deleted overlay is not permanently useless.  You can give it
+a new buffer position by calling @code{move-overlay}.
 @end defun
 
 @defun move-overlay overlay start end &optional buffer
@@ -886,8 +909,8 @@ An overlay contains position @var{pos} if it begins at or before
 @var{pos}, and ends after @var{pos}.
 @end defun
 
-@tindex overlays-in
 @defun overlays-in beg end
+@tindex overlays-in
 This function returns a list of the overlays that overlap the region
 @var{beg} through @var{end}.  ``Overlap'' means that at least one
 character is contained within the overlay and also contained within the
@@ -912,20 +935,20 @@ Since not all characters have the same width, these functions let you
 check the width of a character.  @xref{Primitive Indent}, and
 @ref{Screen Lines}, for related functions.
 
-@tindex char-width
 @defun char-width char
+@tindex char-width
 This function returns the width in columns of the character @var{char},
 if it were displayed in the current buffer and the selected window.
 @end defun
 
-@tindex string-width
 @defun string-width string
+@tindex string-width
 This function returns the width in columns of the string @var{string},
 if it were displayed in the current buffer and the selected window.
 @end defun
 
-@tindex truncate-string-to-width
 @defun truncate-string-to-width string width &optional start-column padding
+@tindex truncate-string-to-width
 This function returns the part of @var{string} that fits within
 @var{width} columns, as a new string.
 
@@ -1033,22 +1056,22 @@ one.
 @end table
 
 @node Defining Faces
-@section Defining Faces
+@subsection Defining Faces
 
   The way to define a new face is with @code{defface}.  This creates a
 kind of customization item (@pxref{Customization}) which the user can
 customize using the Customization buffer (@pxref{Easy Customization,,,
 emacs, The GNU Emacs Manual}).
 
-@tindex defface
 @defmac defface face spec doc [keyword value]... 
+@tindex defface
 Declare @var{face} as a customizable face that defaults according to
 @var{spec}.  Do not quote the symbol @var{face}.  The argument @var{doc}
 specifies the face documentation.
 
 When @code{defface} executes, it defines the face according to
-@var{spec}, then uses any customizations saved in the @file{.emacs} file
-to override that specification.
+@var{spec}, then uses any customizations that were read from the
+@file{.emacs} file to override that specification.
 
 The purpose of @var{spec} is to specify how the face should appear on
 different kinds of terminals.  It should be an alist whose elements have
@@ -1069,7 +1092,7 @@ This element of @var{spec} matches all frames.  Therefore, any
 subsequent elements of @var{spec} are never used.  Normally
 @code{t} is used in the last (or only) element of @var{spec}.
 
-@item an list
+@item a list
 If @var{display} is alist, each elements should have the form
 @code{(@var{characteristic} @var{value}@dots{})}.  Here
 @var{characteristic} specifies a way of classifying frames, and the
@@ -1222,19 +1245,20 @@ they are used automatically to handle certain shades of gray.
 
 @defun set-face-font face font &optional frame
 This function sets the font of face @var{face}.  The argument @var{font}
-should be a string.  Note that if you set the font explicitly, the bold
-and italic attributes cease to have any effect, because the precise font
-that you specified is always used.
+should be a string, either a valid font name for your system or the name
+of an Emacs fontset (@pxref{Fontsets}).  Note that if you set the font
+explicitly, the bold and italic attributes cease to have any effect,
+because the precise font that you specified is always used.
 @end defun
 
-@tindex set-face-bold-p
 @defun set-face-bold-p face bold-p &optional frame
+@tindex set-face-bold-p
 This function sets the bold attribute of face @var{face}.
 Non-@code{nil} means bold; @code{nil} means non-bold.
 @end defun
 
-@tindex set-face-italic-p
 @defun set-face-italic-p face italic-p &optional frame
+@tindex set-face-italic-p
 This function sets the italic attribute of face @var{face}.
 Non-@code{nil} means italic; @code{nil} means non-italic.
 @end defun
@@ -1269,13 +1293,13 @@ This function returns the name of the background stipple pattern of face
 This function returns the name of the font of face @var{face}.
 @end defun
 
-@tindex face-bold-p
 @defun face-bold-p face &optional frame
+@tindex face-bold-p
 This function returns the bold attribute of face @var{face}.
 @end defun
 
-@tindex face-italic-p
 @defun face-italic-p face &optional frame
+@tindex face-italic-p
 This function returns the italic attribute of face @var{face}.
 @end defun
 
@@ -1287,8 +1311,8 @@ This function returns the underline attribute of face @var{face}.
 This function returns the face number of face @var{face}.
 @end defun
 
-@tindex face-documentation
 @defun face-documentation face
+@tindex face-documentation
 This function returns the documentation string of face @var{face}, or
 @code{nil} if none was specified for it.
 @end defun
@@ -1428,7 +1452,7 @@ just like the codes in the range 128 to 255.
 @item
 Character codes 128 through 255 map to sequences of four glyphs, where
 the first glyph is the @sc{ASCII} code for @samp{\}, and the others are
-digit characters representing the charatcer code in octal.  (A display
+digit characters representing the character code in octal.  (A display
 table can specify a glyph to use instead of @samp{\}.)
 
 @item
@@ -1497,7 +1521,8 @@ force redisplay of the mode line using a new display table, call
 @node Display Table Format
 @subsection Display Table Format
 
-  A display table is actually char-table with subtype @code{display-table}.
+  A display table is actually a char-table (@pxref{Char-Tables}) with
+@code{display-table} as its subtype.
 
 @defun make-display-table
 This creates and returns a display table.  The table initially has
@@ -1550,8 +1575,8 @@ effect of setting @code{ctl-arrow} to a non-@code{nil} value:
   (aset disptab 127 (vector ?^ ??)))
 @end example
 
-@tindex display-table-slot
 @defun display-table-slot display-table slot
+@tindex display-table-slot
 This function returns the value of the extra slot @var{slot} of
 @var{display-table}.  The argument @var{slot} may be a number from 0 to
 5 inclusive, or a slot name (symbol).  Valid symbols are
@@ -1559,8 +1584,8 @@ This function returns the value of the extra slot @var{slot} of
 @code{selective-display}, and @code{vertical-border}.
 @end defun
 
-@tindex set-display-table-slot
 @defun set-display-table-slot display-table slot value
+@tindex set-display-table-slot
 This function stores @var{value} in the extra slot @var{slot} of
 @var{display-table}.  The argument @var{slot} may be a number from 0 to
 5 inclusive, or a slot name (symbol).  Valid symbols are
@@ -1669,14 +1694,14 @@ often you do this; frequent bells can become irritating.  Also be
 careful not to use just beeping when signaling an error is more
 appropriate.  (@xref{Errors}.)
 
-@defun ding &optional dont-terminate
+@defun ding &optional do-not-terminate
 @cindex keyboard macro termination
 This function beeps, or flashes the screen (see @code{visible-bell} below).
 It also terminates any keyboard macro currently executing unless
-@var{dont-terminate} is non-@code{nil}.
+@var{do-not-terminate} is non-@code{nil}.
 @end defun
 
-@defun beep &optional dont-terminate
+@defun beep &optional do-not-terminate
 This is a synonym for @code{ding}.
 @end defun
 
@@ -1688,10 +1713,10 @@ provided the terminal's Termcap entry defines the visible bell
 capability (@samp{vb}).
 @end defvar
 
-@tindex ring-bell-function
 @defvar ring-bell-function
+@tindex ring-bell-function
 If this is non-@code{nil}, it specifies how Emacs should ``ring the
-bell.''  Its value should bea function of no arguments.
+bell.''  Its value should be a function of no arguments.
 @end defvar
 
 @node Window Systems
@@ -1714,7 +1739,7 @@ terminal).
 This variable is a normal hook which Emacs runs after handling the
 initialization files.  Emacs runs this hook after it has completed
 loading your @file{.emacs} file, the default initialization file (if
-any), and the terminal-specific Lisp code, and runring the hook
+any), and the terminal-specific Lisp code, and running the hook
 @code{term-setup-hook}.
 
 This hook is used for internal purposes: setting up communication with
diff --git a/lispref/edebug.texi b/lispref/edebug.texi
index d8459d2bcea..c93330e38ae 100644
--- a/lispref/edebug.texi
+++ b/lispref/edebug.texi
@@ -36,7 +36,7 @@ Display expression results and evaluate expressions as if outside of
 Edebug.
 
 @item 
-Automatically reevaluate a list of expressions and
+Automatically re-evaluate a list of expressions and
 display their results each time Edebug updates the display.
 
 @item
@@ -199,11 +199,11 @@ steps into the call after instrumenting the function.
 @cindex Common Lisp (Edebug)
 @pindex cl.el @r{(Edebug)}
 @pindex cl-specs.el
-  Edebug knows how to instrument all the standard special forms, an
-interactive form with an expression argument, anonymous lambda
+  Edebug knows how to instrument all the standard special forms,
+@code{interactive} forms with an expression argument, anonymous lambda
 expressions, and other defining forms.  Edebug cannot know what a
 user-defined macro will do with the arguments of a macro call, so you
-must tell it; @xref{Instrumenting Macro Calls}, for details.
+must tell it; see @ref{Instrumenting Macro Calls}, for details.
 
   When Edebug is about to instrument code for the first time in a
 session, it runs the hook @code{edebug-setup-hook}, then sets it to
@@ -212,7 +212,7 @@ session, it runs the hook @code{edebug-setup-hook}, then sets it to
 using, but actually load them only if you use Edebug.
 
 @findex eval-expression @r{(Edebug)}
-  To remove instrumentation from a definition, simply reevaluate its
+  To remove instrumentation from a definition, simply re-evaluate its
 definition in a way that does not instrument.  There are two ways of
 evaluating forms that never instrument them: from a file with
 @code{load}, and from the minibuffer with @code{eval-expression}
@@ -335,8 +335,8 @@ Step into the function or macro called by the form after point.
 @end table
 
 The @kbd{h} command proceeds to the stop point near the current location
-if point, using a temporary breakpoint.  See @ref{Breakpoints}, for more
-about breakpoints.
+of point, using a temporary breakpoint.  See @ref{Breakpoints}, for more
+information about breakpoints.
 
 The @kbd{f} command runs the program forward over one expression.  More
 precisely, it sets a temporary breakpoint at the position that
@@ -463,7 +463,7 @@ with @kbd{u}.  First move point to the Edebug stop point of your choice,
 then type @kbd{b} or @kbd{u} to set or unset a breakpoint there.
 Unsetting a breakpoint where none has been set has no effect.
 
-Reevaluating or reinstrumenting a definition forgets all its breakpoints.
+Re-evaluating or reinstrumenting a definition forgets all its breakpoints.
 
 A @dfn{conditional breakpoint} tests a condition each time the program
 gets there.  Any errors that occur as a result of evaluating the
@@ -568,7 +568,7 @@ are bound to the values they had outside of Edebug.
 @subsection Edebug Views
 
   These Edebug commands let you view aspects of the buffer and window
-status that obtained before entry to Edebug.  The outside window
+status as they were before entry to Edebug.  The outside window
 configuration is the collection of windows and contents that were in
 effect outside of Edebug.
 
@@ -745,7 +745,6 @@ After selecting @samp{*edebug*}, you can return to the source code
 buffer with @kbd{C-c C-w}.  The @samp{*edebug*} buffer is killed when
 you continue execution, and recreated next time it is needed.
 
-
 @node Printing in Edebug
 @subsection Printing in Edebug
 
@@ -765,7 +764,6 @@ and @code{edebug-print-level} specify the values to use within Edebug.)
 @defopt edebug-print-length
 If non-@code{nil}, bind @code{print-length} to this while printing
 results in Edebug.  The default value is @code{50}.
-@xref{Printing in Edebug}.
 @end defopt
 
 @defopt edebug-print-level 
@@ -785,13 +783,13 @@ edebug-uninstall-custom-print}.
 
 @example
 (setq a '(x y))
-(setcar a a))
+(setcar a a)
 @end example
 
 @noindent
 Custom printing prints this as @samp{Result: #1=(#1# y)}.  The
 @samp{#1=} notation labels the structure that follows it with the label
-@samp{1}, and the @samp{#1#} notation references the previously labelled
+@samp{1}, and the @samp{#1#} notation references the previously labeled
 structure.  This notation is used for any shared elements of lists or
 vectors.
 
@@ -857,12 +855,19 @@ last lines inserted.
 @cindex frequency counts
 @cindex performance analysis
 Edebug provides rudimentary coverage testing and display of execution
-frequency.  All execution of an instrumented function accumulates
-frequency counts, both before and after evaluation of each instrumented
-expression, even if the execution mode is Go-nonstop.  Coverage testing
-is more expensive, so it is done only if @code{edebug-test-coverage} is
-non-@code{nil}.  The command @kbd{M-x edebug-display-freq-count}
-displays both the frequency data and the coverage data (if recorded).
+frequency.  Coverage testing works by comparing the result of each
+expression with the previous result; coverage is considered OK if two
+different results are found.  Thus, to sufficiently test the coverage of
+your code, try to execute it under conditions that evaluate all
+expressions more than once, and produce different results for each
+expression.  Coverage testing makes execution slower, so it is only done
+if @code{edebug-test-coverage} is non-@code{nil}.  Whether or not
+coverage testing is enabled, frequency counting is performed for all
+execution of an instrumented function, even if the execution mode is
+Go-nonstop.
+
+Use @kbd{M-x edebug-display-freq-count} to display both the
+coverage information and the frequency counts for a definition.
 
 @deffn Command edebug-display-freq-count
 This command displays the frequency count data for each line of the
@@ -871,15 +876,16 @@ current definition.
 The frequency counts appear as comment lines after each line of code,
 and you can undo all insertions with one @code{undo} command.  The
 counts appear under the @samp{(} before an expression or the @samp{)}
-after an expression, or on the last character of a symbol.  Values do
-not appear if they are equal to the previous count on the same line.
+after an expression, or on the last character of a variable.  To
+simplify the display, a count is not shown if it is equal to the
+count of an earlier expression on the same line.
 
 The character @samp{=} following the count for an expression says that
-the expression has returned the same value each time it was evaluated
+the expression has returned the same value each time it was evaluated.
 This is the only coverage information that Edebug records.
 
 To clear the frequency count and coverage data for a definition,
-reinstrument it.
+simply reinstrument it with @code{eval-defun}.
 @end deffn
 
 For example, after evaluating @code{(fac 5)} with a source
@@ -930,8 +936,8 @@ program.
 @itemize @bullet
 @item 
 @code{max-lisp-eval-depth} and @code{max-specpdl-size} are both
-incremented one time to reduce Edebug's impact on the stack.
-You could, however, still run out of stack space when using Edebug.
+incremented once to reduce Edebug's impact on the stack.  You could,
+however, still run out of stack space when using Edebug.
 
 @item 
 The state of keyboard macro execution is saved and restored.  While
@@ -1067,8 +1073,8 @@ name.
 @end deffn
 
 Here is a simple example that defines the specification for the
-@code{for} macro described in the Emacs Lisp Reference Manual, followed
-by an alternative, equivalent specification.
+@code{for} example macro (@code{Argument Evaluation}), followed by an
+alternative, equivalent specification.
 
 @example
 (def-edebug-spec for
@@ -1091,7 +1097,7 @@ None of the arguments is instrumented.
 @item a symbol
 The symbol must have an Edebug specification which is used instead.
 This indirection is repeated until another kind of specification is
-found.  This allows you to inherit the specification for another macro.
+found.  This allows you to inherit the specification from another macro.
 
 @item a list
 The elements of the list describe the types of the arguments of a
@@ -1137,9 +1143,8 @@ their meanings:
 
 @table @code
 @item sexp
-A single Lisp object, not unevaluated.
-@c "unevaluated expression" is not meaningful, because
-@c an expression is a Lisp object intended for evaluation.
+A single unevaluated expression, which is not instrumented.
+@c an "expression" is not necessarily intended for evaluation.
 
 @item form
 A single evaluated expression, which is instrumented.
@@ -1202,7 +1207,7 @@ succeeds.
 @item &define 
 @kindex &define @r{(Edebug)}
 Indicates that the specification is for a defining form.  The defining
-form itself is not instrumented (i.e. Edebug does not stop before and
+form itself is not instrumented (that is, Edebug does not stop before and
 after the defining form), but forms inside it typically will be
 instrumented.  The @code{&define} keyword should be the first element in
 a list specification.
@@ -1260,7 +1265,7 @@ a list whose elements match the specification @var{elements}.
 A sublist specification may be a dotted list and the corresponding list
 argument may then be a dotted list.  Alternatively, the last @sc{cdr} of a
 dotted list specification may be another sublist specification (via a
-grouping or an indirect specification, e.g. @code{(spec .  [(more
+grouping or an indirect specification, e.g., @code{(spec .  [(more
 specs@dots{})])}) whose elements match the non-dotted list arguments.
 This is useful in recursive specifications such as in the backquote
 example below.  Also see the description of a @code{nil} specification
@@ -1293,7 +1298,7 @@ than once.
 
 @item arg
 The argument, a symbol, is the name of an argument of the defining form.
-However, lambda list keywords (symbols starting with @samp{@code{&}})
+However, lambda-list keywords (symbols starting with @samp{&})
 are not allowed.
 
 @item lambda-list
@@ -1326,33 +1331,35 @@ necessarily mean a syntax error will be signaled; instead,
 exhausted.  Eventually every element of the argument list must be
 matched by some element in the specification, and every required element
 in the specification must match some argument.
-
-Backtracking is disabled for the remainder of a sublist or group when
-certain conditions occur, described below.  Backtracking is reenabled
-when a new alternative is established by @code{&optional}, @code{&rest},
-or @code{&or}.  It is also reenabled initially when processing a
-sublist or group specification or an indirect specification.
-
-You might want to disable backtracking to commit to some alternative so
-that Edebug can provide a more specific syntax error message.  Normally,
-if no alternative matches, Edebug reports that none matched, but if one
-alternative is committed to, Edebug can report how it failed to match.
-
-First, backtracking is disabled while matching any of the form
-specifications (i.e. @code{form}, @code{body}, @code{def-form}, and
+  
+When a syntax error is detected, it might not be reported until much
+later after higher-level alternatives have been exhausted, and with the
+point positioned further from the real error.  But if backtracking is
+disabled when an error occurs, it can be reported immediately.  Note
+that backtracking is also reenabled automatically in several situations;
+it is reenabled when a new alternative is established by
+@code{&optional}, @code{&rest}, or @code{&or}, or at the start of
+processing a sublist, group, or indirect specification.  The effect of
+enabling or disabling backtracking is limited to the remainder of the
+level currently being processed and lower levels.
+
+Backtracking is disabled while matching any of the
+form specifications (that is, @code{form}, @code{body}, @code{def-form}, and
 @code{def-body}).  These specifications will match any form so any error
 must be in the form itself rather than at a higher level.
 
-Second, backtracking is disabled after successfully matching a quoted
+Backtracking is also disabled after successfully matching a quoted
 symbol or string specification, since this usually indicates a
-recognized construct.  If you have a set of alternative constructs that
+recognized construct.  But if you have a set of alternative constructs that
 all begin with the same symbol, you can usually work around this
 constraint by factoring the symbol out of the alternatives, e.g.,
 @code{["foo" &or [first case] [second case] ...]}.
 
-Third, backtracking may be explicitly disabled by using the
-@code{gate} specification.  This is useful when you know that
-no higher alternatives may apply.
+Most needs are satisfied by these two ways that bactracking is
+automatically disabled, but occasionally it is useful to explicitly
+disable backtracking by using the @code{gate} specification.  This is
+useful when you know that no higher alternatives could apply.  See the
+example of the @code{let} specification.
 
 @node Specification Examples
 @subsubsection Specification Examples
@@ -1362,7 +1369,7 @@ the examples provided here.
 
 A @code{let} special form has a sequence of bindings and a body.  Each
 of the bindings is either a symbol or a sublist with a symbol and
-optional value.  In the specification below, notice the @code{gate}
+optional expression.  In the specification below, notice the @code{gate}
 inside of the sublist to prevent backtracking once a sublist is found.
 
 @example
@@ -1491,19 +1498,11 @@ function entry or exit per line, indented by the recursion level.
 
 The default value is @code{nil}.  
 
-Also see @code{edebug-tracing}, in @xref{Trace Buffer}.
+Also see @code{edebug-tracing}, in @ref{Trace Buffer}.
 @end defopt
 
 @defopt edebug-test-coverage 
 If non-@code{nil}, Edebug tests coverage of all expressions debugged.
-This is done by comparing the result of each expression
-with the previous result. Coverage is considered OK if two different
-results are found.  So to sufficiently test the coverage of your code,
-try to execute it under conditions that evaluate all expressions more
-than once, and produce different results for each expression.
-
-Use @kbd{M-x edebug-display-freq-count} to display the frequency count
-and coverage information for a definition.
 @xref{Coverage Testing}.
 @end defopt
 
diff --git a/lispref/elisp.texi b/lispref/elisp.texi
index 6005cff535e..7dbc8093346 100644
--- a/lispref/elisp.texi
+++ b/lispref/elisp.texi
@@ -4,6 +4,8 @@
 @settitle GNU Emacs Lisp Reference Manual
 @c %**end of header
 
+@smallbook
+
 @ifinfo
 This version is the edition 2.5 of the GNU Emacs Lisp
 Reference Manual.  It corresponds to Emacs Version 20.3
@@ -269,7 +271,7 @@ Editing Types
 * Process Type::            A process running on the underlying OS.
 * Stream Type::             Receive or send characters.
 * Keymap Type::             What function a keystroke invokes.
-* Syntax Table Type::       What a character means.
+* Overlay Type::        How an overlay is represented.
 
 Numbers
 
@@ -291,7 +293,7 @@ Strings and Characters
 * Text Comparison::         Comparing characters or strings.
 * String Conversion::       Converting characters or strings and vice versa.
 * Formatting Strings::      @code{format}: Emacs's analog of @code{printf}.
-* Character Case::          Case conversion functions.
+* Case Conversion::         Case conversion functions.
 
 Lists
 
@@ -443,6 +445,19 @@ Byte Compilation
 * Compilation Functions::   Byte compilation functions.
 * Disassembly::             Disassembling byte-code; how to read byte-code.
 
+Advising Functions
+
+* Simple Advice::           A simple example to explain the basics of advice.
+* Defining Advice::         Detailed description of @code{defadvice}.
+* Computed Advice::         ...is to @code{defadvice} as @code{fset} is to @code{defun}.
+* Activation of Advice::    Advice doesn't do anything until you activate it.
+* Enabling Advice::         You can enable or disable each piece of advice.
+* Preactivation::           Preactivation is a way of speeding up the
+                              loading of compiled advice.
+* Argument Access::         How advice can access the function's arguments.
+* Subr Arguments::          Accessing arguments when advising a primitive.
+* Combined Definition::     How advice is implemented.
+
 Debugging Lisp Programs
 
 * Debugger::                How the Emacs Lisp debugger is implemented.
@@ -684,7 +699,7 @@ Frames
 * Pop-Up Menus::	    Displaying a menu for the user to select from.
 * Dialog Boxes::            Displaying a box to ask yes or no.
 * Pointer Shapes::          Specifying the shape of the mouse pointer.
-* X Selections::	    Transferring text to and from other X clients.
+* Window System Selections::Transferring text to and from other X clients.
 * Color Names::	            Getting the definitions of color names.
 * Resources::		    Getting resource values from the server.
 * Server Data::		    Getting info about the X server.
@@ -951,7 +966,7 @@ Object Internals
 @include index.texi
 
 @node New Symbols, , Index, Top
-@chapter New Symbols Since the Previous Edition
+@unnumbered New Symbols Since the Previous Edition
 
 @printindex tp
 
diff --git a/lispref/errors.texi b/lispref/errors.texi
index 809db995ed0..823eadddeac 100644
--- a/lispref/errors.texi
+++ b/lispref/errors.texi
@@ -104,7 +104,7 @@ This is a @code{file-error}.@*
 @xref{Regular Expressions}.
 
 @item mark-inactive
-@code{Mark inactive"}@*
+@code{"Mark inactive"}@*
 @xref{The Mark}.
 
 @item no-catch
diff --git a/lispref/eval.texi b/lispref/eval.texi
index 512e6d927b2..d49aba1cc16 100644
--- a/lispref/eval.texi
+++ b/lispref/eval.texi
@@ -464,6 +464,9 @@ Emacs Lisp with a reference to where each is described.
 @item quote
 @pxref{Quoting}
 
+@item save-current-buffer
+@pxref{Current Buffer}
+
 @item save-excursion
 @pxref{Excursions}
 
@@ -657,8 +660,10 @@ The depth limit counts internal uses of @code{eval}, @code{apply}, and
 expressions, and recursive evaluation of function call arguments and
 function body forms, as well as explicit calls in Lisp code.
 
-The default value of this variable is 200.  If you set it to a value
+The default value of this variable is 300.  If you set it to a value
 less than 100, Lisp will reset it to 100 if the given value is reached.
+Entry to the Lisp debugger increases the value, if there is little room
+left, to make sure the debugger itself has room to execute.
 
 @code{max-specpdl-size} provides another limit on nesting.
 @xref{Local Variables}.
diff --git a/lispref/files.texi b/lispref/files.texi
index 45f8097fecd..940ac549210 100644
--- a/lispref/files.texi
+++ b/lispref/files.texi
@@ -15,7 +15,7 @@ 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
+expand file name arguments by calling @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}.
@@ -201,9 +201,9 @@ used, and in many cases only some of the functions are called.
 @comment  node-name,  next,  previous,  up
 @subsection Subroutines of Visiting
 
-  The @code{find-file-noselect} function uses the
-@code{create-file-buffer} and @code{after-find-file} functions as
-subroutines.  Sometimes it is useful to call them directly.
+  The @code{find-file-noselect} function uses two important subroutines
+which are sometimes useful in user Lisp code: @code{create-file-buffer}
+and @code{after-find-file}.  This section explains how to use them.
 
 @defun create-file-buffer filename
 This function creates a suitably named buffer for visiting
@@ -251,7 +251,7 @@ If @var{warn} is non-@code{nil}, then this function issues a warning
 if an auto-save file exists and is more recent than the visited file.
 
 The last thing @code{after-find-file} does is call all the functions
-in @code{find-file-hooks}.
+in the list @code{find-file-hooks}.
 @end defun
 
 @node Saving Buffers
@@ -334,6 +334,12 @@ You might wish to save the file modes value returned by
 @code{backup-buffer} and use that to set the mode bits of the file that
 you write.  This is what @code{save-buffer} normally does.
 
+The hook functions in @code{write-file-hooks} are also responsible for
+encoding the data (if desired): they must choose a suitable coding
+system (@pxref{Lisp and Coding Systems}), perform the encoding
+(@pxref{Explicit Encoding}), and set @code{last-coding-system-used} to
+the coding system that was used (@pxref{Specifying Coding Systems}).
+
 Do not make this variable buffer-local.  To set up buffer-specific hook
 functions, use @code{write-contents-hooks} instead.
 
@@ -448,12 +454,13 @@ contents of the file.  This is better than simply deleting the buffer
 contents and inserting the whole file, because (1) it preserves some
 marker positions and (2) it puts less data in the undo list.
 
-It works to read a special file with @code{insert-file-contents}
-as long as @var{replace} and @var{visit} are @code{nil}.
+It is possible to read a special file (such as a FIFO or an I/O device)
+with @code{insert-file-contents}, as long as @var{replace} and
+@var{visit} are @code{nil}.
 @end defun
 
-@tindex insert-file-contents-literally
 @defun insert-file-contents-literally filename &optional visit beg end replace
+@tindex insert-file-contents-literally
 This function works like @code{insert-file-contents} except that it does
 not do format decoding (@pxref{Format Conversion}), does not do
 character code conversion (@pxref{Coding Systems}), does not run
@@ -485,7 +492,7 @@ An error is signaled if @var{filename} specifies a nonwritable file,
 or a nonexistent file in a directory where files cannot be created.
 @end deffn
 
-@deffn Command write-region start end filename &optional append visit
+@deffn Command write-region start end filename &optional append visit confirm
 This function writes the region delimited by @var{start} and @var{end}
 in the current buffer into the file specified by @var{filename}.
 
@@ -496,6 +503,9 @@ that string, rather than text from the buffer.
 If @var{append} is non-@code{nil}, then the specified text is appended
 to the existing file contents (if any).
 
+If @var{confirm} is non-@code{nil}, then @code{write-region} asks
+for confirmation if @var{filename} names an existing file.
+
 If @var{visit} is @code{t}, then Emacs establishes an association
 between the buffer and the file: the buffer is then visiting that file.
 It also sets the last file modification time for the current buffer to
@@ -524,8 +534,8 @@ feature is useful for programs that use files for internal purposes,
 files that the user does not need to know about.
 @end deffn
 
-@tindex with-temp-file
 @defmac with-temp-file file body...
+@tindex with-temp-file
 The @code{with-temp-file} macro evaluates the @var{body} forms with a
 temporary buffer as the current buffer; then, at the end, it writes the
 buffer contents into file @var{file}.  It kills the temporary buffer
@@ -732,8 +742,8 @@ we can deduce that any attempt to read a file in @file{/foo/} will
 give an error.
 @end defun
 
-@tindex access-file
 @defun access-file filename string
+@tindex access-file
 This function opens file @var{filename} for reading, then closes it and
 returns @code{nil}.  However, if the open fails, it signals an error
 using @var{string} as the error message text.
@@ -1103,9 +1113,9 @@ In the first part of the following example, we list two files,
 
 @example
 @group
-% ls -l fo*
--rw-rw-rw-  1 rms       29 Aug 18 20:32 foo
--rw-rw-rw-  1 rms       24 Aug 18 20:31 foo3
+% ls -li fo*
+81908 -rw-rw-rw-  1 rms       29 Aug 18 20:32 foo
+84302 -rw-rw-rw-  1 rms       24 Aug 18 20:31 foo3
 @end group
 @end example
 
@@ -1115,23 +1125,22 @@ the files again.  This shows two names for one file, @file{foo} and
 
 @example
 @group
-(add-name-to-file "~/lewis/foo" "~/lewis/foo2")
+(add-name-to-file "foo" "foo2")
      @result{} nil
 @end group
 
 @group
-% ls -l fo*
--rw-rw-rw-  2 rms       29 Aug 18 20:32 foo
--rw-rw-rw-  2 rms       29 Aug 18 20:32 foo2
--rw-rw-rw-  1 rms       24 Aug 18 20:31 foo3
+% ls -li fo*
+81908 -rw-rw-rw-  2 rms       29 Aug 18 20:32 foo
+81908 -rw-rw-rw-  2 rms       29 Aug 18 20:32 foo2
+84302 -rw-rw-rw-  1 rms       24 Aug 18 20:31 foo3
 @end group
 @end example
 
-@c !!! Check whether this set of examples is consistent.  --rjc 15mar92
-  Finally, we evaluate the following:
+Finally, we evaluate the following:
 
 @example
-(add-name-to-file "~/lewis/foo" "~/lewis/foo3" t)
+(add-name-to-file "foo" "foo3" t)
 @end example
 
 @noindent
@@ -1141,22 +1150,22 @@ contents of @file{foo3} are lost.
 
 @example
 @group
-(add-name-to-file "~/lewis/foo1" "~/lewis/foo3")
+(add-name-to-file "foo1" "foo3")
      @result{} nil
 @end group
 
 @group
-% ls -l fo*
--rw-rw-rw-  3 rms       29 Aug 18 20:32 foo
--rw-rw-rw-  3 rms       29 Aug 18 20:32 foo2
--rw-rw-rw-  3 rms       29 Aug 18 20:32 foo3
+% ls -li fo*
+81908 -rw-rw-rw-  3 rms       29 Aug 18 20:32 foo
+81908 -rw-rw-rw-  3 rms       29 Aug 18 20:32 foo2
+81908 -rw-rw-rw-  3 rms       29 Aug 18 20:32 foo3
 @end group
 @end example
 
-  This function is meaningless on VMS, where multiple names for one file
-are not allowed.
+This function is meaningless on operating systems where multiple names
+for one file are not allowed.
 
-  See also @code{file-nlinks} in @ref{File Attributes}.
+See also @code{file-nlinks} in @ref{File Attributes}.
 @end defun
 
 @deffn Command rename-file filename newname &optional ok-if-already-exists
@@ -1176,7 +1185,7 @@ In an interactive call, this function prompts for @var{filename} and
 This command copies the file @var{oldname} to @var{newname}.  An
 error is signaled if @var{oldname} does not exist.
 
-If @var{time} is non-@code{nil}, then this functions gives the new file
+If @var{time} is non-@code{nil}, then this function gives the new file
 the same last-modified time that the old one has.  (This works on only
 some operating systems.)  If setting the time gets an error,
 @code{copy-file} signals a @code{file-date-error} error.
@@ -1579,9 +1588,9 @@ form.
 
 @example
 (file-relative-name "/foo/bar" "/foo/")
-     @result{} "bar")
+     @result{} "bar"
 (file-relative-name "/foo/bar" "/hack/")
-     @result{} "/foo/bar")
+     @result{} "/foo/bar"
 @end example
 @end defun
 
@@ -1653,38 +1662,55 @@ construct a name for such a file:
 @example
 (make-temp-name
  (expand-file-name @var{name-of-application}
-                   (or (getenv "TMPDIR")
-                       "/tmp/")))
+                   temporary-file-directory))
 @end example
 
-@cindex @code{TMPDIR} environment variable.
 @noindent
 The job of @code{make-temp-name} is to prevent two different users or
-two different jobs from trying to use the same name.
-
-This example uses the environment variable @code{TMPDIR} to specify the
-directory, and if that is not specified, we use the directory
-@file{/tmp/}.  This is the standard way to choose the directory, and all
-Emacs Lisp programs should use it.
+two different jobs from trying to use the exact same file name.  This
+example uses the variable @code{temporary-file-directory} to decide
+where to put the temporary file.  All Emacs Lisp programs should
+use @code{temporary-file-directory} for this purpose, to give the user
+a uniform way to specify the directory for all temporary files.
 
 @defun make-temp-name string
-This function generates string that can be used as a unique name.  The
-name starts with @var{string}, and ends with a number that is different
-in each Emacs job.
+This function generates string that can be used as a unique file name.
+The name starts with @var{string}, and contains a number that is
+different in each Emacs job.
 
 @example
 @group
 (make-temp-name "/tmp/foo")
-     @result{} "/tmp/foo021304"
+     @result{} "/tmp/foo232J6v"
 @end group
 @end example
 
 To prevent conflicts among different libraries running in the same
 Emacs, each Lisp program that uses @code{make-temp-name} should have its
-own @var{string}.  The number added to the end of the name distinguishes
-between the same application running in different Emacs jobs.
+own @var{string}.  The number added to the end of @var{string}
+distinguishes between the same application running in different Emacs
+jobs.  Additional added characters permit a large number of distinct
+names even in one Emacs job.
 @end defun
 
+@defvar temporary-file-directory
+@cindex @code{TMPDIR} environment variable.
+@cindex @code{TMP} environment variable.
+This variable specifies the directory name for creating temporary files.
+Its value should be a directory name (@pxref{Directory Names}), but it
+is good for Lisp programs to cope if the value is a file name instead.
+(Using the value as the second argument to @code{expand-file-name} is a
+good way to achieve that.)
+
+The default value is determined in a reasonable way for your operating
+system; on GNU and Unix systems it is based on the @code{TMP} and
+@code{TMPDIR} environment variables.
+
+Even if you do not use @code{make-temp-name} to choose the temporary
+file's name, you should still use this variable to decide which
+directory to put the file in.
+@end defvar
+
 @node File Name Completion
 @subsection File Name Completion
 @cindex file name completion subroutines
@@ -1813,7 +1839,7 @@ is an example from the @code{completion} package:
 
   On GNU and Unix systems, and on some other systems as well,
 @code{convert-standard-filename} returns its argument unchanged.  On
-some other systems, it alters the name to fit the systems's conventions.
+some other systems, it alters the name to fit the system's conventions.
 
   For example, on MS-DOS the alterations made by this function include
 converting a leading @samp{.}  to @samp{_}, converting a @samp{_} in the
@@ -1883,11 +1909,12 @@ 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 the directory listing
-is expected to show a complete directory.  You should specify @code{t}
-when @var{file} is a directory and switches do not contain @samp{-d}.
-(The @samp{-d} option to @code{ls} says to describe a directory itself
-as a file, rather than showing its contents.)
+If @var{full-directory-p} is non-@code{nil}, that means the directory
+listing is expected to show the full contents of a directory.  You
+should specify @code{t} when @var{file} is a directory and switches do
+not contain @samp{-d}.  (The @samp{-d} option to @code{ls} says to
+describe a directory itself as a file, rather than showing 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
@@ -2230,7 +2257,7 @@ The argument @var{format} is a list of format names.  If @var{format} is
 @defvar auto-save-file-format
 This variable specifies the format to use for auto-saving.  Its value is
 a list of format names, just like the value of
-@code{buffer-file-format}; but it is used instead of
-@code{buffer-file-format} for writing auto-save files.  This variable
-is always buffer-local in all buffers.
+@code{buffer-file-format}; however, it is used instead of
+@code{buffer-file-format} for writing auto-save files.  This variable is
+always buffer-local in all buffers.
 @end defvar
diff --git a/lispref/frames.texi b/lispref/frames.texi
index b5c641d891e..612a1a3ff64 100644
--- a/lispref/frames.texi
+++ b/lispref/frames.texi
@@ -13,11 +13,11 @@ perhaps a minibuffer window), which you can subdivide vertically or
 horizontally into smaller windows.
 
 @cindex terminal frame
-@cindex X window frame
   When Emacs runs on a text-only terminal, it starts with one
 @dfn{terminal frame}.  If you create additional ones, Emacs displays
 one and only one at any given time---on the terminal screen, of course.
 
+@cindex window frame
   When Emacs communicates directly with a supported window system, such
 as X Windows, it does not have a terminal frame; instead, it starts with
 a single @dfn{window frame}, but you can create more, and Emacs can
@@ -77,14 +77,14 @@ window system Emacs uses to display its frames.  @xref{Window Frame
 Parameters}, for documentation of individual parameters you can specify.
 @end defun
 
-@tindex before-make-frame-hook
 @defvar before-make-frame-hook
+@tindex before-make-frame-hook
 A normal hook run by @code{make-frame} before it actually creates the
 frame.
 @end defvar
 
-@tindex after-make-frame-hook
 @defvar after-make-frame-hook
+@tindex after-make-frame-hook
 An abnormal hook run by @code{make-frame} after it creates the frame.
 Each function in @code{after-make-frame-hook} receives one argument, the
 frame just created.
@@ -265,6 +265,11 @@ window frame; of these, @code{name}, @code{title}, @code{height},
 meaningful information in terminal frames.
 
 @table @code
+@item display
+The display on which to open this frame.  It should be a string of the
+form @code{"@var{host}:@var{dpy}.@var{screen}"}, just like the
+@code{DISPLAY} environment variable.
+
 @item title
 If a frame has a non-@code{nil} title, it appears in the window system's
 border for the frame, and also in the mode line of windows in that frame
@@ -283,11 +288,6 @@ If you specify the frame name explicitly when you create the frame, the
 name is also used (instead of the name of the Emacs executable) when
 looking up X resources for the frame.
 
-@item display
-The display on which to open this frame.  It should be a string of the
-form @code{"@var{host}:@var{dpy}.@var{screen}"}, just like the
-@code{DISPLAY} environment variable.
-
 @item left
 The screen position of the left edge, in pixels, with respect to the
 left edge of the screen.  The value may be a positive number @var{pos},
@@ -382,7 +382,8 @@ ordered most-recently-selected first.
 
 @item font
 The name of the font for displaying text in the frame.  This is a
-string.
+string, either a valid font name for your system or the name of an Emacs
+fontset (@pxref{Fontsets}).
 
 @item auto-raise
 Whether selecting the frame raises it (non-@code{nil} means yes).
@@ -457,12 +458,14 @@ The default is 1.  @xref{Menu Bar}.  (In Emacs versions that use the X
 toolkit, there is only one menu bar line; all that matters about the
 number you specify is whether it is greater than zero.)
 
+@ignore
 @item parent-id
 @c ??? Not yet working.
 The X window number of the window that should be the parent of this one.
 Specifying this lets you create an Emacs window inside some other
 application's window.  (It is not certain this will be implemented; try
 it and see if it works.)
+@end ignore
 @end table
 
 @node Size and Position
@@ -820,8 +823,8 @@ The redirection lasts until @code{redirect-frame-focus} is called to
 change it.
 @end defun
 
-@tindex focus-follows-mouse
 @defopt focus-follows-mouse
+@tindex focus-follows-mouse
 This option is how you inform Emacs whether the window manager transfers
 focus when the user moves the mouse.  Non-@code{nil} says that it does.
 When this is so, the command @code{other-frame} moves the mouse to a
@@ -895,12 +898,12 @@ on the screen.
 
   You can raise and lower Emacs frame Windows with these functions:
 
-@deffn Command raise-frame frame
-This function raises frame @var{frame}.
+@deffn Command raise-frame &optional frame
+This function raises frame @var{frame} (default, the selected frame).
 @end deffn
 
-@deffn Command lower-frame frame
-This function lowers frame @var{frame}.
+@deffn Command lower-frame &optional frame
+This function lowers frame @var{frame} (default, the selected frame).
 @end deffn
 
 @defopt minibuffer-auto-raise
@@ -1022,7 +1025,8 @@ the top left corner of the inside of @var{frame}.
 This function @dfn{warps the mouse} to position @var{x}, @var{y} in
 frame @var{frame}.  The arguments @var{x} and @var{y} are integers,
 giving the position in characters relative to the top left corner of the
-inside of @var{frame}.
+inside of @var{frame}.  If @var{frame} is not visible, this function
+does nothing.  The return value is not significant.
 @end defun
 
 @defun mouse-pixel-position
@@ -1034,6 +1038,9 @@ coordinates in units of pixels rather than units of characters.
 This function warps the mouse like @code{set-mouse-position} except that
 @var{x} and @var{y} are in units of pixels rather than units of
 characters.  These coordinates are not required to be within the frame.
+
+If @var{frame} is not visible, this function does nothing.  The return
+value is not significant.
 @end defun
 
 @need 3000
@@ -1266,6 +1273,101 @@ for @var{maximum} can make this function much faster, in cases where
 many fonts match the pattern.
 @end defun
 
+@node Fontsets
+@section Fontsets
+
+  A @dfn{fontset} is a list of fonts, each assigned to a range of
+character codes.  An individual font cannot display the whole range of
+characters that Emacs supports, but a fontset can.  Fontsets have names,
+just as fonts do, and you can use a fontset name in place of a font name
+when you specify the ``font'' for a frame or a face.  Here is
+information about defining a fontset under Lisp program control.
+
+@defun create-fontset-from-fontset-spec fontset-spec &optional style noerror
+This function defines a new fontset according to the specification
+string @var{fontset-spec}.  The string should have this format:
+
+@smallexample
+@var{fontpattern}, @r{[}@var{charsetname}:@var{fontname}@r{]@dots{}}
+@end smallexample
+
+@noindent
+Whitespace characters before and after the commas are ignored.
+
+The first part of the string, @var{fontpattern}, should have the form of
+a standard X font name, except that the last two fields should be
+@samp{fontset-@var{alias}}.
+
+Each fontset has two names, one long and one short.  The long name is
+@var{fontpattern} in its entirety.  The short name is
+@samp{fontset-@var{alias}}.  You can refer to the fontset by either
+name.  If a fontset with the same name already exists, an error is
+signaled, unless @var{noerror} is non-@code{nil}, in which case this
+function does nothing.
+
+The specification string also says which fonts to use in the fontset.
+See below for the details.
+@end defun
+
+  If optional argument @var{style} is specified, it specifies a way to
+modify the fontset.  It should be one of @code{bold}, @code{italic}, and
+@code{bold-italic}, and it says to find the bold, italic or bold-italic
+version of each font if possible.
+
+  The construct @samp{@var{charset}:@var{font}} specifies which font to
+use (in this fontset) for one particular character set.  Here,
+@var{charset} is the name of a character set, and @var{font} is the font
+to use for that character set.  You can use this construct any number of
+times in the specification string.
+
+  For the remaining character sets, those that you don't specify
+explicitly, Emacs chooses a font based on @var{fontpattern}: it replaces
+@samp{fontset-@var{alias}} with a value that names one character set.
+For the @sc{ASCII} character set, @samp{fontset-@var{alias}} is replaced
+with @samp{ISO8859-1}.
+
+  In addition, when several consecutive fields are wildcards, Emacs
+collapses them into a single wildcard.  This is to prevent use of
+auto-scaled fonts.  Fonts made by scaling larger fonts are not usable
+for editing, and scaling a smaller font is not useful because it is
+better to use the smaller font in its own size, which Emacs does.
+
+  Thus if @var{fontpattern} is this,
+
+@example
+-*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24
+@end example
+
+@noindent
+the font specification for ASCII characters would be this:
+
+@example
+-*-fixed-medium-r-normal-*-24-*-ISO8859-1
+@end example
+
+@noindent
+and the font specification for Chinese GB2312 characters would be this:
+
+@example
+-*-fixed-medium-r-normal-*-24-*-gb2312*-*
+@end example
+
+  You may not have any Chinese font matching the above font
+specification.  Most X distributions include only Chinese fonts that
+have @samp{song ti} or @samp{fangsong ti} in @var{family} field.  In
+such a case, @samp{Fontset-@var{n}} can be specified as below:
+
+@smallexample
+Emacs.Fontset-0: -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24,\
+        chinese-gb2312:-*-*-medium-r-normal-*-24-*-gb2312*-*
+@end smallexample
+
+@noindent
+Then, the font specifications for all but Chinese GB2312 characters have
+@samp{fixed} in the @var{family} field, and the font specification for
+Chinese GB2312 characters has a wild card @samp{*} in the @var{family}
+field.
+
 @node Color Names
 @section Color Names
 
@@ -1422,7 +1524,7 @@ This function returns the number of color cells the screen supports.
 
 @ignore
 @defvar x-no-window-manager
-This variable's value is is @code{t} if no X window manager is in use.
+This variable's value is @code{t} if no X window manager is in use.
 @end defvar
 @end ignore
 
diff --git a/lispref/functions.texi b/lispref/functions.texi
index b770ac39f7c..510b3e1766d 100644
--- a/lispref/functions.texi
+++ b/lispref/functions.texi
@@ -54,11 +54,11 @@ such as @code{car} or @code{append}.  These functions are also called
 @dfn{built-in} functions or @dfn{subrs}.  (Special forms are also
 considered primitives.)
 
-Usually the reason we implement a function as a primitive is because it
-is fundamental, because it provides a low-level interface to operating
-system services, or because it needs to run fast.  Primitives can be
-modified or added only by changing the C sources and recompiling the
-editor.  See @ref{Writing Emacs Primitives}.
+Usually the reason we implement a function as a primitive is either
+because it is fundamental, because it provides a low-level interface to
+operating system services, or because it needs to run fast.  Primitives
+can be modified or added only by changing the C sources and recompiling
+the editor.  See @ref{Writing Emacs Primitives}.
 
 @item lambda expression
 A @dfn{lambda expression} is a function written in Lisp.
@@ -110,8 +110,8 @@ A @dfn{byte-code function} is a function that has been compiled by the
 byte compiler.  @xref{Byte-Code Type}.
 @end table
 
-@tindex functionp
 @defun functionp object
+@tindex functionp
 This function returns @code{t} if @var{object} is any kind of function,
 or a special form or macro.
 @end defun
@@ -458,11 +458,13 @@ one symbol, this is just a matter of convenience.  It is easy to store
 it in several symbols using @code{fset}; then each of the symbols is
 equally well a name for the same function.
 
-  A symbol used as a function name may also be used as a variable;
-these two uses of a symbol are independent and do not conflict.
-(Some Lisp dialects, such as Scheme, do not distinguish between a
-symbol's value and its function definition; a symbol's value as a variable
-is also its function definition.)
+  A symbol used as a function name may also be used as a variable; these
+two uses of a symbol are independent and do not conflict.  (Some Lisp
+dialects, such as Scheme, do not distinguish between a symbol's value
+and its function definition; a symbol's value as a variable is also its
+function definition.)  If you have not given a symbol a function
+definition, you cannot use it as a function; whether the symbol has a
+value as a variable makes no difference to this.
 
 @node Defining Functions
 @section Defining Functions
@@ -581,7 +583,7 @@ which function to call, and how many arguments to give it, when you
 write the program.  Usually that's just what you want.  Occasionally you
 need to compute at run time which function to call.  To do that, use the
 function @code{funcall}.  When you also need to determine at run time
-how may arguments to pass, use @code{apply}.
+how many arguments to pass, use @code{apply}.
 
 @defun funcall function &rest arguments
 @code{funcall} calls @var{function} with @var{arguments}, and returns
@@ -846,7 +848,8 @@ of simple quotation to quote the anonymous function, like this:
 @example
 @group
 (defun double-property (symbol prop)
-  (change-property symbol prop (function (lambda (x) (* 2 x)))))
+  (change-property symbol prop
+                   (function (lambda (x) (* 2 x)))))
 @end group
 @end example
 
@@ -864,7 +867,7 @@ definition which uses ordinary @code{quote}, the argument passed to
 @noindent
 The Lisp compiler cannot assume this list is a function, even though it
 looks like one, since it does not know what @code{change-property} will
-do with the list.  Perhaps will check whether the @sc{car} of the third
+do with the list.  Perhaps it will check whether the @sc{car} of the third
 element is the symbol @code{*}!  Using @code{function} tells the
 compiler it is safe to go ahead and compile the constant function.
 
@@ -876,6 +879,20 @@ comment:
 (function @var{symbol}) @equiv{} (quote @var{symbol}) @equiv{} '@var{symbol}
 @end example
 
+  The read syntax @code{#'} is a short-hand for using @code{function}.
+For example, 
+
+@example
+#'(lambda (x) (* x x))
+@end example
+
+@noindent
+is equivalent to
+
+@example
+(function (lambda (x) (* x x)))
+@end example
+
 @defspec function function-object
 @cindex function quoting
 This special form returns @var{function-object} without evaluating it.
@@ -952,7 +969,7 @@ is a legitimate function.
 @defun fmakunbound symbol
 This function makes @var{symbol}'s function cell void, so that a
 subsequent attempt to access this cell will cause a @code{void-function}
-error.  (See also @code{makunbound}, in @ref{Local Variables}.)
+error.  (See also @code{makunbound}, in @ref{Void Variables}.)
 
 @example
 @group
diff --git a/lispref/help.texi b/lispref/help.texi
index d31315c0ef1..cde0956b5be 100644
--- a/lispref/help.texi
+++ b/lispref/help.texi
@@ -415,6 +415,15 @@ Emacs buffers are usually displayed).
 @end smallexample
 @end defun
 
+@defun read-kbd-macro string
+This function is used mainly for operating on keyboard macros, but it
+can also be used as a rough inverse for @code{key-description}.  You
+call it with a string containing key descriptions, separated by spaces;
+it returns a string or vector containing the corresponding events.
+(This may or may not be a single valid key sequence, depending on what
+events you use; @pxref{Keymap Terminology}.)
+@end defun
+
 @node Help Functions
 @section Help Functions
 
@@ -431,8 +440,9 @@ named @samp{*Help*}, each with a one-line description taken from the
 beginning of its documentation string.
 
 @c Emacs 19 feature
-If @var{do-all} is non-@code{nil}, then @code{apropos} also shows
-key bindings for the functions that are found.
+If @var{do-all} is non-@code{nil}, then @code{apropos} also shows key
+bindings for the functions that are found; it also shows all symbols,
+even those that are neither functions nor variables.
 
 In the first of the following examples, @code{apropos} finds all the
 symbols with names containing @samp{exec}.  (We don't show here the
@@ -481,10 +491,10 @@ Documentation}.
 
 @defvar help-char
 The value of this variable is the help character---the character that
-Emacs recognizes as meaning Help.  By default, it stands for 8, which is
-@kbd{C-h}.  When Emacs reads this character, if @code{help-form} is
-non-@code{nil} Lisp expression, it evaluates that expression, and
-displays the result in a window if it is a string.
+Emacs recognizes as meaning Help.  By default, its value is 8, which
+stands for @kbd{C-h}.  When Emacs reads this character, if
+@code{help-form} is a non-@code{nil} Lisp expression, it evaluates that
+expression, and displays the result in a window if it is a string.
 
 Usually the value of @code{help-form}'s value is @code{nil}.  Then the
 help character has no special meaning at the level of command input, and
@@ -498,8 +508,8 @@ binding as a subcommand of the prefix key, it runs
 subcommands of the prefix key.
 @end defvar
 
-@tindex help-event-list
 @defvar help-event-list
+@tindex help-event-list
 The value of this variable is a list of event types that serve as
 alternative ``help characters.''  These events are handled just like the
 event specified by @code{help-char}.
@@ -534,11 +544,10 @@ prefix described consists of all but the last event of that key
 sequence.  (The last event is, presumably, the help character.)
 @end defun
 
-  The following two functions are found in the library @file{helper}.
-They are for modes that want to provide help without relinquishing
-control, such as the ``electric'' modes.  You must load that library
-with @code{(require 'helper)} in order to use them.  Their names begin
-with @samp{Helper} to distinguish them from the ordinary help functions.
+  The following two functions are meant for modes that want to provide
+help without relinquishing control, such as the ``electric'' modes.
+Their names begin with @samp{Helper} to distinguish them from the
+ordinary help functions.
 
 @deffn Command Helper-describe-bindings
 This command pops up a window displaying a help buffer containing a
diff --git a/lispref/hooks.texi b/lispref/hooks.texi
index 6b0019146d6..b6904d2b7f7 100644
--- a/lispref/hooks.texi
+++ b/lispref/hooks.texi
@@ -30,7 +30,7 @@ however, we have renamed all of those.)
 
 @c !!! need  xref  to where each hook is documented or else document it
 @c by specifying what is expected, and when it is called relative to
-@c mode initialization.)
+@c mode initialization.
 
 @table @code
 @item activate-mark-hook
diff --git a/lispref/internals.texi b/lispref/internals.texi
index 74d019d2039..33f5cb26dbd 100644
--- a/lispref/internals.texi
+++ b/lispref/internals.texi
@@ -302,6 +302,14 @@ The number of floats in use.
 @c Emacs 19 feature
 The number of floats for which space has been obtained from the
 operating system, but that are not currently being used.
+
+@item used-intervals
+The number of intervals in use.  Intervals are an internal
+data structure used for representing text properties.
+
+@item free-intervals
+The number of intervals for which space has been obtained
+from the operating system, but that are not currently being used.
 @end table
 @end deffn
 
@@ -778,7 +786,7 @@ This field is non-@code{nil} if the buffer's mark is active.
 @item local_var_alist
 This field contains the association list describing the buffer-local
 variable bindings of this buffer, not including the built-in
-buffer-local bindings that that have special slots in the buffer object.
+buffer-local bindings that have special slots in the buffer object.
 (Those slots are omitted from this table.)  @xref{Buffer-Local
 Variables}.
 
diff --git a/lispref/intro.texi b/lispref/intro.texi
index 6d2d63981eb..d6471a4ced1 100644
--- a/lispref/intro.texi
+++ b/lispref/intro.texi
@@ -418,12 +418,17 @@ closely integrated with the editing facilities; thus, editing commands
 are functions that can also conveniently be called from Lisp programs,
 and parameters for customization are ordinary Lisp variables.
 
-  This manual describes Emacs Lisp, presuming considerable familiarity
-with the use of Emacs for editing.  (See @cite{The GNU Emacs Manual}
-for this basic information.)  Generally speaking, the earlier chapters
-describe features of Emacs Lisp that have counterparts in many
-programming languages, and later chapters describe features that are
-peculiar to Emacs Lisp or relate specifically to editing.
+  This manual attempts to be a full description of Emacs Lisp.  For a
+beginner's introduction to Emacs Lisp, see @cite{An Introduction to
+Emacs Lisp Programming}, by Bob Chassell, also published by the Free
+Software Foundation.  This manual presumes considerable familiarity with
+the use of Emacs for editing; see @cite{The GNU Emacs Manual} for this
+basic information.
+
+  Generally speaking, the earlier chapters describe features of Emacs
+Lisp that have counterparts in many programming languages, and later
+chapters describe features that are peculiar to Emacs Lisp or relate
+specifically to editing.
 
   This is edition 2.5.
 
@@ -431,6 +436,7 @@ peculiar to Emacs Lisp or relate specifically to editing.
 * Caveats::             Flaws and a request for help.
 * Lisp History::        Emacs Lisp is descended from Maclisp.
 * Conventions::         How the manual is formatted.
+* Version Info::        Which Emacs version is running?
 * Acknowledgements::    The authors, editors, and sponsors of this manual.
 @end menu
 
@@ -474,7 +480,7 @@ which you are criticizing.
 Please mail comments and corrections to
 
 @example
-bug-lisp-manual@@prep.ai.mit.edu
+bug-lisp-manual@@gnu.org
 @end example
 
 @noindent
@@ -483,7 +489,7 @@ apply the corrections.  Months, and sometimes years, go by between
 updates.  So please attach no significance to the lack of a reply---your
 mail @emph{will} be acted on in due time.  If you want to contact the
 Emacs maintainers more quickly, send mail to
-@code{bug-gnu-emacs@@prep.ai.mit.edu}.
+@code{bug-gnu-emacs@@gnu.org}.
 
 @display
  --Bil Lewis, Dan LaLiberte, Richard Stallman
@@ -493,33 +499,38 @@ Emacs maintainers more quickly, send mail to
 @section Lisp History
 @cindex Lisp history
 
-  Lisp (LISt Processing language) was first developed in the late 1950's
+  Lisp (LISt Processing language) was first developed in the late 1950s
 at the Massachusetts Institute of Technology for research in artificial
-intelligence.  The great power of the Lisp language makes it superior
+intelligence.  The great power of the Lisp language makes it ideal
 for other purposes as well, such as writing editing commands.
 
 @cindex Maclisp
 @cindex Common Lisp
   Dozens of Lisp implementations have been built over the years, each
 with its own idiosyncrasies.  Many of them were inspired by Maclisp,
-which was written in the 1960's at MIT's Project MAC.  Eventually the
+which was written in the 1960s at MIT's Project MAC.  Eventually the
 implementors of the descendants of Maclisp came together and developed a
-standard for Lisp systems, called Common Lisp.  In the mean time, Gerry
+standard for Lisp systems, called Common Lisp.  In the meantime, Gerry
 Sussman and Guy Steele at MIT developed a simplified but very powerful
 dialect of Lisp, called Scheme.
 
   GNU Emacs Lisp is largely inspired by Maclisp, and a little by Common
 Lisp.  If you know Common Lisp, you will notice many similarities.
-However, many of the features of Common Lisp have been omitted or
+However, many features of Common Lisp have been omitted or
 simplified in order to reduce the memory requirements of GNU Emacs.
 Sometimes the simplifications are so drastic that a Common Lisp user
 might be very confused.  We will occasionally point out how GNU Emacs
 Lisp differs from Common Lisp.  If you don't know Common Lisp, don't
 worry about it; this manual is self-contained.
 
+@pindex cl
+  A certain amount of Common Lisp emulation is available via the
+@file{cl} library @xref{Top,, Common Lisp Extension, cl, Common Lisp
+Extensions}.
+
   Emacs Lisp is not at all influenced by Scheme; but the GNU project has
-an implementation of Scheme, called Guile.  We use Guile for
-extensibility in all new GNU software that calls for extensibility.
+an implementation of Scheme, called Guile.  We use Guile in all new GNU
+software that calls for extensibility.
 
 @node Conventions
 @section Conventions
@@ -531,23 +542,22 @@ manual.  You may want to skip this section and refer back to it later.
 * Some Terms::               Explanation of terms we use in this manual.
 * nil and t::                How the symbols @code{nil} and @code{t} are used.
 * Evaluation Notation::      The format we use for examples of evaluation.
-* Printing Notation::        The format we use for examples that print output.
+* Printing Notation::        The format we use when examples print text.
 * Error Messages::           The format we use for examples of errors.
 * Buffer Text Notation::     The format we use for buffer contents in examples.
 * Format of Descriptions::   Notation for describing functions, variables, etc.
-* Version Info::             Which Emacs version is running?
 @end menu
 
 @node Some Terms
 @subsection Some Terms
 
   Throughout this manual, the phrases ``the Lisp reader'' and ``the Lisp
-printer'' are used to refer to those routines in Lisp that convert
-textual representations of Lisp objects into actual Lisp objects, and vice
+printer'' refer to those routines in Lisp that convert textual
+representations of Lisp objects into actual Lisp objects, and vice
 versa.  @xref{Printed Representation}, for more details.  You, the
 person reading this manual, are thought of as ``the programmer'' and are
-addressed as ``you''.  ``The user'' is the person who uses Lisp programs,
-including those you write.
+addressed as ``you''.  ``The user'' is the person who uses Lisp
+programs, including those you write.
 
 @cindex fonts
   Examples of Lisp code appear in this font or form: @code{(list 1 2
@@ -590,7 +600,8 @@ in Lisp programs also.
 is considered to be @var{true}.  However, @code{t} is the preferred way
 to represent the truth value @var{true}.  When you need to choose a
 value which represents @var{true}, and there is no other basis for
-choosing, use @code{t}.  The symbol @code{t} always has value @code{t}.
+choosing, use @code{t}.  The symbol @code{t} always has the value
+@code{t}.
 
   In Emacs Lisp, @code{nil} and @code{t} are special symbols that always
 evaluate to themselves.  This is so that you do not need to quote them
@@ -618,7 +629,7 @@ You can read this as ``@code{(car '(1 2))} evaluates to 1''.
 
   When a form is a macro call, it expands into a new form for Lisp to
 evaluate.  We show the result of the expansion with
-@samp{@expansion{}}.  We may or may not show the actual result of the
+@samp{@expansion{}}.  We may or may not show the result of the
 evaluation of the expanded form.
 
 @example
@@ -741,10 +752,11 @@ indicates that the subsequent arguments may be omitted (omitted
 arguments default to @code{nil}).  Do not write @code{&optional} when
 you call the function.
 
-  The keyword @code{&rest} (which will always be followed by a single
-argument name) indicates that any number of arguments can follow.  The value
-of the single following arguments name will be a list of all these arguments.
-Do not write @code{&rest} when you call the function.
+  The keyword @code{&rest} (which must be followed by a single argument
+name) indicates that any number of arguments can follow.  The single
+following argument name will have a value, as a variable, which is a
+list of all these remaining arguments.  Do not write @code{&rest} when
+you call the function.
 
   Here is a description of an imaginary function @code{foo}:
 
@@ -791,7 +803,7 @@ interactively; macros process their arguments differently from functions
   Special form descriptions use a more complex notation to specify
 optional and repeated arguments because they can break the argument
 list down into separate arguments in more complicated ways.
-@samp{@code{@r{[}@var{optional-arg}@r{]}}} means that @var{optional-arg} is
+@samp{@r{[}@var{optional-arg}@r{]}} means that @var{optional-arg} is
 optional and @samp{@var{repeated-args}@dots{}} stands for zero or more
 arguments.  Parentheses are used when several arguments are grouped into
 additional levels of list structure.  Here is an example:
@@ -800,7 +812,7 @@ additional levels of list structure.  Here is an example:
 This imaginary special form implements a loop that executes the
 @var{body} forms and then increments the variable @var{var} on each
 iteration.  On the first iteration, the variable has the value
-@var{from}; on subsequent iterations, it is incremented by 1 (or by
+@var{from}; on subsequent iterations, it is incremented by one (or by
 @var{inc} if that is given).  The loop exits before executing @var{body}
 if @var{var} equals @var{to}.  Here is an example:
 
@@ -811,7 +823,7 @@ if @var{var} equals @var{to}.  Here is an example:
   (terpri))
 @end example
 
-If @var{from} and @var{to} are omitted, then @var{var} is bound to
+If @var{from} and @var{to} are omitted, @var{var} is bound to
 @code{nil} before the loop begins, and the loop exits if @var{var} is
 non-@code{nil} at the beginning of an iteration.  Here is an example:
 
@@ -855,33 +867,34 @@ replaced by `User Option'.
 @node Version Info
 @section Version Information
 
-  These functions and variables provide information about which
-version of Emacs is in use.
+  These facilities provide information about which version of Emacs is
+in use.
 
 @deffn Command emacs-version
 This function returns a string describing the version of Emacs that is
 running.  It is useful to include this string in bug reports.
 
-@example
+@smallexample
 @group
 (emacs-version)
   @result{} "GNU Emacs 20.3.5 (i486-pc-linux-gnulibc1, X toolkit)
  of Sat Feb 14 1998 on psilocin.gnu.org"
 @end group
-@end example
+@end smallexample
 
 Called interactively, the function prints the same information in the
 echo area.
 @end deffn
 
 @defvar emacs-build-time
-The value of this variable is the time at which Emacs was built at the
-local site.
+The value of this variable indicates the time at which Emacs was built
+at the local site.  It is a list of three integers, like the value
+of @code{current-time} (@pxref{Time of Day}).
 
 @example
 @group
 emacs-build-time
-     @result{} "Tue Jun  6 14:55:57 1995"
+     @result{} (13623 62065 344633)
 @end group
 @end example
 @end defvar
@@ -893,7 +906,7 @@ really part of the Emacs release version number; it is incremented each
 time you build Emacs in any given directory.
 @end defvar
 
-  The following two variables have existed since Emacs version 19.23,
+  The following two variables have existed since Emacs version 19.23:
 
 @defvar emacs-major-version
 The major version number of Emacs, as an integer.  For Emacs version
diff --git a/lispref/keymaps.texi b/lispref/keymaps.texi
index 7e6cc59cecc..d29878d3288 100644
--- a/lispref/keymaps.texi
+++ b/lispref/keymaps.texi
@@ -133,11 +133,11 @@ keymaps}.
 When a keymap contains a vector, it always defines a binding for each
 @sc{ASCII} character, even if the vector contains @code{nil} for that
 character.  Such a binding of @code{nil} overrides any default key
-binding in the keymap.  However, default bindings are still meaningful
-for events that are not @sc{ASCII} characters.  A binding of @code{nil}
-does @emph{not} override lower-precedence keymaps; thus, if the local
-map gives a binding of @code{nil}, Emacs uses the binding from the
-global map.
+binding in the keymap, for @sc{ASCII} characters.  However, default
+bindings are still meaningful for events other than @sc{ASCII}
+characters.  A binding of @code{nil} does @emph{not} override
+lower-precedence keymaps; thus, if the local map gives a binding of
+@code{nil}, Emacs uses the binding from the global map.
 
 @item @var{string}
 @cindex keymap prompt string
@@ -350,7 +350,7 @@ This map is also the function definition of @code{ESC-prefix}.
 
 @item
 @cindex @kbd{C-h}
-@code{help-map} is the global definitions for the @kbd{C-h} prefix key.
+@code{help-map} is the global keymap for the @kbd{C-h} prefix key.
 
 @item
 @cindex @kbd{C-c}
@@ -365,8 +365,8 @@ mode-specific bindings.
 @cindex @kbd{C-x}
 @vindex ctl-x-map
 @findex Control-X-prefix
-@code{ctl-x-map} is the global key map used for the @kbd{C-x} prefix
-key.  This map is found via the function definition of the symbol
+@code{ctl-x-map} is the global keymap used for the @kbd{C-x} prefix key.
+This map is found via the function cell of the symbol
 @code{Control-X-prefix}.
 
 @item
@@ -395,7 +395,7 @@ that have no special names.
 that follows the prefix key.  (It may instead be a symbol whose function
 definition is a keymap.  The effect is the same, but the symbol serves
 as a name for the prefix key.)  Thus, the binding of @kbd{C-x} is the
-symbol @code{Control-X-prefix}, whose function definition is the keymap
+symbol @code{Control-X-prefix}, whose function cell holds the keymap
 for @kbd{C-x} commands.  (The same keymap is also the value of
 @code{ctl-x-map}.)
 
@@ -472,7 +472,7 @@ local keymap is always active except when @code{overriding-local-map}
 overrides it.  Text properties can specify an alternative local map for
 certain parts of the buffer; see @ref{Special Properties}.
 
-  Each minor mode may have a keymap; if it does, the keymap is active
+  Each minor mode can have a keymap; if it does, the keymap is active
 when the minor mode is enabled.
 
   The variable @code{overriding-local-map}, if non-@code{nil}, specifies
@@ -485,11 +485,12 @@ order of decreasing precedence, until it finds a binding in one of the
 maps.  The procedure for searching a single keymap is called @dfn{key
 lookup}; see @ref{Key Lookup}.
 
-Normally, Emacs first searches for the key in the minor mode
-maps (one map at a time); if they do not supply a binding for the key,
-Emacs searches the local map; if that too has no binding, Emacs then
-searches the global map.  However, if @code{overriding-local-map} is
-non-@code{nil}, Emacs searches that map first, before the global map.
+  Normally, Emacs first searches for the key in the minor mode maps, in
+the order specified by @code{minor-mode-map-alist}; if they do not
+supply a binding for the key, Emacs searches the local map; if that too
+has no binding, Emacs then searches the global map.  However, if
+@code{overriding-local-map} is non-@code{nil}, Emacs searches that map
+first, before the global map.
 
 @cindex major mode keymap
   Since every buffer that uses the same major mode normally uses the
@@ -506,6 +507,9 @@ only when the mode is used for the first time in a session.
   The minibuffer has local keymaps, too; they contain various completion
 and exit commands.  @xref{Intro to Minibuffers}.
 
+  Emacs has other keymaps that are used in a different way---translating
+events within @code{read-key-sequence}.  @xref{Translating Input}.
+
   @xref{Standard Keymaps}, for a list of standard keymaps.
 
 @defvar global-map
@@ -604,14 +608,17 @@ modes.  See also @code{minor-mode-key-binding} (@pxref{Functions for Key
 Lookup}).
 @end defvar
 
-@tindex minor-mode-overriding-map-alist
 @defvar minor-mode-overriding-map-alist
+@tindex minor-mode-overriding-map-alist
 This variable allows major modes to override the key bindings for
 particular minor modes.  The elements of this alist look like the
 elements of @code{minor-mode-map-alist}: @code{(@var{variable}
-. @var{keymap})}.  If a variable appears an element
-@code{minor-mode-overriding-map-alist}, that element overrides any
-element for the same variable in @code{minor-mode-map-alist}.
+. @var{keymap})}.
+
+If a variable appears an element of
+@code{minor-mode-overriding-map-alist}, the map specified by that
+element totally replaces any map specified for the same variable in
+@code{minor-mode-map-alist}.
 
 @code{minor-mode-overriding-map-alist} is automatically buffer-local in
 all buffers.
@@ -1414,7 +1421,7 @@ an indirect definition itself.
 @end smallexample
 @end defun
 
-@deffn Command describe-bindings prefix
+@deffn Command describe-bindings &optional prefix
 This function creates a listing of all current key bindings, and
 displays it in a buffer named @samp{*Help*}.  The text is grouped by
 modes---minor modes first, then the major mode, then global bindings.
@@ -1475,8 +1482,12 @@ an existing menu, you can specify its position in the menu using
 @code{define-key-after} (@pxref{Modifying Menus}).
 
 @menu
-* Simple Menu Items::
-* Extended Menu Items::
+* Simple Menu Items::       A simple kind of menu key binding,
+                              limited in capabilities.
+* Alias Menu Items::        Using command aliases in menu items.
+* Extended Menu Items::     More powerful menu item definitions
+                              let you specify keywords to enable
+                              various features.
 @end menu
 
 @node Simple Menu Items
@@ -1489,6 +1500,7 @@ looks like this:
 (@var{item-string} . @var{real-binding})
 @end example
 
+@noindent
 The @sc{car}, @var{item-string}, is the string to be displayed in the
 menu.  It should be short---preferably one to three words.  It should
 describe the action of the command it corresponds to.
@@ -1540,35 +1552,9 @@ Don't put these sublists in the menu item yourself; menu display
 calculates them automatically.  Don't mention keyboard equivalents in
 the item strings themselves, since that is redundant.
 
-Sometimes it is useful to make menu items that use the ``same'' command
-but with different enable conditions.  You can do this by defining alias
-commands.  Here's an example that makes two aliases for
-@code{toggle-read-only} and gives them different enable conditions:
-
-@example
-(defalias 'make-read-only 'toggle-read-only)
-(put 'make-read-only 'menu-enable '(not buffer-read-only))
-(defalias 'make-writable 'toggle-read-only)
-(put 'make-writable 'menu-enable 'buffer-read-only)
-@end example
-
-When using aliases in menus, often it is useful to display the
-equivalent key bindings for the ``real'' command name, not the aliases
-(which typically don't have any key bindings except for the menu
-itself).  To request this, give the alias symbol a non-@code{nil}
-@code{menu-alias} property.  Thus,
-
-@example
-(put 'make-read-only 'menu-alias t)
-(put 'make-writable 'menu-alias t)
-@end example
-
-@noindent
-causes menu items for @code{make-read-only} and @code{make-writable} to
-show the keyboard bindings for @code{toggle-read-only}.
-
 @node Extended Menu Items
 @subsubsection Extended Menu Items
+@kindex menu-item
 
   An extended-format menu item is a more flexible and also cleaner
 alternative to the simple format.  It consists of a list that starts
@@ -1610,7 +1596,7 @@ not defined at all.
 
 @item :help @var{help}
 The value of this property, @var{help}, is the extra help string (not
-currently used).
+currently used by Emacs).
 
 @item :button (@var{type} . @var{selected})
 This property provides a way to define radio buttons and toggle buttons.
@@ -1618,6 +1604,54 @@ The @sc{car}, @var{type}, says which: is should be @code{:toggle} or
 @code{:radio}.  The @sc{cdr}, @var{selected}, should be a form; the
 result of evaluating it says whether this button is currently selected.
 
+A @dfn{toggle} is a menu item which is labeled as either ``on'' or ``off''
+according to the value of @var{selected}.  The command itself should
+toggle @var{selected}, setting it to @code{t} if it is @code{nil},
+and to @code{nil} if it is @code{t}.  Here is how the menu item
+to toggle the @code{debug-on-error} flag is defined:
+
+@example
+(menu-item "Debug on Error" toggle-debug-on-error
+           :button (:toggle
+                    . (and (boundp 'debug-on-error)
+                           debug-on-error))
+@end example
+
+@noindent
+This works because @code{toggle-debug-on-error} is defined as a command
+which toggles the variable @code{debug-on-error}.
+
+@dfn{Radio buttons} are a group of menu items, in which at any time one
+and only one is ``selected.''  There should be a variable whose value
+says which one is selected at any time.  The @var{selected} form for
+each radio button in the group should check whether the variable has the
+right value for selecting that button.  Clicking on the button should
+set the variable so that the button you clicked on becomes selected.
+
+@item :key-sequence @var{key-sequence}
+This property specifies which key sequence is likely to be bound to the
+same command invoked by this menu item.  If you specify the right key
+sequence, that makes preparing the menu for display run much faster.
+
+If you specify the wrong key sequence, it has no effect; before Emacs
+displays @var{key-sequence} in the menu, it verifies that
+@var{key-sequence} is really equivalent to this menu item.
+
+@item :key-sequence nil
+This property indicates that there is normally no key binding which is
+equivalent to this menu item.  Using this property saves time in
+preparing the menu for display, because Emacs does not need to search
+the keymaps for a keyboard equivalent for this menu item.
+
+However, if the user has rebound this item's definition to a key
+sequence, Emacs ignores the @code{:keys} property and finds the keyboard
+equivalent anyway.
+
+@item :keys @var{string}
+This property specifies that @var{string} is the string to display
+as the keyboard equivalent for this menu item.  You can use
+the @samp{\\[...]} documentation construct in @var{string}.
+
 @item :filter @var{filter-fn}
 This property provides a way to compute the menu item dynamically.
 The property value @var{filter-fn} should be a function of one argument;
@@ -1625,6 +1659,38 @@ when it is called, its argument will be @var{real-binding}.  The
 function should return the binding to use instead.
 @end table
 
+@node Alias Menu Items
+@subsubsection Alias Menu Items
+
+  Sometimes it is useful to make menu items that use the ``same''
+command but with different enable conditions.  The best way to do this
+in Emacs now is with extended menu items; before that feature existed,
+it could be done by defining alias commands and using them in menu
+items.  Here's an example that makes two aliases for
+@code{toggle-read-only} and gives them different enable conditions:
+
+@example
+(defalias 'make-read-only 'toggle-read-only)
+(put 'make-read-only 'menu-enable '(not buffer-read-only))
+(defalias 'make-writable 'toggle-read-only)
+(put 'make-writable 'menu-enable 'buffer-read-only)
+@end example
+
+When using aliases in menus, often it is useful to display the
+equivalent key bindings for the ``real'' command name, not the aliases
+(which typically don't have any key bindings except for the menu
+itself).  To request this, give the alias symbol a non-@code{nil}
+@code{menu-alias} property.  Thus,
+
+@example
+(put 'make-read-only 'menu-alias t)
+(put 'make-writable 'menu-alias t)
+@end example
+
+@noindent
+causes menu items for @code{make-read-only} and @code{make-writable} to
+show the keyboard bindings for @code{toggle-read-only}.
+
 @node Mouse Menus
 @subsection Menus and the Mouse
 
@@ -1708,7 +1774,8 @@ for @key{SPC}.
 
   Here is a complete example of defining a menu keymap.  It is the
 definition of the @samp{Print} submenu in the @samp{Tools} menu in the
-menu bar.  First we create the keymap, and give it a name:
+menu bar, and it uses the simple menu item format (@pxref{Simple Menu
+Items}).  First we create the keymap, and give it a name:
 
 @example
 (defvar menu-bar-print-menu (make-sparse-keymap "Print"))
@@ -1771,7 +1838,29 @@ command.
 can do it this way:
 
 @example
-(define-key global-map [C-S-down-mouse-1] menu-bar-print-menu)
+(define-key global-map [C-S-down-mouse-1]
+   menu-bar-print-menu)
+@end example
+
+  We could equally well use an extended menu item (@pxref{Extended Menu
+Items}) for @code{print-region}, like this:
+
+@example
+(define-key menu-bar-print-menu [print-region]
+  '(menu-item "Print Region" print-region
+              :enable (mark-active)))
+@end example
+
+@noindent
+With the extended menu item, the enable condition is specified
+inside the menu item itself.  If we wanted to make this
+item disappear from the menu entirely when the mark is inactive,
+we could do it this way:
+
+@example
+(define-key menu-bar-print-menu [print-region]
+  '(menu-item "Print Region" print-region
+              :visible (mark-active)))
 @end example
 
 @node Menu Bar
diff --git a/lispref/lists.texi b/lispref/lists.texi
index 3f269dc9093..bdc94dc015a 100644
--- a/lispref/lists.texi
+++ b/lispref/lists.texi
@@ -357,8 +357,8 @@ If @var{n} is zero or negative, @code{nthcdr} returns all of
 @end example
 @end defun
 
-@tindex safe-length
 @defun safe-length list
+@tindex safe-length
 This function returns the length of @var{list}, with no risk
 of either an error or an infinite loop.
 
@@ -371,24 +371,24 @@ number of distinct elements.
 worried that it may be circular, is with @code{length}.  @xref{Sequence
 Functions}.
 
-@tindex caar
 @defun caar cons-cell
+@tindex caar
 This is the same as @code{(car (car @var{cons-cell}))}.
 @end defun
 
-@tindex cadr
 @defun cadr cons-cell
+@tindex cadr
 This is the same as @code{(car (cdr @var{cons-cell}))}
 or @code{(nth 1 @var{cons-cell})}.
 @end defun
 
-@tindex cdar
 @defun cdar cons-cell
+@tindex cdar
 This is the same as @code{(cdr (car @var{cons-cell}))}.
 @end defun
 
-@tindex cddr
 @defun cddr cons-cell
+@tindex cddr
 This is the same as @code{(cdr (cdr @var{cons-cell}))}
 or @code{(nthcdr 2 @var{cons-cell})}.
 @end defun
@@ -572,8 +572,8 @@ Here we show the use of vectors and strings as arguments to @code{append}:
 @end group
 @end example
 
-With the help of @code{apply}, we can append all the lists in a list of
-lists:
+With the help of @code{apply} (@pxref{Calling Functions}), we can append
+all the lists in a list of lists:
 
 @example
 @group
@@ -1030,6 +1030,15 @@ arguments.  It is called with two elements of @var{list}.  To get an
 increasing order sort, the @var{predicate} should return @code{t} if the
 first element is ``less than'' the second, or @code{nil} if not.
 
+The comparison function @var{predicate} must give reliable results for
+any given pair of arguments, at least within a single call to
+@code{sort}.  It must be @dfn{antisymmetric}; that is, if @var{a} is
+less than @var{b}, @var{b} must not be less than @var{a}.  It must be
+@dfn{transitive}---that is, if @var{a} is less than @var{b}, and @var{b}
+is less than @var{c}, then @var{a} must be less than @var{c}.  If you
+use a comparison function which does not meet these requirements, the
+result of @code{sort} is unpredictable.
+
 The destructive aspect of @code{sort} is that it rearranges the cons
 cells forming @var{list} by changing @sc{cdr}s.  A nondestructive sort
 function would create new cons cells to store the elements in their
@@ -1338,6 +1347,10 @@ Here is another example, in which the keys and values are not symbols:
 @end smallexample
 @end defun
 
+  The functions @code{assoc-ignore-representation} and
+@code{assoc-ignore-case} are much like @code{assoc} except using
+@code{compare-strings} to do the comparison.  @xref{Text Comparison}.
+
 @defun rassoc value alist
 This function returns the first association with value @var{value} in
 @var{alist}.  It returns @code{nil} if no association in @var{alist} has
diff --git a/lispref/loading.texi b/lispref/loading.texi
index 44eac1cbe44..6dda4a437ed 100644
--- a/lispref/loading.texi
+++ b/lispref/loading.texi
@@ -35,6 +35,8 @@ containing Lisp code.
 
 @menu
 * How Programs Do Loading::     The @code{load} function and others.
+* Library Search::              Finding a library to load.
+* Loading Non-ASCII::           Non-@sc{ASCII} characters in Emacs Lisp files.
 * Autoload::                    Setting up a function to autoload.
 * Repeated Loading::            Precautions about loading a file twice.
 * Named Features::              Loading a library if it isn't already loaded.
@@ -53,7 +55,7 @@ function's real definition (@pxref{Autoload}).  @code{require} loads a
 file if it isn't already loaded (@pxref{Named Features}).  Ultimately,
 all these facilities call the @code{load} function to do the work.
 
-@defun load filename &optional missing-ok nomessage nosuffix
+@defun load filename &optional missing-ok nomessage nosuffix must-suffix
 This function finds and opens a file of Lisp code, evaluates all the
 forms in it, and closes the file.
 
@@ -74,6 +76,12 @@ must specify the precise file name you want.  By specifying the precise
 file name and using @code{t} for @var{nosuffix}, you can prevent
 perverse file names such as @file{foo.el.el} from being tried.
 
+If the optional argument @var{must-suffix} is non-@code{nil}, then
+@code{load} insists that the file name used must end in either
+@samp{.el} or @samp{.elc}, unless it contains an explicit directory
+name.  If @var{filename} does not contain an explicit directory name,
+and does not end in a suffix, then @code{load} insists on adding one.
+
 If @var{filename} is a relative file name, such as @file{foo} or
 @file{baz/foo.bar}, @code{load} searches for the file using the variable
 @code{load-path}.  It appends @var{filename} to each of the directories
@@ -82,7 +90,7 @@ matches.  The current default directory is tried only if it is specified
 in @code{load-path}, where @code{nil} stands for the default directory.
 @code{load} tries all three possible suffixes in the first directory in
 @code{load-path}, then all three suffixes in the second directory, and
-so on.
+so on.  @xref{Library Search}.
 
 If you get a warning that @file{foo.elc} is older than @file{foo.el}, it
 means you should consider recompiling @file{foo.el}.  @xref{Byte
@@ -118,7 +126,7 @@ See below.
 This command loads the file @var{filename}.  If @var{filename} is a
 relative file name, then the current default directory is assumed.
 @code{load-path} is not used, and suffixes are not appended.  Use this
-command if you wish to specify the file to be loaded exactly.
+command if you wish to specify precisely the file name to load.
 @end deffn
 
 @deffn Command load-library library
@@ -126,17 +134,43 @@ This command loads the library named @var{library}.  It is equivalent to
 @code{load}, except in how it reads its argument interactively.
 @end deffn
 
+@defvar load-in-progress
+This variable is non-@code{nil} if Emacs is in the process of loading a
+file, and it is @code{nil} otherwise.
+@end defvar
+
+@defvar load-read-function
+This variable specifies an alternate expression-reading function for
+@code{load} and @code{eval-region} to use instead of @code{read}.
+The function should accept one argument, just as @code{read} does.
+
+Normally, the variable's value is @code{nil}, which means those
+functions should use @code{read}.
+@end defvar
+
+  For how @code{load} is used to build Emacs, see @ref{Building Emacs}.
+
+@node Library Search
+@section Library Search
+
+  When Emacs loads a Lisp library, it searches for the library
+in a list of directories specified by the variable @code{load-path}.
+
 @defopt load-path
 @cindex @code{EMACSLOADPATH} environment variable
 The value of this variable is a list of directories to search when
 loading files with @code{load}.  Each element is a string (which must be
 a directory name) or @code{nil} (which stands for the current working
-directory).  The value of @code{load-path} is initialized from the
-environment variable @code{EMACSLOADPATH}, if that exists; otherwise its
-default value is specified in @file{emacs/src/paths.h} when Emacs is
-built.
+directory).
+@end defopt
+
+  The value of @code{load-path} is initialized from the environment
+variable @code{EMACSLOADPATH}, if that exists; otherwise its default
+value is specified in @file{emacs/src/paths.h} when Emacs is built.
+Then the list is expanded by adding subdirectories of the directories
+in the list.
 
-The syntax of @code{EMACSLOADPATH} is the same as used for @code{PATH};
+  The syntax of @code{EMACSLOADPATH} is the same as used for @code{PATH};
 @samp{:} (or @samp{;}, according to the operating system) separates
 directory names, and @samp{.} is used for the current default directory.
 Here is an example of how to set your @code{EMACSLOADPATH} variable from
@@ -144,17 +178,17 @@ a @code{csh} @file{.login} file:
 
 @c This overfull hbox is OK.  --rjc 16mar92
 @smallexample
-setenv EMACSLOADPATH .:/user/bil/emacs:/usr/lib/emacs/lisp
+setenv EMACSLOADPATH .:/user/bil/emacs:/usr/local/lib/emacs/lisp
 @end smallexample
 
-Here is how to set it using @code{sh}:
+  Here is how to set it using @code{sh}:
 
 @smallexample
 export EMACSLOADPATH
 EMACSLOADPATH=.:/user/bil/emacs:/usr/local/lib/emacs/lisp
 @end smallexample
 
-Here is an example of code you can place in a @file{.emacs} file to add
+  Here is an example of code you can place in a @file{.emacs} file to add
 several directories to the front of your default @code{load-path}:
 
 @smallexample
@@ -174,34 +208,37 @@ followed then by the @file{/user/bil/emacs} directory, the
 @file{/usr/local/lisplib} directory, and the @file{~/emacs} directory,
 which are then followed by the standard directories for Lisp code.
 
-Dumping Emacs uses a special value of @code{load-path}.  If the value of
+  Dumping Emacs uses a special value of @code{load-path}.  If the value of
 @code{load-path} at the end of dumping is unchanged (that is, still the
 same special value), the dumped Emacs switches to the ordinary
 @code{load-path} value when it starts up, as described above.  But if
 @code{load-path} has any other value at the end of dumping, that value
 is used for execution of the dumped Emacs also.
 
-Therefore, if you want to change @code{load-path} temporarily for
+  Therefore, if you want to change @code{load-path} temporarily for
 loading a few libraries in @file{site-init.el} or @file{site-load.el},
 you should bind @code{load-path} locally with @code{let} around the
 calls to @code{load}.
-@end defopt
 
   The default value of @code{load-path}, when running an Emacs which has
-been installed on the system, looks like this:
+been installed on the system, includes two special directories (and
+their subdirectories as well):
 
 @smallexample
-("/usr/local/share/emacs/@var{version}/site-lisp"
- "/usr/local/share/emacs/site-lisp"
- "/usr/local/share/emacs/@var{version}/lisp")
+"/usr/local/share/emacs/@var{version}/site-lisp"
 @end smallexample
 
-  The last of these three directories is where the Lisp files of Emacs
-itself are installed; the first two are for additional Lisp packages
-installed at your site.  The first directory is for locally installed
-packages that belong with a particular Emacs version; the second is for
-locally installed packages that can be used with any installed Emacs
-version.
+@noindent
+and
+
+@smallexample
+"/usr/local/share/emacs/site-lisp"
+@end smallexample
+
+@noindent
+The first one is for locally installed packages for a particular Emacs
+version; the second is for locally installed packages meant for use with
+all installed Emacs versions.
 
   There are several reasons why a Lisp package that works well in one
 Emacs version can cause trouble in another.  Sometimes packages need
@@ -210,28 +247,23 @@ undocumented internal Emacs data that can change without notice;
 sometimes a newer Emacs version incorporates a version of the package,
 and should be used only with that version.
 
+  Emacs finds these directories' subdirectories and adds them to
+@code{load-path} when it starts up.  Both immediate subdirectories and
+subdirectories multiple levels down are added to @code{load-path}.
+
+  Not all subdirectories are included, though.  Subdirectories whose
+names do not start with a letter or digit are excluded.  Subdirectories
+named @file{RCS} are excluded.  Also, a subdirectory which contains a
+file named @file{.nosearch} is excluded.  You can use these methods to
+prevent certain subdirectories of the @file{site-lisp} directories from
+being searched.
+
   If you run Emacs from the directory where it was built---that is, an
 executable that has not been formally installed---then @code{load-path}
 normally contains two additional directories.  These are the @code{lisp}
 and @code{site-lisp} subdirectories of the main build directory.  (Both
 are represented as absolute file names.)
 
-@defvar load-in-progress
-This variable is non-@code{nil} if Emacs is in the process of loading a
-file, and it is @code{nil} otherwise.
-@end defvar
-
-@defvar load-read-function
-This variable specifies an alternate expression-reading function for
-@code{load} and @code{eval-region} to use instead of @code{read}.
-The function should accept one argument, just as @code{read} does.
-
-Normally, the variable's value is @code{nil}, which means those
-functions should use @code{read}.
-@end defvar
-
-  For how @code{load} is used to build Emacs, see @ref{Building Emacs}.
-
 @deffn Command locate-library library &optional nosuffix path interactive-call
 This command finds the precise file name for library @var{library}.  It
 searches for the library in the same way @code{load} does, and the
@@ -248,6 +280,44 @@ interactively, the argument @var{interactive-call} is @code{t}, and this
 tells @code{locate-library} to display the file name in the echo area.
 @end deffn
 
+@node Loading Non-ASCII
+@section Loading Non-ASCII Characters
+
+  When Emacs Lisp programs contain string constants with non-@sc{ASCII}
+characters, these can be represented within Emacs either as unibyte
+strings or as multibyte strings (@pxref{Text Representations}).  Which
+representation is used depends on how the file is read into Emacs.  If
+it is read with decoding into multibyte representation, the text of the
+Lisp program will be multibyte text, and its string constants will be
+multibyte strings.  If a file containing Latin-1 characters (for
+example) is read without decoding, the text of the program will be
+unibyte text, and its string constants will be unibyte strings.
+@xref{Coding Systems}.
+
+  To make the results more predictable, Emacs always performs decoding
+into the multibyte representation when loading Lisp files, even if it
+was started with the @samp{--unibyte} option.  This means that string
+constants with non-@sc{ASCII} characters translate into multibyte
+strings.  The only exception is when a particular file specifies no
+decoding.
+
+  The reason Emacs is designed this way is so that Lisp programs give
+predictable results, regardless of how Emacs was started.  In addition,
+this enables programs that depend on using multibyte text to work even
+in a unibyte Emacs.  Of course, such programs should be designed to
+notice whether the user prefers unibyte or multibyte text, by checking
+@code{default-enable-multibyte-characters}, and convert representations
+appropriately.
+
+  In most Emacs Lisp programs, the fact that non-@sc{ASCII} strings are
+multibyte strings should not be noticeable, since inserting them in
+unibyte buffers converts them to unibyte automatically.  However, if
+this does make a difference, you can force a particular Lisp file to be
+interpreted as unibyte by writing @samp{-*-coding: raw-text;-*-} in a
+comment on the file's first line.  With that designator, the file will
+be unconditionally be interpreted as unibyte, even in an ordinary
+multibyte Emacs session.
+
 @node Autoload
 @section Autoload
 @cindex autoload
@@ -263,8 +333,8 @@ as if it had been loaded all along.
 source before the real definition.  @code{autoload} is the low-level
 primitive for autoloading; any Lisp program can call @code{autoload} at
 any time.  Magic comments are the most convenient way to make a function
-autoload, for packages installed along with Emacs.  They do nothing on
-their own, but they serve as a guide for the command
+autoload, for packages installed along with Emacs.  These comments do
+nothing on their own, but they serve as a guide for the command
 @code{update-file-autoloads}, which constructs calls to @code{autoload}
 and arranges to execute them when Emacs is built.
 
@@ -286,10 +356,10 @@ documentation without loading the function's real definition.
 
 If @var{interactive} is non-@code{nil}, that says @var{function} can be
 called interactively.  This lets completion in @kbd{M-x} work without
-loading its real definition.  The complete interactive specification is
-not given here; it's not needed unless the user actually calls
-@var{function}, and when that happens, it's time to load the real
-definition.
+loading @var{function}'s real definition.  The complete interactive
+specification is not given here; it's not needed unless the user
+actually calls @var{function}, and when that happens, it's time to load
+the real definition.
 
 You can autoload macros and keymaps as well as ordinary functions.
 Specify @var{type} as @code{macro} if @var{function} is really a macro.
@@ -338,9 +408,9 @@ or provide one or more features.  If the file is not completely loaded
 definitions or @code{provide} calls that occurred during the load are
 undone.  This is to ensure that the next attempt to call any function
 autoloading from this file will try again to load the file.  If not for
-this, then some of the functions in the file might appear defined, but
-they might fail to work properly for the lack of certain subroutines
-defined later in the file and not loaded successfully.
+this, then some of the functions in the file might be defined by the
+aborted load, but fail to work properly for the lack of certain
+subroutines not loaded successfully because they come later in the file.
 
   If the autoloaded file fails to define the desired Lisp function or
 macro, then an error is signaled with data @code{"Autoloading failed to
@@ -348,7 +418,7 @@ define function @var{function-name}"}.
 
 @findex update-file-autoloads
 @findex update-directory-autoloads
-  A magic autoload comment looks like @samp{;;;###autoload}, on a line
+  A magic autoload comment consists of @samp{;;;###autoload}, on a line
 by itself, just before the real definition of the function in its
 autoloadable source file.  The command @kbd{M-x update-file-autoloads}
 writes a corresponding @code{autoload} call into @file{loaddefs.el}.
@@ -398,7 +468,7 @@ documentation string in the @file{etc/DOC} file.  @xref{Building Emacs}.
 @section Repeated Loading
 @cindex repeated loading
 
-  You can load one file more than once in an Emacs session.  For
+  You can load a given file more than once in an Emacs session.  For
 example, after you have rewritten and reinstalled a function definition
 by editing it in a buffer, you may wish to return to the original
 version; you can do this by reloading the file it came from.
@@ -409,7 +479,7 @@ rather than a non-compiled file of similar name.  If you rewrite a file
 that you intend to save and reinstall, you need to byte-compile the new
 version; otherwise Emacs will load the older, byte-compiled file instead
 of your newer, non-compiled file!  If that happens, the message
-displayed when loading the file includes, @samp{(compiled; source is
+displayed when loading the file includes, @samp{(compiled; note, source is
 newer)}, to remind you to recompile it.
 
   When writing the forms in a Lisp library file, keep in mind that the
@@ -435,7 +505,7 @@ To avoid the problem, write this:
           (cons '(leif-mode " Leif") minor-mode-alist)))
 @end example
 
-  To add an element to a list just once, use @code{add-to-list}
+  To add an element to a list just once, you can also use @code{add-to-list}
 (@pxref{Setting Variables}).
 
   Occasionally you will want to test explicitly whether a library has
diff --git a/lispref/macros.texi b/lispref/macros.texi
index b9e93bcf6d4..0a739bc3ba5 100644
--- a/lispref/macros.texi
+++ b/lispref/macros.texi
@@ -503,7 +503,7 @@ in expressions ordinarily.
 @node Eval During Expansion
 @subsection Evaluating Macro Arguments in Expansion
 
-  Another problem can happen if you the macro definition itself
+  Another problem can happen if the macro definition itself
 evaluates any of the macro argument expressions, such as by calling
 @code{eval} (@pxref{Eval}).  If the argument is supposed to refer to the
 user's variables, you may have trouble if the user happens to use a
@@ -542,7 +542,7 @@ with @code{eval}) don't occur and its local variable bindings don't
 exist.
 
   To avoid these problems, @strong{don't evaluate an argument expression
-while computing the macro expansion.}  Instead, substitute the
+while computing the macro expansion}.  Instead, substitute the
 expression into the macro expansion, so that its value will be computed
 as part of executing the expansion.  This is how the other examples in
 this chapter work.
diff --git a/lispref/maps.texi b/lispref/maps.texi
index 78b5ceae979..96f8d0921ee 100644
--- a/lispref/maps.texi
+++ b/lispref/maps.texi
@@ -150,8 +150,8 @@ The keymap which displays the Files menu in the menu bar.
 @vindex menu-bar-help-menu
 The keymap which displays the Help menu in the menu bar.
 
-@tindex menu-bar-mule-menu
 @item menu-bar-mule-menu
+@tindex menu-bar-mule-menu
 @vindex menu-bar-mule-menu
 The keymap which displays the Mule menu in the menu bar.
 
diff --git a/lispref/markers.texi b/lispref/markers.texi
index 6a475b7a01e..0fa549bdd16 100644
--- a/lispref/markers.texi
+++ b/lispref/markers.texi
@@ -131,8 +131,8 @@ This function returns @code{t} if @var{object} is an integer or a marker,
 @end defun
 
 @defun number-or-marker-p object
-This function returns @code{t} if @var{object} is a number (either kind)
-or a marker, @code{nil} otherwise.
+This function returns @code{t} if @var{object} is a number (either
+integer or floating point) or a marker, @code{nil} otherwise.
 @end defun
 
 @node Creating Markers
@@ -144,7 +144,7 @@ accessible portion of the buffer, or to the same place as another given
 marker.
 
 @defun make-marker
-This functions returns a newly created marker that does not point
+This function returns a newly created marker that does not point
 anywhere.
 
 @example
@@ -216,8 +216,25 @@ passed an integer argument greater than the length of the buffer,
 @code{copy-marker} returns a new marker that points to the end of the
 buffer.
 
+@example
+@group
+(copy-marker 0)
+     @result{} #<marker at 1 in markers.texi>
+@end group
+
+@group
+(copy-marker 20000)
+     @result{} #<marker at 7572 in markers.texi>
+@end group
+@end example
+
 An error is signaled if @var{marker} is neither a marker nor an
 integer.
+@end defun
+
+  Two distinct markers are considered @code{equal} (even though not
+@code{eq}) to each other if they have the same position and buffer, or
+if they both point nowhere.
 
 @example
 @group
@@ -239,18 +256,7 @@ integer.
 (equal p q)
      @result{} t
 @end group
-
-@group
-(copy-marker 0)
-     @result{} #<marker at 1 in markers.texi>
-@end group
-
-@group
-(copy-marker 20000)
-     @result{} #<marker at 7572 in markers.texi>
-@end group
 @end example
-@end defun
 
 @node Information from Markers
 @section Information from Markers
@@ -296,10 +302,6 @@ This function returns the buffer that @var{marker} points into, or
 @end example
 @end defun
 
-  Two distinct markers are considered @code{equal} (even though not
-@code{eq}) to each other if they have the same position and buffer, or
-if they both point nowhere.
-
 @node Marker Insertion Types
 @section Marker Insertion Types
 
@@ -311,16 +313,16 @@ marker should do by setting its @dfn{insertion type}.  Note that use of
 @code{insert-before-markers} ignores markers' insertion types, always
 relocating a marker to point after the inserted text.
 
-@tindex set-marker-insertion-type
 @defun set-marker-insertion-type marker type
+@tindex set-marker-insertion-type
 This function sets the insertion type of marker @var{marker} to
 @var{type}.  If @var{type} is @code{t}, @var{marker} will advances when
 text is inserted at it.  If @var{type} is @code{nil}, @var{marker} does
 not advance when text is inserted there.
 @end defun
 
-@tindex marker-insertion-type
 @defun marker-insertion-type marker
+@tindex marker-insertion-type
 This function reports the current insertion type of @var{marker}.
 @end defun
 
@@ -377,9 +379,9 @@ This is another name for @code{set-marker}.
 
   One special marker in each buffer is designated @dfn{the mark}.  It
 records a position for the user for the sake of commands such as
-@kbd{C-w} and @kbd{C-x @key{TAB}}.  Lisp programs should set the mark
-only to values that have a potential use to the user, and never for
-their own internal purposes.  For example, the @code{replace-regexp}
+@code{kill-region} and @code{indent-rigidly}.  Lisp programs should set
+the mark only to values that have a potential use to the user, and never
+for their own internal purposes.  For example, the @code{replace-regexp}
 command sets the mark to the value of point before doing any
 replacements, because this enables the user to move back there
 conveniently after the replace is finished.
diff --git a/lispref/minibuf.texi b/lispref/minibuf.texi
index 0ff8e79c1ca..8ddb5d72350 100644
--- a/lispref/minibuf.texi
+++ b/lispref/minibuf.texi
@@ -90,8 +90,8 @@ either one.
 
   In most cases, you should not call minibuffer input functions in the
 middle of a Lisp function.  Instead, do all minibuffer input as part of
-reading the arguments for a command, in the @code{interactive} spec.
-@xref{Defining Commands}.
+reading the arguments for a command, in the @code{interactive}
+specification.  @xref{Defining Commands}.
 
 @defun read-from-minibuffer prompt-string &optional initial-contents keymap read hist default inherit-input-method
 This function is the most general way to get input through the
@@ -115,7 +115,7 @@ The argument @var{default} specifies a default value to make available
 through the history commands.  It should be a string, or @code{nil}.  If
 @var{read} is non-@code{nil}, then @var{default} is also used as the
 input to @code{read}, if the user enters empty input.  However, in the
-usual case (where @var{read} is @code{nil}, @code{read-from-minibuffer}
+usual case (where @var{read} is @code{nil}), @code{read-from-minibuffer}
 does not return @var{default} when the user enters empty input; it
 returns an empty string, @code{""}.  In this respect, it is different
 from all the other minibuffer input functions in this chapter.
@@ -136,9 +136,10 @@ properties were present in the minibuffer.  Otherwise all the text
 properties are stripped when the value is returned.
 
 If the argument @var{inherit-input-method} is non-@code{nil}, then the
-minibuffer inherits the current input method and the setting of
-@code{enable-multibyte-characters} from whichever buffer was current
-before entering the minibuffer.
+minibuffer inherits the current buffer's input method (@pxref{Input
+Methods}) and the setting of @code{enable-multibyte-characters}
+(@pxref{Text Representations}) from whichever buffer was current before
+entering the minibuffer.
 
 If @var{initial-contents} is a string, @code{read-from-minibuffer}
 inserts it into the minibuffer, leaving point at the end, before the
@@ -425,7 +426,12 @@ arguments to other commands).
 @end defvar
 
 @defvar file-name-history
-A history list for file name arguments.
+A history list for file-name arguments.
+@end defvar
+
+@defvar buffer-name-history
+@tindex buffer-name-history
+A history list for buffer-name arguments.
 @end defvar
 
 @defvar regexp-history
@@ -673,10 +679,10 @@ edit the input, providing several commands to attempt completion.
 In most cases, we recommend using @var{default}, and not @var{initial}.
 
 If the argument @var{inherit-input-method} is non-@code{nil}, then the
-minibuffer inherits the current input method and the setting of
-@code{enable-multibyte-characters} from whichever buffer was current
-before entering the minibuffer.  @xref{Input Methods,,, emacs, The GNU
-Emacs Manual}.
+minibuffer inherits the current buffer's input method (@pxref{Input
+Methods}) and the setting of @code{enable-multibyte-characters}
+(@pxref{Text Representations}) from whichever buffer was current before
+entering the minibuffer.
 
 Completion ignores case when comparing the input against the possible
 matches, if the built-in variable @code{completion-ignore-case} is
@@ -853,8 +859,8 @@ reading certain sorts of names with completion.
 
   In most cases, you should not call these functions in the middle of a
 Lisp function.  When possible, do all minibuffer input as part of
-reading the arguments for a command, in the @code{interactive} spec.
-@xref{Defining Commands}.
+reading the arguments for a command, in the @code{interactive}
+specification.  @xref{Defining Commands}.
 
 @defun read-buffer prompt &optional default existing
 This function reads the name of a buffer and returns it as a string.
@@ -1412,8 +1418,8 @@ The return value of @code{map-y-or-n-p} is the number of objects acted on.
 
   This function is useful for reading passwords.
 
-@tindex read-password
 @defun read-password prompt default
+@tindex read-password
 This function reads a password, echoing @samp{.} in the echo area
 for each character entered, and returns it as a string.  It prompts
 with @var{prompt}, and returns @var{default} if the user enters the
diff --git a/lispref/modes.texi b/lispref/modes.texi
index dbdefb5a2d3..dfbdfee00c6 100644
--- a/lispref/modes.texi
+++ b/lispref/modes.texi
@@ -305,7 +305,7 @@ the conventions listed above:
 (if text-mode-map
     ()              ; @r{Do not change the keymap if it is already set up.}
   (setq text-mode-map (make-sparse-keymap))
-  (define-key text-mode-map "\t" 'tab-to-tab-stop)
+  (define-key text-mode-map "\t" 'indent-relative)
   (define-key text-mode-map "\es" 'center-line)
   (define-key text-mode-map "\eS" 'center-paragraph))
 @end group
@@ -399,7 +399,7 @@ mode functions:
   (cond (lisp-syntax
 	  (set-syntax-table lisp-mode-syntax-table)))
   (setq local-abbrev-table lisp-mode-abbrev-table)
-  @dots{})
+  @dots{}
 @end group
 @end smallexample
 
@@ -915,8 +915,8 @@ characters are reserved for major modes.)
 minor mode; with it, you can specify all about a simple minor mode in
 one self-contained definition.
 
-@tindex easy-mmode-define-minor-mode
 @defmac easy-mmode-define-minor-mode mode doc &optional init-value mode-indicator keymap
+@tindex easy-mmode-define-minor-mode
 This macro defines a new minor mode whose name is @var{mode} (a symbol).
 
 This macro defines a command named @var{mode} which toggles the minor
@@ -1144,12 +1144,11 @@ line.  There is nothing inherently special about these variables; any
 other variables could have the same effects on the mode line if
 @code{mode-line-format} were changed to use them.
 
-@tindex mode-line-mule-info
 @defvar mode-line-mule-info
+@tindex mode-line-mule-info
 This variable holds the value of the mode-line construct that displays
 information about the language environment, buffer coding system, and
-current input method.  @xref{International,,, emacs, The GNU Emacs
-Manual}.
+current input method.  @xref{Non-ASCII Characters}.
 @end defvar
 
 @defvar mode-line-modified
@@ -1165,8 +1164,8 @@ modified.
 Changing this variable does not force an update of the mode line.
 @end defvar
 
-@tindex mode-line-frame-identification
 @defvar mode-line-frame-identification
+@tindex mode-line-frame-identification
 This variable identifies the current frame.  The default value is
 @code{" "} if you are using a window system which can show multiple
 frames, or @code{"-%F "} on an ordinary terminal which shows only one
@@ -1426,6 +1425,7 @@ selected by the user, calls @var{function} with arguments
 
 For Emacs Lisp mode, @var{pattern} could look like this:
 
+@c should probably use imenu-syntax-alist and \\sw rather than [-A-Za-z0-9+]
 @example
 @group
 ((nil "^\\s-*(def\\(un\\|subst\\|macro\\|advice\\)\
@@ -1437,7 +1437,8 @@ For Emacs Lisp mode, @var{pattern} could look like this:
 @end group
 @group
  ("*Types*"
-  "^\\s-*(def\\(type\\|struct\\|class\\|ine-condition\\)\
+  "^\\s-*\
+(def\\(type\\|struct\\|class\\|ine-condition\\)\
 \\s-+\\([-A-Za-z0-9+]+\\)" 2))
 @end group
 @end example
@@ -1446,9 +1447,40 @@ Setting this variable makes it buffer-local in the current buffer.
 @end defvar
 
 @defvar imenu-case-fold-search
-This variable controls whether the regular expression matching for Imenu
-is case-sensitive: @code{t}, the default, means matching should ignore
-case.
+This variable controls whether matching against
+@var{imenu-generic-expression} is case-sensitive: @code{t}, the default,
+means matching should ignore case.
+
+Setting this variable makes it buffer-local in the current buffer.
+@end defvar
+
+@defvar imenu-syntax-alist
+This variable is an alist of syntax table modifiers to use while
+executing @code{imenu--generic-function} to override the syntax table of
+the current buffer.  Each element should have this form:
+
+@example
+(@var{characters} . @var{syntax-description})
+@end example
+
+The @sc{car}, @var{characters}, can be either a character or a string.
+The element says to give that character or characters the syntax
+specified by @var{syntax-description}, which is passed to
+@code{modify-syntax-entry} (@pxref{Syntax Table Functions}).
+
+This feature is typically used to give word syntax to characters which
+normally have symbol syntax, and thus to simplify
+@code{imenu-generic-expression} and speed up matching.
+For example, Fortran mode uses it this way:
+
+@example
+  (setq imenu-syntax-alist '(("_$" . "w")))
+@end example
+
+The @code{imenu-generic-expression} patterns can then use @samp{\\sw+}
+instead of @samp{\\(\\sw\\|\\s_\\)\\}.  Note that this technique may be
+inconvenient to use when the mode needs to limit the initial character
+of a name to a smaller set of characters
 
 Setting this variable makes it buffer-local in the current buffer.
 @end defvar
@@ -1568,7 +1600,7 @@ first symbol specifies how to do level 1 fontification, the second
 symbol how to do level 2, and so on.
 
 The second element, @var{keywords-only}, specifies the value of the
-variable @code{font-lock-keywords-only}.  If this is is non-@code{nil},
+variable @code{font-lock-keywords-only}.  If this is non-@code{nil},
 syntactic fontification (of strings and comments) is not performed.
 
 The third element, @var{case-fold}, specifies the value of
@@ -1731,7 +1763,7 @@ where @var{submatcher} is much like @var{matcher}, with one
 exception---see below.  @var{pre-match-form} and @var{post-match-form}
 are evaluated before the first, and after the last, instance
 @var{anchored}'s @var{submatcher} is used.  Therefore they can be used
-to initialise before, and cleanup after, @var{submatcher} is used.
+to initialize before, and cleanup after, @var{submatcher} is used.
 Typically, @var{pre-match-form} is used to move to some position
 relative to the original @var{submatcher}, before starting with
 @var{anchored}'s @var{submatcher}.  @var{post-match-form} might be used
@@ -1787,7 +1819,7 @@ syntactically; it should only fontify based on
 @end defvar
 
 @ignore
-Other variables include those for buffer-specialised fontification functions,
+Other variables include those for buffer-specialized fontification functions,
 `font-lock-fontify-buffer-function', `font-lock-unfontify-buffer-function',
 `font-lock-fontify-region-function', `font-lock-unfontify-region-function',
 `font-lock-inhibit-thing-lock' and `font-lock-maximum-size'.
@@ -2039,6 +2071,27 @@ For example, here's how @code{emacs-lisp-mode} runs its mode hook:
 @end example
 @end defun
 
+@defun run-hook-with-args hook &rest args
+This function is the way to run an abnormal hook which passes arguments
+to the hook functions.  It calls each of the hook functions, passing
+each of them the arguments @var{args}.
+@end defun
+
+@defun run-hook-with-args-until-failure hook &rest args
+This function is the way to run an abnormal hook which passes arguments
+to the hook functions, and stops as soon as any hook function fails.  It
+calls each of the hook functions, passing each of them the arguments
+@var{args}, until some hook function returns @code{nil}.  Then it stops.
+@end defun
+
+@defun run-hook-with-args-until-success hook &rest args
+This function is the way to run an abnormal hook which passes arguments
+to the hook functions, and stops as soon as any hook function succeeds.
+It calls each of the hook functions, passing each of them the arguments
+@var{args}, until some hook function returns non-@code{nil}.  Then it
+stops.
+@end defun
+
 @defun add-hook hook function &optional append local
 This function is the handy way to add function @var{function} to hook
 variable @var{hook}.  The argument @var{function} may be any valid Lisp
diff --git a/lispref/nonascii.texi b/lispref/nonascii.texi
index f75900d6818..ac7c9ed9c43 100644
--- a/lispref/nonascii.texi
+++ b/lispref/nonascii.texi
@@ -17,15 +17,12 @@ characters and how they are stored in strings and buffers.
 * Selecting a Representation::
 * Character Codes::
 * Character Sets::
-* Scanning Charsets::
 * Chars and Bytes::
+* Splitting Characters::
+* Scanning Charsets::
+* Translation of Characters::
 * Coding Systems::
-* Lisp and Coding System::
-* Default Coding Systems::
-* Specifying Coding Systems::
-* Explicit Encoding::
-* MS-DOS File Types::
-* MS-DOS Subprocesses::
+* Input Methods::
 @end menu
 
 @node Text Representations
@@ -53,19 +50,17 @@ character set by setting the variable @code{nonascii-insert-offset}).
 byte, and as a result, the full range of Emacs character codes can be
 stored.  The first byte of a multibyte character is always in the range
 128 through 159 (octal 0200 through 0237).  These values are called
-@dfn{leading codes}.  The first byte determines which character set the
-character belongs to (@pxref{Character Sets}); in particular, it
-determines how many bytes long the sequence is.  The second and
-subsequent bytes of a multibyte character are always in the range 160
-through 255 (octal 0240 through 0377).
+@dfn{leading codes}.  The second and subsequent bytes of a multibyte
+character are always in the range 160 through 255 (octal 0240 through
+0377).
 
   In a buffer, the buffer-local value of the variable
 @code{enable-multibyte-characters} specifies the representation used.
 The representation for a string is determined based on the string
 contents when the string is constructed.
 
-@tindex enable-multibyte-characters
 @defvar enable-multibyte-characters
+@tindex enable-multibyte-characters
 This variable specifies the current buffer's text representation.
 If it is non-@code{nil}, the buffer contains multibyte text; otherwise,
 it contains unibyte text.
@@ -74,20 +69,21 @@ You cannot set this variable directly; instead, use the function
 @code{set-buffer-multibyte} to change a buffer's representation.
 @end defvar
 
-@tindex default-enable-multibyte-characters
 @defvar default-enable-multibyte-characters
-This variable`s value is entirely equivalent to @code{(default-value
+@tindex default-enable-multibyte-characters
+This variable's value is entirely equivalent to @code{(default-value
 'enable-multibyte-characters)}, and setting this variable changes that
-default value.  Although setting the local binding of
-@code{enable-multibyte-characters} in a specific buffer is dangerous,
-changing the default value is safe, and it is a reasonable thing to do.
+default value.  Setting the local binding of
+@code{enable-multibyte-characters} in a specific buffer is not allowed,
+but changing the default value is supported, and it is a reasonable
+thing to do, because it has no effect on existing buffers.
 
 The @samp{--unibyte} command line option does its job by setting the
 default value to @code{nil} early in startup.
 @end defvar
 
-@tindex multibyte-string-p
 @defun multibyte-string-p string
+@tindex multibyte-string-p
 Return @code{t} if @var{string} contains multibyte characters.
 @end defun
 
@@ -120,11 +116,12 @@ user that cannot be overridden automatically.
 unchanged, and likewise 128 through 159.  It converts the non-@sc{ASCII}
 codes 160 through 255 by adding the value @code{nonascii-insert-offset}
 to each character code.  By setting this variable, you specify which
-character set the unibyte characters correspond to.  For example, if
-@code{nonascii-insert-offset} is 2048, which is @code{(- (make-char
-'latin-iso8859-1 0) 128)}, then the unibyte non-@sc{ASCII} characters
-correspond to Latin 1.  If it is 2688, which is @code{(- (make-char
-'greek-iso8859-7 0) 128)}, then they correspond to Greek letters.
+character set the unibyte characters correspond to (@pxref{Character
+Sets}).  For example, if @code{nonascii-insert-offset} is 2048, which is
+@code{(- (make-char 'latin-iso8859-1) 128)}, then the unibyte
+non-@sc{ASCII} characters correspond to Latin 1.  If it is 2688, which
+is @code{(- (make-char 'greek-iso8859-7) 128)}, then they correspond to
+Greek letters.
 
   Converting multibyte text to unibyte is simpler: it performs
 logical-and of each character code with 255.  If
@@ -133,21 +130,22 @@ the beginning of some character set, this conversion is the inverse of
 the other: converting unibyte text to multibyte and back to unibyte
 reproduces the original unibyte text.
 
-@tindex nonascii-insert-offset
 @defvar nonascii-insert-offset
+@tindex nonascii-insert-offset
 This variable specifies the amount to add to a non-@sc{ASCII} character
 when converting unibyte text to multibyte.  It also applies when
-@code{insert-char} or @code{self-insert-command} inserts a character in
-the unibyte non-@sc{ASCII} range, 128 through 255.
+@code{self-insert-command} inserts a character in the unibyte
+non-@sc{ASCII} range, 128 through 255.  However, the function
+@code{insert-char} does not perform this conversion.
 
 The right value to use to select character set @var{cs} is @code{(-
-(make-char @var{cs} 0) 128)}.  If the value of
+(make-char @var{cs}) 128)}.  If the value of
 @code{nonascii-insert-offset} is zero, then conversion actually uses the
 value for the Latin 1 character set, rather than zero.
 @end defvar
 
-@tindex nonascii-translate-table
-@defvar nonascii-translate-table
+@defvar nonascii-translation-table
+@tindex nonascii-translation-table
 This variable provides a more general alternative to
 @code{nonascii-insert-offset}.  You can use it to specify independently
 how to translate each code in the range of 128 through 255 into a
@@ -155,15 +153,15 @@ multibyte character.  The value should be a vector, or @code{nil}.
 If this is non-@code{nil}, it overrides @code{nonascii-insert-offset}.
 @end defvar
 
-@tindex string-make-unibyte
 @defun string-make-unibyte string
+@tindex string-make-unibyte
 This function converts the text of @var{string} to unibyte
 representation, if it isn't already, and return the result.  If
 @var{string} is a unibyte string, it is returned unchanged.
 @end defun
 
-@tindex string-make-multibyte
 @defun string-make-multibyte string
+@tindex string-make-multibyte
 This function converts the text of @var{string} to multibyte
 representation, if it isn't already, and return the result.  If
 @var{string} is a multibyte string, it is returned unchanged.
@@ -175,8 +173,8 @@ representation, if it isn't already, and return the result.  If
   Sometimes it is useful to examine an existing buffer or string as
 multibyte when it was unibyte, or vice versa.
 
-@tindex set-buffer-multibyte
 @defun set-buffer-multibyte multibyte
+@tindex set-buffer-multibyte
 Set the representation type of the current buffer.  If @var{multibyte}
 is non-@code{nil}, the buffer becomes multibyte.  If @var{multibyte}
 is @code{nil}, the buffer becomes unibyte.
@@ -193,8 +191,8 @@ representation is in use.  It also adjusts various data in the buffer
 same text as they did before.
 @end defun
 
-@tindex string-as-unibyte
 @defun string-as-unibyte string
+@tindex string-as-unibyte
 This function returns a string with the same bytes as @var{string} but
 treating each byte as a character.  This means that the value may have
 more characters than @var{string} has.
@@ -203,8 +201,8 @@ If @var{string} is unibyte already, then the value is @var{string}
 itself.
 @end defun
 
-@tindex string-as-multibyte
 @defun string-as-multibyte string
+@tindex string-as-multibyte
 This function returns a string with the same bytes as @var{string} but
 treating each multibyte sequence as one character.  This means that the
 value may have fewer characters than @var{string} has.
@@ -253,88 +251,93 @@ example, @code{latin-iso8859-1} is one character set,
 @code{greek-iso8859-7} is another, and @code{ascii} is another.  An
 Emacs character set can hold at most 9025 characters; therefore, in some
 cases, characters that would logically be grouped together are split
-into several character sets.  For example, one set of Chinese characters
-is divided into eight Emacs character sets, @code{chinese-cns11643-1}
-through @code{chinese-cns11643-7}.
+into several character sets.  For example, one set of Chinese
+characters, generally known as Big 5, is divided into two Emacs
+character sets, @code{chinese-big5-1} and @code{chinese-big5-2}.
 
-@tindex charsetp
 @defun charsetp object
+@tindex charsetp
 Return @code{t} if @var{object} is a character set name symbol,
 @code{nil} otherwise.
 @end defun
 
-@tindex charset-list
 @defun charset-list
+@tindex charset-list
 This function returns a list of all defined character set names.
 @end defun
 
-@tindex char-charset
 @defun char-charset character
-This function returns the the name of the character
+@tindex char-charset
+This function returns the name of the character
 set that @var{character} belongs to.
 @end defun
 
-@node Scanning Charsets
-@section Scanning for Character Sets
-
-  Sometimes it is useful to find out which character sets appear in a
-part of a buffer or a string.  One use for this is in determining which
-coding systems (@pxref{Coding Systems}) are capable of representing all
-of the text in question.
-
-@tindex find-charset-region
-@defun find-charset-region beg end &optional unification
-This function returns a list of the character sets
-that appear in the current buffer between positions @var{beg}
-and @var{end}.
-@end defun
-
-@tindex find-charset-string
-@defun find-charset-string string &optional unification
-This function returns a list of the character sets
-that appear in the string @var{string}.
-@end defun
-
 @node Chars and Bytes
 @section Characters and Bytes
 @cindex bytes and characters
 
+@cindex introduction sequence
+@cindex dimension (of character set)
   In multibyte representation, each character occupies one or more
-bytes.  The functions in this section convert between characters and the
-byte values used to represent them.  For most purposes, there is no need
-to be concerned with the number of bytes used to represent a character
+bytes.  Each character set has an @dfn{introduction sequence}, which is
+one or two bytes long.  The introduction sequence is the beginning of
+the byte sequence for any character in the character set.  (The
+@sc{ASCII} character set has a zero-length introduction sequence.)  The
+rest of the character's bytes distinguish it from the other characters
+in the same character set.  Depending on the character set, there are
+either one or two distinguishing bytes; the number of such bytes is
+called the @dfn{dimension} of the character set.
+
+@defun charset-dimension charset
+@tindex charset-dimension
+This function returns the dimension of @var{charset};
+At present, the dimension is always 1 or 2.
+@end defun
+
+  This is the simplest way to determine the byte length of a character
+set's introduction sequence:
+
+@example
+(- (char-bytes (make-char @var{charset}))
+   (charset-dimension @var{charset}))
+@end example
+
+@node Splitting Characters
+@section Splitting Characters
+
+  The functions in this section convert between characters and the byte
+values used to represent them.  For most purposes, there is no need to
+be concerned with the sequence of bytes used to represent a character,
 because Emacs translates automatically when necessary.
 
-@tindex char-bytes
 @defun char-bytes character
+@tindex char-bytes
 This function returns the number of bytes used to represent the
-character @var{character}.  In most cases, this is the same as
-@code{(length (split-char @var{character}))}; the only exception is for
-ASCII characters and the codes used in unibyte text, which use just one
-byte.
+character @var{character}.  This depends only on the character set that
+@var{character} belongs to; it equals the dimension of that character
+set (@pxref{Character Sets}), plus the length of its introduction
+sequence.
 
 @example
 (char-bytes 2248)
      @result{} 2
 (char-bytes 65)
      @result{} 1
-@end example
-
-This function's values are correct for both multibyte and unibyte
-representations, because the non-@sc{ASCII} character codes used in
-those two representations do not overlap.
-
-@example
 (char-bytes 192)
      @result{} 1
 @end example
+
+The reason this function can give correct results for both multibyte and
+unibyte representations is that the non-@sc{ASCII} character codes used
+in those two representations do not overlap.
 @end defun
 
-@tindex split-char
 @defun split-char character
+@tindex split-char
 Return a list containing the name of the character set of
-@var{character}, followed by one or two byte-values which identify
-@var{character} within that character set.
+@var{character}, followed by one or two byte values (integers) which
+identify @var{character} within that character set.  The number of byte
+values is the character set's dimension.
 
 @example
 (split-char 2248)
@@ -352,11 +355,13 @@ the @code{ascii} character set:
 @end example
 @end defun
 
-@tindex make-char
 @defun make-char charset &rest byte-values
-Thus function returns the character in character set @var{charset}
-identified by @var{byte-values}.  This is roughly the opposite of
-split-char.
+@tindex make-char
+This function returns the character in character set @var{charset}
+identified by @var{byte-values}.  This is roughly the inverse of
+@code{split-char}.  Normally, you should specify either one or two
+@var{byte-values}, according to the dimension of @var{charset}.  For
+example,
 
 @example
 (make-char 'latin-iso8859-1 72)
@@ -364,6 +369,105 @@ split-char.
 @end example
 @end defun
 
+@cindex generic characters
+  If you call @code{make-char} with no @var{byte-values}, the result is
+a @dfn{generic character} which stands for @var{charset}.  A generic
+character is an integer, but it is @emph{not} valid for insertion in the
+buffer as a character.  It can be used in @code{char-table-range} to
+refer to the whole character set (@pxref{Char-Tables}).
+@code{char-valid-p} returns @code{nil} for generic characters.
+For example:
+
+@example
+(make-char 'latin-iso8859-1)
+     @result{} 2176
+(char-valid-p 2176)
+     @result{} nil
+(split-char 2176)
+     @result{} (latin-iso8859-1 0)
+@end example
+
+@node Scanning Charsets
+@section Scanning for Character Sets
+
+  Sometimes it is useful to find out which character sets appear in a
+part of a buffer or a string.  One use for this is in determining which
+coding systems (@pxref{Coding Systems}) are capable of representing all
+of the text in question.
+
+@defun find-charset-region beg end &optional translation
+@tindex find-charset-region
+This function returns a list of the character sets that appear in the
+current buffer between positions @var{beg} and @var{end}.
+
+The optional argument @var{translation} specifies a translation table to
+be used in scanning the text (@pxref{Translation of Characters}).  If it
+is non-@code{nil}, then each character in the region is translated
+through this table, and the value returned describes the translated
+characters instead of the characters actually in the buffer.
+@end defun
+
+@defun find-charset-string string &optional translation
+@tindex find-charset-string
+This function returns a list of the character sets
+that appear in the string @var{string}.
+
+The optional argument @var{translation} specifies a
+translation table; see @code{find-charset-region}, above.
+@end defun
+
+@node Translation of Characters
+@section Translation of Characters
+@cindex character translation tables
+@cindex translation tables
+
+  A @dfn{translation table} specifies a mapping of characters
+into characters.  These tables are used in encoding and decoding, and
+for other purposes.  Some coding systems specify their own particular
+translation tables; there are also default translation tables which
+apply to all other coding systems.
+
+@defun make-translation-table translations
+This function returns a translation table based on the arguments
+@var{translations}.  Each argument---each element of
+@var{translations}---should be a list of the form @code{(@var{from}
+. @var{to})}; this says to translate the character @var{from} into
+@var{to}.
+
+You can also map one whole character set into another character set with
+the same dimension.  To do this, you specify a generic character (which
+designates a character set) for @var{from} (@pxref{Splitting Characters}).
+In this case, @var{to} should also be a generic character, for another
+character set of the same dimension.  Then the translation table
+translates each character of @var{from}'s character set into the
+corresponding character of @var{to}'s character set.
+@end defun
+
+  In decoding, the translation table's translations are applied to the
+characters that result from ordinary decoding.  If a coding system has
+property @code{character-translation-table-for-decode}, that specifies
+the translation table to use.  Otherwise, if
+@code{standard-character-translation-table-for-decode} is
+non-@code{nil}, decoding uses that table.
+
+  In encoding, the translation table's translations are applied to the
+characters in the buffer, and the result of translation is actually
+encoded.  If a coding system has property
+@code{character-translation-table-for-encode}, that specifies the
+translation table to use.  Otherwise the variable
+@code{standard-character-translation-table-for-encode} specifies the
+translation table.
+
+@defvar standard-character-translation-table-for-decode
+This is the default translation table for decoding, for
+coding systems that don't specify any other translation table.
+@end defvar
+
+@defvar standard-character-translation-table-for-encode
+This is the default translation table for encoding, for
+coding systems that don't specify any other translation table.
+@end defvar
+
 @node Coding Systems
 @section Coding Systems
 
@@ -373,6 +477,20 @@ subprocess or receives text from a subprocess, it normally performs
 character code conversion and end-of-line conversion as specified
 by a particular @dfn{coding system}.
 
+@menu
+* Coding System Basics::
+* Encoding and I/O::
+* Lisp and Coding Systems::
+* Default Coding Systems::
+* Specifying Coding Systems::
+* Explicit Encoding::
+* Terminal I/O Encoding::
+* MS-DOS File Types::
+@end menu
+
+@node Coding System Basics
+@subsection Basic Concepts of Coding Systems
+
 @cindex character code conversion
   @dfn{Character code conversion} involves conversion between the encoding
 used inside Emacs and some other encoding.  Emacs supports many
@@ -401,129 +519,219 @@ carriage-return.
 conversion unspecified, to be chosen based on the data.  @dfn{Variant
 coding systems} such as @code{latin-1-unix}, @code{latin-1-dos} and
 @code{latin-1-mac} specify the end-of-line conversion explicitly as
-well.  Each base coding system has three corresponding variants whose
+well.  Most base coding systems have three corresponding variants whose
 names are formed by adding @samp{-unix}, @samp{-dos} and @samp{-mac}.
 
+  The coding system @code{raw-text} is special in that it prevents
+character code conversion, and causes the buffer visited with that
+coding system to be a unibyte buffer.  It does not specify the
+end-of-line conversion, allowing that to be determined as usual by the
+data, and has the usual three variants which specify the end-of-line
+conversion.  @code{no-conversion} is equivalent to @code{raw-text-unix}:
+it specifies no conversion of either character codes or end-of-line.
+
+  The coding system @code{emacs-mule} specifies that the data is
+represented in the internal Emacs encoding.  This is like
+@code{raw-text} in that no code conversion happens, but different in
+that the result is multibyte data.
+
+@defun coding-system-get coding-system property
+@tindex coding-system-get
+This function returns the specified property of the coding system
+@var{coding-system}.  Most coding system properties exist for internal
+purposes, but one that you might find useful is @code{mime-charset}.
+That property's value is the name used in MIME for the character coding
+which this coding system can read and write.  Examples:
+
+@example
+(coding-system-get 'iso-latin-1 'mime-charset)
+     @result{} iso-8859-1
+(coding-system-get 'iso-2022-cn 'mime-charset)
+     @result{} iso-2022-cn
+(coding-system-get 'cyrillic-koi8 'mime-charset)
+     @result{} koi8-r
+@end example
+
+The value of the @code{mime-charset} property is also defined
+as an alias for the coding system.
+@end defun
+
+@node Encoding and I/O
+@subsection Encoding and I/O
+
+  The principal purpose coding systems is for use in reading and
+writing files.  The function @code{insert-file-contents} uses
+a coding system for decoding the file data, and @code{write-region}
+uses one to encode the buffer contents.
+
+  You can specify the coding system to use either explicitly
+(@pxref{Specifying Coding Systems}), or implicitly using the defaulting
+mechanism (@pxref{Default Coding Systems}).  But these methods may not
+completely specify what to do.  For example, they may choose a coding
+system such as @code{undefined} which leaves the character code
+conversion to be determined from the data.  In these cases, the I/O
+operation finishes the job of choosing a coding system.  Very often
+you will want to find out afterwards which coding system was chosen.
+
+@defvar buffer-file-coding-system
+@tindex buffer-file-coding-system
+This variable records the coding system that was used for visiting the
+current buffer.  It is used for saving the buffer, and for writing part
+of the buffer with @code{write-region}.  When those operations ask the
+user to specify a different coding system,
+@code{buffer-file-coding-system} is updated to the coding system
+specified.
+@end defvar
+
+@defvar save-buffer-coding-system
+@tindex save-buffer-coding-system
+This variable specifies the coding system for saving the buffer---but it
+is not used for @code{write-region}.  When saving the buffer asks the
+user to specify a different coding system, and
+@code{save-buffer-coding-system} was used, then it is updated to the
+coding system that was specified.
+@end defvar
+
+@defvar last-coding-system-used
+@tindex last-coding-system-used
+I/O operations for files and subprocesses set this variable to the
+coding system name that was used.  The explicit encoding and decoding
+functions (@pxref{Explicit Encoding}) set it too.
+
+@strong{Warning:} Since receiving subprocess output sets this variable,
+it can change whenever Emacs waits; therefore, you should use copy the
+value shortly after the function call which stores the value you are
+interested in.
+@end defvar
+
 @node Lisp and Coding Systems
 @subsection Coding Systems in Lisp
 
   Here are Lisp facilities for working with coding systems;
 
-@tindex coding-system-list
 @defun coding-system-list &optional base-only
+@tindex coding-system-list
 This function returns a list of all coding system names (symbols).  If
 @var{base-only} is non-@code{nil}, the value includes only the
 base coding systems.  Otherwise, it includes variant coding systems as well.
 @end defun
 
-@tindex coding-system-p
 @defun coding-system-p object
+@tindex coding-system-p
 This function returns @code{t} if @var{object} is a coding system
 name.
 @end defun
 
-@tindex check-coding-system
 @defun check-coding-system coding-system
+@tindex check-coding-system
 This function checks the validity of @var{coding-system}.
 If that is valid, it returns @var{coding-system}.
 Otherwise it signals an error with condition @code{coding-system-error}.
 @end defun
 
-@tindex find-safe-coding-system
-@defun find-safe-coding-system from to
-Return a list of proper coding systems to encode a text between
-@var{from} and @var{to}.  All coding systems in the list can safely
-encode any multibyte characters in the text.
+@defun coding-system-change-eol-conversion coding-system eol-type
+@tindex coding-system-change-eol-conversion
+This function returns a coding system which is like @var{coding-system}
+except for its in eol conversion, which is specified by @code{eol-type}.
+@var{eol-type} should be @code{unix}, @code{dos}, @code{mac}, or
+@code{nil}.  If it is @code{nil}, the returned coding system determines
+the end-of-line conversion from the data.
+@end defun
 
-If the text contains no multibyte characters, return a list of a single
-element @code{undecided}.
+@defun coding-system-change-text-conversion eol-coding text-coding
+@tindex coding-system-change-text-conversion
+This function returns a coding system which uses the end-of-line
+conversion of @var{eol-coding}, and the text conversion of
+@var{text-coding}.  If @var{text-coding} is @code{nil}, it returns
+@code{undecided}, or one of its variants according to @var{eol-coding}.
 @end defun
 
+@defun find-coding-systems-region from to
+@tindex find-coding-systems-region
+This function returns a list of coding systems that could be used to
+encode a text between @var{from} and @var{to}.  All coding systems in
+the list can safely encode any multibyte characters in that portion of
+the text.
+
+If the text contains no multibyte characters, the function returns the
+list @code{(undecided)}.
+@end defun
+
+@defun find-coding-systems-string string
+@tindex find-coding-systems-string
+This function returns a list of coding systems that could be used to
+encode the text of @var{string}.  All coding systems in the list can
+safely encode any multibyte characters in @var{string}.  If the text
+contains no multibyte characters, this returns the list
+@code{(undecided)}.
+@end defun
+
+@defun find-coding-systems-for-charsets charsets
+@tindex find-coding-systems-for-charsets
+This function returns a list of coding systems that could be used to
+encode all the character sets in the list @var{charsets}.
+@end defun
+
+@defun detect-coding-region start end &optional highest
 @tindex detect-coding-region
-@defun detect-coding-region start end highest
 This function chooses a plausible coding system for decoding the text
 from @var{start} to @var{end}.  This text should be ``raw bytes''
 (@pxref{Explicit Encoding}).
 
-Normally this function returns is a list of coding systems that could
+Normally this function returns a list of coding systems that could
 handle decoding the text that was scanned.  They are listed in order of
-decreasing priority, based on the priority specified by the user with
-@code{prefer-coding-system}.  But if @var{highest} is non-@code{nil},
-then the return value is just one coding system, the one that is highest
-in priority.
+decreasing priority.  But if @var{highest} is non-@code{nil}, then the
+return value is just one coding system, the one that is highest in
+priority.
+
+If the region contains only @sc{ASCII} characters, the value
+is @code{undecided} or @code{(undecided)}.
 @end defun
 
-@tindex detect-coding-string string highest
-@defun detect-coding-string
+@defun detect-coding-string string highest
+@tindex detect-coding-string
 This function is like @code{detect-coding-region} except that it
 operates on the contents of @var{string} instead of bytes in the buffer.
 @end defun
 
-@defun find-operation-coding-system operation &rest arguments
-This function returns the coding system to use (by default) for
-performing @var{operation} with @var{arguments}.  The value has this
-form:
-
-@example
-(@var{decoding-system} @var{encoding-system})
-@end example
-
-The first element, @var{decoding-system}, is the coding system to use
-for decoding (in case @var{operation} does decoding), and
-@var{encoding-system} is the coding system for encoding (in case
-@var{operation} does encoding).
-
-The argument @var{operation} should be an Emacs I/O primitive:
-@code{insert-file-contents}, @code{write-region}, @code{call-process},
-@code{call-process-region}, @code{start-process}, or
-@code{open-network-stream}.
-
-The remaining arguments should be the same arguments that might be given
-to that I/O primitive.  Depending on which primitive, one of those
-arguments is selected as the @dfn{target}.  For example, if
-@var{operation} does file I/O, whichever argument specifies the file
-name is the target.  For subprocess primitives, the process name is the
-target.  For @code{open-network-stream}, the target is the service name
-or port number.
-
-This function looks up the target in @code{file-coding-system-alist},
-@code{process-coding-system-alist}, or
-@code{network-coding-system-alist}, depending on @var{operation}.
-@xref{Default Coding Systems}.
-@end defun
-
   Here are two functions you can use to let the user specify a coding
 system, with completion.  @xref{Completion}.
 
+@defun read-coding-system prompt &optional default
 @tindex read-coding-system
-@defun read-coding-system prompt default
 This function reads a coding system using the minibuffer, prompting with
 string @var{prompt}, and returns the coding system name as a symbol.  If
 the user enters null input, @var{default} specifies which coding system
 to return.  It should be a symbol or a string.
 @end defun
 
-@tindex read-non-nil-coding-system
 @defun read-non-nil-coding-system prompt
+@tindex read-non-nil-coding-system
 This function reads a coding system using the minibuffer, prompting with
-string @var{prompt},and returns the coding system name as a symbol.  If
+string @var{prompt}, and returns the coding system name as a symbol.  If
 the user tries to enter null input, it asks the user to try again.
 @xref{Coding Systems}.
 @end defun
 
+  @xref{Process Information}, for how to examine or set the coding
+systems used for I/O to a subprocess.
+
 @node Default Coding Systems
-@section Default Coding Systems
+@subsection Default Coding Systems
 
-  These variable specify which coding system to use by default for
-certain files or when running certain subprograms.  The idea of these
-variables is that you set them once and for all to the defaults you
-want, and then do not change them again.  To specify a particular coding
-system for a particular operation in a Lisp program, don't change these
-variables; instead, override them using @code{coding-system-for-read}
-and @code{coding-system-for-write} (@pxref{Specifying Coding Systems}).
+  This section describes variables that specify the default coding
+system for certain files or when running certain subprograms, and the
+function which which I/O operations use to access them.
+
+  The idea of these variables is that you set them once and for all to the
+defaults you want, and then do not change them again.  To specify a
+particular coding system for a particular operation in a Lisp program,
+don't change these variables; instead, override them using
+@code{coding-system-for-read} and @code{coding-system-for-write}
+(@pxref{Specifying Coding Systems}).
 
-@tindex file-coding-system-alist
 @defvar file-coding-system-alist
+@tindex file-coding-system-alist
 This variable is an alist that specifies the coding systems to use for
 reading and writing particular files.  Each element has the form
 @code{(@var{pattern} . @var{coding})}, where @var{pattern} is a regular
@@ -542,8 +750,8 @@ system or a cons cell containing two coding systems.  This value is used
 as described above.
 @end defvar
 
-@tindex process-coding-system-alist
 @defvar process-coding-system-alist
+@tindex process-coding-system-alist
 This variable is an alist specifying which coding systems to use for a
 subprocess, depending on which program is running in the subprocess.  It
 works like @code{file-coding-system-alist}, except that @var{pattern} is
@@ -553,8 +761,21 @@ coding systems used for I/O to the subprocess, but you can specify
 other coding systems later using @code{set-process-coding-system}.
 @end defvar
 
-@tindex network-coding-system-alist
+  @strong{Warning:} Coding systems such as @code{undecided} which
+determine the coding system from the data do not work entirely reliably
+with asynchronous subprocess output.  This is because Emacs processes
+asynchronous subprocess output in batches, as it arrives.  If the coding
+system leaves the character code conversion unspecified, or leaves the
+end-of-line conversion unspecified, Emacs must try to detect the proper
+conversion from one batch at a time, and this does not always work.
+
+  Therefore, with an asynchronous subprocess, if at all possible, use a
+coding system which determines both the character code conversion and
+the end of line conversion---that is, one like @code{latin-1-unix},
+rather than @code{undecided} or @code{latin-1}.
+
 @defvar network-coding-system-alist
+@tindex network-coding-system-alist
 This variable is an alist that specifies the coding system to use for
 network streams.  It works much like @code{file-coding-system-alist},
 with the difference that the @var{pattern} in an element may be either a
@@ -563,26 +784,60 @@ is matched against the network service name used to open the network
 stream.
 @end defvar
 
-@tindex default-process-coding-system
 @defvar default-process-coding-system
+@tindex default-process-coding-system
 This variable specifies the coding systems to use for subprocess (and
 network stream) input and output, when nothing else specifies what to
 do.
 
-The value should be a cons cell of the form @code{(@var{output-coding}
-. @var{input-coding})}.  Here @var{output-coding} applies to output to
-the subprocess, and @var{input-coding} applies to input from it.
+The value should be a cons cell of the form @code{(@var{input-coding}
+. @var{output-coding})}.  Here @var{input-coding} applies to input from
+the subprocess, and @var{output-coding} applies to output to it.
 @end defvar
 
+@defun find-operation-coding-system operation &rest arguments
+@tindex find-operation-coding-system
+This function returns the coding system to use (by default) for
+performing @var{operation} with @var{arguments}.  The value has this
+form:
+
+@example
+(@var{decoding-system} @var{encoding-system})
+@end example
+
+The first element, @var{decoding-system}, is the coding system to use
+for decoding (in case @var{operation} does decoding), and
+@var{encoding-system} is the coding system for encoding (in case
+@var{operation} does encoding).
+
+The argument @var{operation} should be an Emacs I/O primitive:
+@code{insert-file-contents}, @code{write-region}, @code{call-process},
+@code{call-process-region}, @code{start-process}, or
+@code{open-network-stream}.
+
+The remaining arguments should be the same arguments that might be given
+to that I/O primitive.  Depending on which primitive, one of those
+arguments is selected as the @dfn{target}.  For example, if
+@var{operation} does file I/O, whichever argument specifies the file
+name is the target.  For subprocess primitives, the process name is the
+target.  For @code{open-network-stream}, the target is the service name
+or port number.
+
+This function looks up the target in @code{file-coding-system-alist},
+@code{process-coding-system-alist}, or
+@code{network-coding-system-alist}, depending on @var{operation}.
+@xref{Default Coding Systems}.
+@end defun
+
 @node Specifying Coding Systems
-@section Specifying a Coding System for One Operation
+@subsection Specifying a Coding System for One Operation
 
   You can specify the coding system for a specific operation by binding
 the variables @code{coding-system-for-read} and/or
 @code{coding-system-for-write}.
 
-@tindex coding-system-for-read
 @defvar coding-system-for-read
+@tindex coding-system-for-read
 If this variable is non-@code{nil}, it specifies the coding system to
 use for reading a file, or for input from a synchronous subprocess.
 
@@ -605,14 +860,14 @@ of the right way to use the variable:
 @end example
 
 When its value is non-@code{nil}, @code{coding-system-for-read} takes
-precedence all other methods of specifying a coding system to use for
+precedence over all other methods of specifying a coding system to use for
 input, including @code{file-coding-system-alist},
 @code{process-coding-system-alist} and
 @code{network-coding-system-alist}.
 @end defvar
 
-@tindex coding-system-for-write
 @defvar coding-system-for-write
+@tindex coding-system-for-write
 This works much like @code{coding-system-for-read}, except that it
 applies to output rather than input.  It affects writing to files,
 subprocesses, and net connections.
@@ -623,53 +878,16 @@ When a single operation does both input and output, as do
 affect it.
 @end defvar
 
-@tindex last-coding-system-used
-@defvar last-coding-system-used
-All I/O operations that use a coding system set this variable
-to the coding system name that was used.
-@end defvar
-
-@tindex inhibit-eol-conversion
 @defvar inhibit-eol-conversion
+@tindex inhibit-eol-conversion
 When this variable is non-@code{nil}, no end-of-line conversion is done,
 no matter which coding system is specified.  This applies to all the
 Emacs I/O and subprocess primitives, and to the explicit encoding and
 decoding functions (@pxref{Explicit Encoding}).
 @end defvar
 
-@tindex keyboard-coding-system
-@defun keyboard-coding-system
-This function returns the coding system that is in use for decoding
-keyboard input---or @code{nil} if no coding system is to be used.
-@end defun
-
-@tindex set-keyboard-coding-system
-@defun set-keyboard-coding-system coding-system
-This function specifies @var{coding-system} as the coding system to
-use for decoding keyboard input.  If @var{coding-system} is @code{nil},
-that means do not decode keyboard input.
-@end defun
-
-@tindex terminal-coding-system
-@defun terminal-coding-system
-This function returns the coding system that is in use for encoding
-terminal output---or @code{nil} for no encoding.
-@end defun
-
-@tindex set-terminal-coding-system
-@defun set-terminal-coding-system coding-system
-This function specifies @var{coding-system} as the coding system to use
-for encoding terminal output.  If @var{coding-system} is @code{nil},
-that means do not encode terminal output.
-@end defun
-
-  See also the functions @code{process-coding-system} and
-@code{set-process-coding-system}.  @xref{Process Information}.
-
-  See also @code{read-coding-system} in @ref{High-Level Completion}.
-
 @node Explicit Encoding
-@section Explicit Encoding and Decoding
+@subsection Explicit Encoding and Decoding
 @cindex encoding text
 @cindex decoding text
 
@@ -699,39 +917,72 @@ write them with @code{write-region} (@pxref{Writing to Files}), and
 suppress encoding for that @code{write-region} call by binding
 @code{coding-system-for-write} to @code{no-conversion}.
 
-@tindex encode-coding-region
 @defun encode-coding-region start end coding-system
+@tindex encode-coding-region
 This function encodes the text from @var{start} to @var{end} according
 to coding system @var{coding-system}.  The encoded text replaces the
 original text in the buffer.  The result of encoding is ``raw bytes,''
 but the buffer remains multibyte if it was multibyte before.
 @end defun
 
-@tindex encode-coding-string
 @defun encode-coding-string string coding-system
+@tindex encode-coding-string
 This function encodes the text in @var{string} according to coding
 system @var{coding-system}.  It returns a new string containing the
 encoded text.  The result of encoding is a unibyte string of ``raw bytes.''
 @end defun
 
-@tindex decode-coding-region
 @defun decode-coding-region start end coding-system
+@tindex decode-coding-region
 This function decodes the text from @var{start} to @var{end} according
 to coding system @var{coding-system}.  The decoded text replaces the
 original text in the buffer.  To make explicit decoding useful, the text
 before decoding ought to be ``raw bytes.''
 @end defun
 
-@tindex decode-coding-string
 @defun decode-coding-string string coding-system
+@tindex decode-coding-string
 This function decodes the text in @var{string} according to coding
 system @var{coding-system}.  It returns a new string containing the
 decoded text.  To make explicit decoding useful, the contents of
 @var{string} ought to be ``raw bytes.''
 @end defun
 
+@node Terminal I/O Encoding
+@subsection Terminal I/O Encoding
+
+  Emacs can decode keyboard input using a coding system, and encode
+terminal output.  This kind of decoding and encoding does not set
+@code{last-coding-system-used}.
+
+@defun keyboard-coding-system
+@tindex keyboard-coding-system
+This function returns the coding system that is in use for decoding
+keyboard input---or @code{nil} if no coding system is to be used.
+@end defun
+
+@defun set-keyboard-coding-system coding-system
+@tindex set-keyboard-coding-system
+This function specifies @var{coding-system} as the coding system to
+use for decoding keyboard input.  If @var{coding-system} is @code{nil},
+that means do not decode keyboard input.
+@end defun
+
+@defun terminal-coding-system
+@tindex terminal-coding-system
+This function returns the coding system that is in use for encoding
+terminal output---or @code{nil} for no encoding.
+@end defun
+
+@defun set-terminal-coding-system coding-system
+@tindex set-terminal-coding-system
+This function specifies @var{coding-system} as the coding system to use
+for encoding terminal output.  If @var{coding-system} is @code{nil},
+that means do not encode terminal output.
+@end defun
+
 @node MS-DOS File Types
-@section MS-DOS File Types
+@subsection MS-DOS File Types
 @cindex DOS file types
 @cindex MS-DOS file types
 @cindex Windows file types
@@ -740,17 +991,24 @@ decoded text.  To make explicit decoding useful, the contents of
 @cindex binary files and text files
 
   Emacs on MS-DOS and on MS-Windows recognizes certain file names as
-text files or binary files.  For a text file, Emacs always uses DOS
-end-of-line conversion.  For a binary file, Emacs does no end-of-line
-conversion and no character code conversion.
+text files or binary files.  By ``binary file'' we mean a file of
+literal byte values that are not necessary meant to be characters.
+Emacs does no end-of-line conversion and no character code conversion
+for a binary file.  Meanwhile, when you create a new file which is
+marked by its name as a ``text file'', Emacs uses DOS end-of-line
+conversion.
 
 @defvar buffer-file-type
 This variable, automatically buffer-local in each buffer, records the
-file type of the buffer's visited file.  The value is @code{nil} for
-text, @code{t} for binary.  When a buffer does not specify a coding
-system with @code{buffer-file-coding-system}, this variable is used by
-the function @code{find-buffer-file-type-coding-system} to determine
-which coding system to use when writing the contents of the buffer.
+file type of the buffer's visited file.  When a buffer does not specify
+a coding system with @code{buffer-file-coding-system}, this variable is
+used to determine which coding system to use when writing the contents
+of the buffer.  It should be @code{nil} for text, @code{t} for binary.
+If it is @code{t}, the coding system is @code{no-conversion}.
+Otherwise, @code{undecided-dos} is used.
+
+Normally this variable is set by visiting a file; it is set to
+@code{nil} if the file was visited without any actual conversion.
 @end defvar
 
 @defopt file-name-buffer-file-type-alist
@@ -775,26 +1033,80 @@ This variable says how to handle files for which
 @code{file-name-buffer-file-type-alist} says nothing about the type.
 
 If this variable is non-@code{nil}, then these files are treated as
-binary.  Otherwise, nothing special is done for them---the coding system
-is deduced solely from the file contents, in the usual Emacs fashion.
+binary: the coding system @code{no-conversion} is used.  Otherwise,
+nothing special is done for them---the coding system is deduced solely
+from the file contents, in the usual Emacs fashion.
 @end defopt
 
-@node MS-DOS Subprocesses
-@section MS-DOS Subprocesses
-
-  On Microsoft operating systems, these variables provide an alternative
-way to specify the kind of end-of-line conversion to use for input and
-output.  The variable @code{binary-process-input} applies to input sent
-to the subprocess, and @code{binary-process-output} applies to output
-received from it.  A non-@code{nil} value means the data is ``binary,''
-and @code{nil} means the data is text.
-
-@defvar binary-process-input
-If this variable is @code{nil}, convert newlines to @sc{crlf} sequences in
-the input to a synchronous subprocess.
+@node Input Methods
+@section Input Methods
+@cindex input methods
+
+  @dfn{Input methods} provide convenient ways of entering non-@sc{ASCII}
+characters from the keyboard.  Unlike coding systems, which translate
+non-@sc{ASCII} characters to and from encodings meant to be read by
+programs, input methods provide human-friendly commands.  (@xref{Input
+Methods,,, emacs, The GNU Emacs Manual}, for information on how users
+use input methods to enter text.)  How to define input methods is not
+yet documented in this manual, but here we describe how to use them.
+
+  Each input method has a name, which is currently a string;
+in the future, symbols may also be usable as input method names.
+
+@tindex current-input-method
+@defvar current-input-method
+This variable holds the name of the input method now active in the
+current buffer.  (It automatically becomes local in each buffer when set
+in any fashion.)  It is @code{nil} if no input method is active in the
+buffer now.
 @end defvar
 
-@defvar binary-process-output
-If this variable is @code{nil}, convert @sc{crlf} sequences to newlines in
-the output from a synchronous subprocess.
+@tindex default-input-method
+@defvar default-input-method
+This variable holds the default input method for commands that choose an
+input method.  Unlike @code{current-input-method}, this variable is
+normally global.
 @end defvar
+
+@tindex set-input-method
+@defun set-input-method input-method
+This function activates input method @var{input-method} for the current
+buffer.  It also sets @code{default-input-method} to @var{input-method}.
+If @var{input-method} is @code{nil}, this function deactivates any input
+method for the current buffer.
+@end defun
+
+@tindex read-input-method-name
+@defun read-input-method-name prompt &optional default inhibit-null
+This function reads an input method name with the minibuffer, prompting
+with @var{prompt}.  If @var{default} is non-@code{nil}, that is returned
+by default, if the user enters empty input.  However, if
+@var{inhibit-null} is non-@code{nil}, empty input signals an error.
+
+The returned value is a string.
+@end defun
+
+@tindex input-method-alist
+@defvar input-method-alist
+This variable defines all the supported input methods.
+Each element defines one input method, and should have the form:
+
+@example
+(@var{input-method} @var{language-env} @var{activate-func} @var{title} @var{description} @var{args}...)
+@end example
+
+Here @var{input-method} is the input method name, a string; @var{env} is
+another string, the name of the language environment this input method
+is recommended for.  (That serves only for documentation purposes.)
+
+@var{title} is a string to display in the mode line while this method is
+active.  @var{description} is a string describing this method and what
+it is good for.
+
+@var{activate-func} is a function to call to activate this method.  The
+@var{args}, if any, are passed as arguments to @var{activate-func}.  All
+told, the arguments to @var{activate-func} are @var{input-method} and
+the @var{args}.
+@end defun
+
+
diff --git a/lispref/numbers.texi b/lispref/numbers.texi
index daee3890e77..fbbdc83871e 100644
--- a/lispref/numbers.texi
+++ b/lispref/numbers.texi
@@ -249,6 +249,11 @@ numbers or markers.  However, it is a good idea to use @code{=} if you
 can, even for comparing integers, just in case we change the
 representation of integers in a future Emacs version.
 
+  Sometimes it is useful to compare numbers with @code{equal}; it treats
+two numbers as equal if they have the same data type (both integers, or
+both floating point) and the same value.  By contrast, @code{=} can
+treat an integer and a floating point number as equal.
+
   There is another wrinkle: because floating point arithmetic is not
 exact, it is often a bad idea to check for equality of two floating
 point values.  Usually it is better to test for approximate equality.
@@ -328,7 +333,7 @@ This function returns the smallest of its arguments.
 @end defun
 
 @defun abs number
-This returns the absolute value of @var{number}.
+This function returns the absolute value of @var{number}.
 @end defun
 
 @node Numeric Conversions
@@ -357,9 +362,9 @@ This returns @var{number}, converted to an integer by rounding downward
 (towards negative infinity).
 
 If @var{divisor} is specified, @var{number} is divided by @var{divisor}
-before the floor is taken; this is the division operation that
-corresponds to @code{mod}.  An @code{arith-error} results if
-@var{divisor} is 0.
+before the floor is taken; this uses the kind of division operation that
+corresponds to @code{mod}, rounding downward.  An @code{arith-error}
+results if @var{divisor} is 0.
 @end defun
 
 @defun ceiling number
@@ -600,7 +605,7 @@ Conversions}.
 @section Rounding Operations
 @cindex rounding without conversion
 
-The functions @code{ffloor}, @code{fceiling}, @code{fround} and
+The functions @code{ffloor}, @code{fceiling}, @code{fround}, and
 @code{ftruncate} take a floating point argument and return a floating
 point result whose value is a nearby integer.  @code{ffloor} returns the
 nearest integer below; @code{fceiling}, the nearest integer above;
@@ -965,14 +970,34 @@ and pi/2 (exclusive) whose tangent is @var{arg}.
 @end defun
 
 @defun exp arg
-This is the exponential function; it returns @i{e} to the power
-@var{arg}.  @i{e} is a fundamental mathematical constant also called the
-base of natural logarithms.
+This is the exponential function; it returns
+@tex
+$e$
+@end tex
+@ifinfo
+@i{e}
+@end ifinfo
+to the power @var{arg}.
+@tex
+$e$
+@end tex
+@ifinfo
+@i{e}
+@end ifinfo
+is a fundamental mathematical constant also called the base of natural
+logarithms.
 @end defun
 
 @defun log arg &optional base
 This function returns the logarithm of @var{arg}, with base @var{base}.
-If you don't specify @var{base}, the base @var{e} is used.  If @var{arg}
+If you don't specify @var{base}, the base
+@tex
+$e$
+@end tex
+@ifinfo
+@i{e}
+@end ifinfo
+is used.  If @var{arg}
 is negative, the result is a NaN.
 @end defun
 
diff --git a/lispref/objects.texi b/lispref/objects.texi
index ea1e8fb1632..f2c082b56bc 100644
--- a/lispref/objects.texi
+++ b/lispref/objects.texi
@@ -396,8 +396,9 @@ distinction to the computer in any way.
 @cindex alt characters
   The X Window System defines three other modifier bits that can be set
 in a character: @dfn{hyper}, @dfn{super} and @dfn{alt}.  The syntaxes
-for these bits are @samp{\H-}, @samp{\s-} and @samp{\A-}.  Thus,
-@samp{?\H-\M-\A-x} represents @kbd{Alt-Hyper-Meta-x}.
+for these bits are @samp{\H-}, @samp{\s-} and @samp{\A-}.  (Case is
+significant in these prefixes.)  Thus, @samp{?\H-\M-\A-x} represents
+@kbd{Alt-Hyper-Meta-x}.
 @tex
 Numerically, the
 bit values are $2^{22}$ for alt, $2^{23}$ for super and $2^{24}$ for hyper.
@@ -882,9 +883,9 @@ character code, using a hex escape, @samp{\x@var{nnnnnnn}}, with as many
 digits as necessary.  (Multibyte non-@sc{ASCII} character codes are all
 greater than 256.)  Any character which is not a valid hex digit
 terminates this construct.  If the character that would follow is a hex
-digit, write @samp{\ } to terminate the hex escape---for example,
-@samp{\x8c0\ } represents one character, @samp{a} with grave accent.
-@samp{\ } in a string constant is just like backslash-newline; it does
+digit, write @w{@samp{\ }} to terminate the hex escape---for example,
+@w{@samp{\x8c0\ }} represents one character, @samp{a} with grave accent.
+@w{@samp{\ }} in a string constant is just like backslash-newline; it does
 not contribute any character to the string, but it does terminate the
 preceding hex escape.
 
@@ -899,30 +900,35 @@ text representations.
 @node Nonprinting Characters
 @subsubsection Nonprinting Characters in Strings
 
-  Strings cannot hold characters that have the hyper, super, or alt
-modifiers; the only control or meta characters they can hold are the
-@sc{ASCII} control characters.  Strings do not distinguish case in
-@sc{ASCII} control characters.
-
   You can use the same backslash escape-sequences in a string constant
 as in character literals (but do not use the question mark that begins a
 character constant).  For example, you can write a string containing the
-nonprinting characters tab, @kbd{C-a} and @kbd{M-C-a}, with commas and
-spaces between them, like this: @code{"\t, \C-a, \M-\C-a"}.
-@xref{Character Type}, for a description of the read syntax for
-characters.
-
-  If you use the @samp{\M-} syntax to indicate a meta character in a
-string constant, this sets the
+nonprinting characters tab and @kbd{C-a}, with commas and spaces between
+them, like this: @code{"\t, \C-a"}.  @xref{Character Type}, for a
+description of the read syntax for characters.
+
+  However, not all of the characters you can write with backslash
+escape-sequences are valid in strings.  The only control characters that
+a string can hold are the @sc{ASCII} control characters.  Strings do not
+distinguish case in @sc{ASCII} control characters.
+
+  Properly speaking, strings cannot hold meta characters; but when a
+string is to be used as a key sequence, there is a special convention
+that allows the meta versions of @sc{ASCII} characters to be put in a
+string.  If you use the @samp{\M-} syntax to indicate a meta character
+in a string constant, this sets the
 @tex
 $2^{7}$
 @end tex
 @ifinfo
 2**7
 @end ifinfo
-bit of the character in the string.  This construct works only with
-ASCII characters.  Note that the same meta characters have a different
-representation when not in a string.  @xref{Character Type}.
+bit of the character in the string.  If the string is used in
+@code{define-key} or @code{lookup-key}, this numeric code is translated
+into the equivalent meta character.  @xref{Character Type}.
+
+  Strings cannot hold characters that have the hyper, super, or alt
+modifiers.
 
 @node Text Props and Strings
 @subsubsection Text Properties in Strings
@@ -960,7 +966,9 @@ represents a string whose textual contents are @samp{foo bar}, in which
 the first three characters have a @code{face} property with value
 @code{bold}, and the last three have a @code{face} property with value
 @code{italic}.  (The fourth character has no text properties so its
-property list is @code{nil}.)
+property list is @code{nil}.  It is not actually necessary to mention
+ranges with @code{nil} as the property list, since any characters not
+mentioned in any range will default to having no properties.)
 
 @node Vector Type
 @subsection Vector Type
@@ -1024,17 +1032,18 @@ that it begins with @samp{#&} followed by the length.  The string
 constant that follows actually specifies the contents of the bool-vector
 as a bitmap---each ``character'' in the string contains 8 bits, which
 specify the next 8 elements of the bool-vector (1 stands for @code{t},
-and 0 for @code{nil}).  If the length is not a multiple of 8, the
-printed representation describes extra elements, but these really
-make no difference.
+and 0 for @code{nil}).  The least significant bits of the character are
+the lowest-numbered elements of the bool-vector.  If the length is not a
+multiple of 8, the printed representation shows extra elements, but
+these extras really make no difference.
 
 @example
 (make-bool-vector 3 t)
-     @result{} #&3"\377"
+     @result{} #&3"\007"
 (make-bool-vector 3 nil)
-     @result{} #&3"\0""
+     @result{} #&3"\0"
 ;; @r{These are equal since only the first 3 bits are used.}
-(equal #&3"\377" #&3"\340")
+(equal #&3"\377" #&3"\007")
      @result{} t
 @end example
 
@@ -1151,7 +1160,7 @@ symbol.  @xref{Autoload}, for more details.
 @section Editing Types
 @cindex editing types
 
-  The types in the previous section used for general programming
+  The types in the previous section are used for general programming
 purposes, and most of them are common to most Lisp dialects.  Emacs Lisp
 provides several additional data types for purposes connected with
 editing.
@@ -1288,7 +1297,7 @@ in any given window can change frequently.
 @node Frame Type
 @subsection Frame Type
 
-  A @var{frame} is a rectangle on the screen that contains one or more
+  A @dfn{frame} is a rectangle on the screen that contains one or more
 Emacs windows.  A frame initially contains a single main window (plus
 perhaps a minibuffer window) which you can subdivide vertically or
 horizontally into smaller windows.
@@ -1300,7 +1309,7 @@ uniquely).
 @example
 @group
 (selected-frame)
-     @result{} #<frame emacs@@mole.gnu.ai.mit.edu 0xdac80>
+     @result{} #<frame emacs@@psilocin.gnu.org 0xdac80>
 @end group
 @end example
 
@@ -1668,10 +1677,10 @@ object.
 @end group
 @end example
 
-(The @code{make-symbol} function returns an uninterned symbol that is
-not interned in the standard @code{obarray}.  When uninterned symbols
-are in use, symbol names are no longer unique.  Distinct symbols with
-the same name are not @code{eq}.  @xref{Creating Symbols}.)
+The @code{make-symbol} function returns an uninterned symbol, distinct
+from the symbol that is used if you write the name in a Lisp expression.
+Distinct symbols with the same name are not @code{eq}.  @xref{Creating
+Symbols}.
 
 @example
 @group
diff --git a/lispref/os.texi b/lispref/os.texi
index a9d58c55aef..b3764422dff 100644
--- a/lispref/os.texi
+++ b/lispref/os.texi
@@ -55,6 +55,14 @@ it is started up is as follows:
 
 @enumerate
 @item
+It adds subdirectories to @code{load-path}, by running the file
+named @file{subdirs.el} in each directory that is listed.
+
+@item
+It sets the language environment and the terminal coding system,
+if requested by environment variables such as @code{LANG}.
+
+@item
 It loads the initialization library for the window system, if you are
 using a window system.  This library's name is
 @file{term/@var{windowsystem}-win.el}.
@@ -76,10 +84,9 @@ It loads the library @file{site-start}, unless the option
 @cindex @file{site-start.el}
 
 @item 
-It loads the file @file{~/.emacs}, unless @samp{-q} was specified on the
-command line.  (This is not done in @samp{-batch} mode.)  The @samp{-u}
-option can specify another user name whose home directory should be used
-instead of @file{~}.
+It loads the file @file{~/.emacs}, unless @samp{-q} or @samp{-batch} was
+specified on the command line.  The @samp{-u} option can specify another
+user name whose home directory should be used instead of @file{~}.
 
 @item 
 It loads the library @file{default}, unless @code{inhibit-default-init}
@@ -146,10 +153,11 @@ form to your @file{.emacs} file:
       "@var{your-login-name}")
 @end example
 
-Simply setting @code{inhibit-startup-echo-area-message} to your login
-name is not sufficient to inhibit the message; Emacs explicitly checks
-whether @file{.emacs} contains an expression as shown above.  Your login
-name must appear in the expression as a Lisp string constant.
+Emacs explicitly checks for an expression as shown above in your
+@file{.emacs} file; your login name must appear in the expression as a
+Lisp string constant.  Other methods of setting
+@code{inhibit-startup-echo-area-message} to the same value do not
+inhibit the startup message.
 
 This way, you can easily inhibit the message for yourself if you wish,
 but thoughtless copying of your @file{.emacs} file will not inhibit the
@@ -206,9 +214,14 @@ then the default library is not loaded.  The default value is
 @end defopt
 
 @defvar before-init-hook
-@defvarx after-init-hook
-These two normal hooks are run just before, and just after, loading of
-the user's init file, @file{default.el}, and/or @file{site-start.el}.
+This normal hook is run, once, just before loading of all the init files
+(the user's init file, @file{default.el}, and/or @file{site-start.el}).
+@end defvar
+
+@defvar after-init-hook
+This normal hook is run, once, just after loading of all the init files
+(the user's init file, @file{default.el}, and/or @file{site-start.el}),
+before the terminal-specific initialization.
 @end defvar
 
 @node Terminal-Specific
@@ -216,18 +229,12 @@ the user's init file, @file{default.el}, and/or @file{site-start.el}.
 @cindex terminal-specific initialization
 
   Each terminal type can have its own Lisp library that Emacs loads when
-run on that type of terminal.  For a terminal type named @var{termtype},
-the library is called @file{term/@var{termtype}}.  Emacs finds the file
-by searching the @code{load-path} directories as it does for other
-files, and trying the @samp{.elc} and @samp{.el} suffixes.  Normally,
-terminal-specific Lisp library is located in @file{emacs/lisp/term}, a
-subdirectory of the @file{emacs/lisp} directory in which most Emacs Lisp
-libraries are kept.@refill
-
-  The library's name is constructed by concatenating the value of the
-variable @code{term-file-prefix} and the terminal type.  Normally,
-@code{term-file-prefix} has the value @code{"term/"}; changing this
-is not recommended.
+run on that type of terminal.  The library's name is constructed by
+concatenating the value of the variable @code{term-file-prefix} and the
+terminal type.  Normally, @code{term-file-prefix} has the value
+@code{"term/"}; changing this is not recommended.  Emacs finds the file
+in the normal manner, by searching the @code{load-path} directories, and
+trying the @samp{.elc} and @samp{.el} suffixes.
 
   The usual function of a terminal-specific library is to enable special
 keys to send sequences that Emacs can recognize.  It may also need to
@@ -620,7 +627,7 @@ systems.
 This function returns the name of the machine you are running on.
 @example
 (system-name)
-     @result{} "prep.ai.mit.edu"
+     @result{} "www.gnu.org"
 @end example
 @end defun
 
@@ -719,19 +726,24 @@ locations, but can find them in a directory related somehow to the one
 containing the Emacs executable.
 @end defvar
 
-@defun load-average
+@defun load-average &optional use-float
 This function returns the current 1-minute, 5-minute and 15-minute load
-averages in a list.  The values are integers that are 100 times the
-system load averages, which indicate the average number of processes
-trying to run.  It would be more logical to use floating point numbers,
-but this function was introduced before Emacs supported floating point
-numbers, and it is not worth changing it now.
+averages in a list.
+
+By default, the values are integers that are 100 times the system load
+averages, which indicate the average number of processes trying to run.
+If @var{use-float} is non-@code{nil}, then they are returned
+as floating point numbers instead.
 
 @example
 @group
 (load-average)
      @result{} (169 48 36)
 @end group
+@group
+(load-average t)
+     @result{} (1.69 0.48 0.36)
+@end group
 
 @group
 lewis@@rocky[5] % uptime
@@ -745,8 +757,8 @@ lewis@@rocky[5] % uptime
 This function returns the process @sc{id} of the Emacs process.
 @end defun
 
-@tindex tty-erase-char
 @defvar tty-erase-char
+@tindex tty-erase-char
 This variable holds the erase character that was selected
 in the system's terminal driver, before Emacs was started.
 @end defvar
@@ -859,7 +871,7 @@ This function returns the effective @sc{uid} of the user.
 zone.
 
 @defun current-time-string &optional time-value
-This function returns the current time and date as a humanly-readable
+This function returns the current time and date as a human-readable
 string.  The format of the string is unvarying; the number of characters
 used for each part is always the same, so you can reliably use
 @code{substring} to extract pieces of it.  It is wise to count the
@@ -1027,7 +1039,8 @@ This stands for the time zone abbreviation.
 You can also specify the field width and type of padding for any of
 these @samp{%}-sequences.  This works as in @code{printf}: you write
 the field width as digits in the middle of a @samp{%}-sequences.  If you
-start the field width with 0, it means to pad with zeros.
+start the field width with @samp{0}, it means to pad with zeros.  If you
+start the field width with @samp{_}, it means to pad with spaces.
 
 For example, @samp{%S} specifies the number of seconds since the minute;
 @samp{%03S} means to pad this with zeros to 3 positions, @samp{%_3S} to
@@ -1101,6 +1114,9 @@ feature makes it possible to use the elements of a list returned by
 You can perform simple date arithmetic by using out-of-range values for
 the @var{sec}, @var{minute}, @var{hour}, @var{day}, and @var{month}
 arguments; for example, day 0 means the day preceding the given month.
+
+The operating system puts limits on the range of possible time values;
+if you try to encode a time that is out of range, an error results.
 @end defun
 
 @node Timers
@@ -1124,10 +1140,18 @@ later, and @var{args} are the arguments to give it when it is called.
 The time @var{time} is specified as a string.
 
 Absolute times may be specified in a wide variety of formats, and tries
-to accept all common date formats.  One valid format is
-@samp{@var{hour}:@var{min}:@var{sec} @var{timezone}
-@var{month}/@var{day}/@var{year}}, where all fields are numbers; the
-format that @code{current-time-string} returns is also allowed.
+to accept all common date formats.  Valid formats include these two,
+
+@example
+@var{year}-@var{month}-@var{day} @var{hour}:@var{min}:@var{sec} @var{timezone}
+
+@var{hour}:@var{min}:@var{sec} @var{timezone} @var{month}/@var{day}/@var{year}
+@end example
+
+@noindent
+where in both examples all fields are numbers; the format that
+@code{current-time-string} returns is also allowed, and many others
+as well.
 
 To specify a relative time, use numbers followed by units.
 For example:
@@ -1168,7 +1192,7 @@ the value of the last form in @var{body}.  If, however, the execution of
 executes all the @var{timeout-forms} and returns the value of the last
 of them.
 
-This macro works by set a timer to run after @var{seconds} seconds.  If
+This macro works by setting a timer to run after @var{seconds} seconds.  If
 @var{body} finishes before that time, it cancels the timer.  If the
 timer actually runs, it terminates execution of @var{body}, then
 executes @var{timeout-forms}.
@@ -1290,8 +1314,8 @@ is non-@code{nil} when Emacs is using interrupt-driven input.  If
 @code{nil}, Emacs is using @sc{cbreak} mode.
 @item flow
 is non-@code{nil} if Emacs uses @sc{xon/xoff} (@kbd{C-q}, @kbd{C-s})
-flow control for output to the terminal.  This value has effect when
-unless @var{interrupt} is @code{nil}.
+flow control for output to the terminal.  This value is meaningful only
+when @var{interrupt} is @code{nil}.
 @item meta
 is @code{t} if Emacs treats the eighth bit of input characters as
 the meta bit; @code{nil} means Emacs clears the eighth bit of every
@@ -1365,7 +1389,7 @@ versa.  (@xref{Flow Control} for more information on this subject.)
 @end group
 @group
   (setq keyboard-translate-table
-        (make-char-table 'keyboard-translate-table nil)))
+        (make-char-table 'keyboard-translate-table nil))
 @end group
 @group
   ;; @r{Swap @kbd{C-s} and @kbd{C-\}.}
diff --git a/lispref/positions.texi b/lispref/positions.texi
index a414abb5dc7..e4f9a4cc7b8 100644
--- a/lispref/positions.texi
+++ b/lispref/positions.texi
@@ -180,10 +180,13 @@ whether a given character is part of a word.  @xref{Syntax Tables}.
 
 @deffn Command forward-word count
 This function moves point forward @var{count} words (or backward if
-@var{count} is negative).  Normally it returns @code{t}.  If this motion
-encounters the beginning or end of the buffer, or the limits of the
-accessible portion when narrowing is in effect, point stops there
-and the value is @code{nil}.
+@var{count} is negative).  More precisely, it keeps moving until it
+moves across a word-constituent character and encounters a
+word-separator character, then returns @code{t}.
+
+If this motion encounters the beginning or end of the buffer, or the
+limits of the accessible portion when narrowing is in effect, point
+stops there and the value is @code{nil}.
 
 In an interactive call, @var{count} is set to the numeric prefix
 argument.
@@ -450,7 +453,7 @@ Display}.
   These functions scan text to determine where screen lines break, and
 thus take time proportional to the distance scanned.  If you intend to
 use them heavily, Emacs provides caches which may improve the
-performance of your code.  @xref{Text Lines, cache-long-line-scans}.
+performance of your code.  @xref{Truncation, cache-long-line-scans}.
 
 
 @defun vertical-motion count &optional window
@@ -507,7 +510,7 @@ normally, use @code{(window-width @var{window})}.
 The argument @var{offsets} is either @code{nil} or a cons cell of the
 form @code{(@var{hscroll} . @var{tab-offset})}.  Here @var{hscroll} is
 the number of columns not being displayed at the left margin; most
-callers get this from @code{window-hscroll}.  Meanwhile,
+callers get this by calling @code{window-hscroll}.  Meanwhile,
 @var{tab-offset} is the offset between column numbers on the screen and
 column numbers in the buffer.  This can be nonzero in a continuation
 line, when the previous screen lines' widths do not add up to a multiple
@@ -725,7 +728,7 @@ an abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}).
 
 The @code{save-excursion} special form is the standard way to switch
 buffers or move point within one part of a program and avoid affecting
-the rest of the program.  It is used more than 500 times in the Lisp
+the rest of the program.  It is used more than 4000 times in the Lisp
 sources of Emacs.
 
 @code{save-excursion} does not save the values of point and the mark for
@@ -759,6 +762,11 @@ The value returned by @code{save-excursion} is the result of the last of
 @end example
 @end defspec
 
+  @strong{Warning:} Ordinary insertion of text adjacent to the saved
+point value relocates the saved value, just as it relocates all markers.
+Therefore, when the saved point value is restored, it normally comes
+after the inserted text.
+
   Although @code{save-excursion} saves the location of the mark, it does
 not prevent functions which modify the buffer from setting
 @code{deactivate-mark}, and thus causing the deactivation of the mark
@@ -857,7 +865,7 @@ of inaccessible text before and after the accessible portion.
 
 This method yields correct results if @var{body} does further narrowing.
 However, @code{save-restriction} can become confused if the body widens
-and then make changes outside the range of the saved narrowing.  When
+and then makes changes outside the range of the saved narrowing.  When
 this is what you want to do, @code{save-restriction} is not the right
 tool for the job.  Here is what you must use instead:
 
diff --git a/lispref/processes.texi b/lispref/processes.texi
index 94b8e61bdf3..8589348b282 100644
--- a/lispref/processes.texi
+++ b/lispref/processes.texi
@@ -34,6 +34,7 @@ This function returns @code{t} if @var{object} is a process,
 
 @menu
 * Subprocess Creation::      Functions that start subprocesses.
+* Shell Arguments::          Quoting an argument to pass it to a shell.
 * Synchronous Processes::    Details of using synchronous subprocesses.
 * Asynchronous Processes::   Starting up an asynchronous subprocess.
 * Deleting Processes::       Eliminating an asynchronous subprocess.
@@ -190,8 +191,6 @@ process terminated.
 coding system, much like text read from a file.  The input sent to a
 subprocess by @code{call-process-region} is encoded using a coding
 system, much like text written into a file.  @xref{Coding Systems}.
-On Microsoft operating systems, additional variables control
-the conversion for end-of-line (@pxref{MS-DOS Subprocesses}).
 
 @defun call-process program &optional infile destination display &rest args
 This function calls @var{program} in a separate process and waits for
@@ -240,9 +239,14 @@ buffer.
 @end table
 
 If @var{display} is non-@code{nil}, then @code{call-process} redisplays
-the buffer as output is inserted.  Otherwise the function does no
-redisplay, and the results become visible on the screen only when Emacs
-redisplays that buffer in the normal course of events.
+the buffer as output is inserted.  (However, if the coding system chosen
+for decoding output is @code{undecided}, meaning deduce the encoding
+from the actual data, then redisplay sometimes cannot continue once
+non-@sc{ASCII} characters are encountered.  There are fundamental
+reasons why it is hard to fix this.)  Otherwise the function
+@code{call-process} does no redisplay, and the results become visible on
+the screen only when Emacs redisplays that buffer in the normal course
+of events.
 
 The remaining arguments, @var{args}, are strings that specify command
 line arguments for the program.
@@ -351,8 +355,8 @@ inputinput@point{}
 @end smallexample
 @end defun
 
-@tindex shell-command-to-string
 @defun shell-command-to-string command
+@tindex shell-command-to-string
 This function executes @var{command} (a string) as a shell command,
 then returns the command's output as a string.
 @end defun
@@ -362,10 +366,15 @@ then returns the command's output as a string.
 @cindex asynchronous subprocess
 
   After an @dfn{asynchronous process} is created, Emacs and the Lisp
-program both continue running immediately.  The process may thereafter
-run in parallel with Emacs, and the two may communicate with each other
-using the functions described in following sections.  Here we describe
-how to create an asynchronous process with @code{start-process}.
+program both continue running immediately.  The process thereafter runs
+in parallel with Emacs, and the two can communicate with each other
+using the functions described in following sections.  However,
+communication is only partially asynchronous: Emacs sends data to the
+process only when certain functions are called, and Emacs accepts data
+from the process only when Emacs is waiting for input or for a time
+delay.
+
+  Here we describe how to create an asynchronous process.
 
 @defun start-process name buffer-or-name program &rest args
 This function creates a new asynchronous subprocess and starts the
@@ -570,8 +579,8 @@ process is started and remains constant as long as the process exists.
 This function returns the name of @var{process}.
 @end defun
 
-@tindex process-contact
 @defun process-contact process
+@tindex process-contact
 This function returns @code{t} for an ordinary child process, and
 @code{(@var{hostname} @var{service})} for a net connection
 (@pxref{Network}).
@@ -639,8 +648,8 @@ instead of a terminal (see @code{process-connection-type} in
 @ref{Asynchronous Processes}).
 @end defun
 
-@tindex process-coding-system
 @defun process-coding-system process
+@tindex process-coding-system
 This function returns a cons cell describing the coding systems in use
 for decoding output from @var{process} and for encoding input to
 @var{process} (@pxref{Coding Systems}).  The value has this form:
@@ -650,8 +659,8 @@ for decoding output from @var{process} and for encoding input to
 @end example
 @end defun
 
-@tindex set-process-coding-system
 @defun set-process-coding-system process decoding-system encoding-system
+@tindex set-process-coding-system
 This function specifies the coding systems to use for subsequent output
 from and input to @var{process}.  It will use @var{decoding-system} to
 decode subprocess output, and @var{encoding-system} to encode subprocess
@@ -673,8 +682,11 @@ the other characters, to force them through.  For most programs,
 these @sc{eof}s do no harm.
 
   Subprocess input is normally encoded using a coding system before the
-subprocess receives it, much like text written into a file.
-@xref{Coding Systems}.
+subprocess receives it, much like text written into a file.  You can use
+@code{set-process-coding-system} to specify which coding system to use
+(@pxref{Process Information}).  Otherwise, the coding system comes from
+@code{coding-system-for-write}, if that is non-@code{nil}; or else from
+the defaulting mechanism (@pxref{Default Coding Systems}).
 
 @defun process-send-string process-name string
 This function sends @var{process-name} the contents of @var{string} as
@@ -838,9 +850,32 @@ called the @dfn{filter function} can be called to act on the output.  If
 the process has no buffer and no filter function, its output is
 discarded.
 
+  Output from a subprocess can arrive only while Emacs is waiting: when
+reading terminal input, in @code{sit-for} and @code{sleep-for}
+(@pxref{Waiting}), and in @code{accept-process-output} (@pxref{Accepting
+Output}).  This minimizes the problem of timing errors that usually
+plague parallel programming.  For example, you can safely create a
+process and only then specify its buffer or filter function; no output
+can arrive before you finish, if the code in between does not call any
+primitive that waits.
+
   Subprocess output is normally decoded using a coding system before the
 buffer or filter function receives it, much like text read from a file.
-@xref{Coding Systems}.
+You can use @code{set-process-coding-system} to specify which coding
+system to use (@pxref{Process Information}).  Otherwise, the coding
+system comes from @code{coding-system-for-read}, if that is
+non-@code{nil}; or else from the defaulting mechanism (@pxref{Default
+Coding Systems}).
+
+  @strong{Warning:} Coding systems such as @code{undecided} which
+determine the coding system from the data do not work entirely reliably
+with asynchronous subprocess output.  This is because Emacs has to
+process asynchronous subprocess output in batches, as it arrives.  Emacs
+must try to detect the proper coding system from one batch at a time,
+and this does not always work.  Therefore, if at all possible, use a
+coding system which determines both the character code conversion and
+the end of line conversion---that is, one like @code{latin-1-unix},
+rather than @code{undecided} or @code{latin-1}.
 
 @menu
 * Process Buffers::       If no filter, output is put in a buffer.
@@ -934,19 +969,16 @@ then @emph{all} output from that process is passed to the filter.  The
 process buffer is used directly for output from the process only when
 there is no filter.
 
+  The filter function can only be called when Emacs is waiting for
+something, because process output arrives only at such times.  Emacs
+waits when reading terminal input, in @code{sit-for} and
+@code{sleep-for} (@pxref{Waiting}), and in @code{accept-process-output}
+(@pxref{Accepting Output}).
+
   A filter function must accept two arguments: the associated process
 and a string, which is output just received from it.  The function is
 then free to do whatever it chooses with the output.
 
-  A filter function runs only while Emacs is waiting (e.g., for terminal
-input, or for time to elapse, or for process output).  This avoids the
-timing errors that could result from running filters at random places in
-the middle of other Lisp programs.  You may explicitly cause Emacs to
-wait, so that filter functions will run, by calling @code{sit-for} or
-@code{sleep-for} (@pxref{Waiting}), or @code{accept-process-output}
-(@pxref{Accepting Output}).  Emacs is also waiting when the command loop
-is reading input.
-
   Quitting is normally inhibited within a filter function---otherwise,
 the effect of typing @kbd{C-g} at command level or to quit a user
 command would be unpredictable.  If you want to permit quitting inside a
@@ -1161,7 +1193,8 @@ errors that could result from running them at random places in the
 middle of other Lisp programs.  A program can wait, so that sentinels
 will run, by calling @code{sit-for} or @code{sleep-for}
 (@pxref{Waiting}), or @code{accept-process-output} (@pxref{Accepting
-Output}).  Emacs is also waiting when the command loop is reading input.
+Output}).  Emacs also allows sentinels to run when the command loop is
+reading input.
 
   Quitting is normally inhibited within a sentinel---otherwise, the
 effect of typing @kbd{C-g} at command level or to quit a user command
diff --git a/lispref/searching.texi b/lispref/searching.texi
index 336865c5642..7ba8a9fe666 100644
--- a/lispref/searching.texi
+++ b/lispref/searching.texi
@@ -231,11 +231,12 @@ this choice, the rest of the regexp matches successfully.@refill
 
 Nested repetition operators can be extremely slow if they specify
 backtracking loops.  For example, it could take hours for the regular
-expression @samp{\(x+y*\)*a} to match the sequence
-@samp{xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz}.  The slowness is because
-Emacs must try each imaginable way of grouping the 35 @samp{x}'s before
-concluding that none of them can work.  To make sure your regular
-expressions run fast, check nested repetitions carefully.
+expression @samp{\(x+y*\)*a} to try to match the sequence
+@samp{xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz}, before it ultimately fails.
+The slowness is because Emacs must try each imaginable way of grouping
+the 35 @samp{x}'s before concluding that none of them can work.  To make
+sure your regular expressions run fast, check nested repetitions
+carefully.
 
 @item @samp{+}
 @cindex @samp{+} in regexp
@@ -281,7 +282,7 @@ representations, because only the @sc{ASCII} characters are excluded.
 The beginning and end of a range must be in the same character set
 (@pxref{Character Sets}).  Thus, @samp{[a-\x8c0]} is invalid because
 @samp{a} is in the @sc{ASCII} character set but the character 0x8c0
-(@samp{a} with grave accent) is in the Latin-1 character set.
+(@samp{A} with grave accent) is in the Emacs character set for Latin-1.
 
 Note that the usual regexp special characters are not special inside a
 character alternative.  A completely different set of characters are
@@ -354,11 +355,11 @@ ordinary since there is no preceding expression on which the @samp{*}
 can act.  It is poor practice to depend on this behavior; quote the
 special character anyway, regardless of where it appears.@refill
 
-For the most part, @samp{\} followed by any character matches only
-that character.  However, there are several exceptions: two-character
-sequences starting with @samp{\} which have special meanings.  The
-second character in the sequence is always an ordinary character on
-their own.  Here is a table of @samp{\} constructs.
+For the most part, @samp{\} followed by any character matches only that
+character.  However, there are several exceptions: two-character
+sequences starting with @samp{\} which have special meanings.  (The
+second character in such a sequence is always ordinary when used on its
+own.)  Here is a table of @samp{\} constructs.
 
 @table @samp
 @item \|
@@ -393,8 +394,8 @@ or @samp{barx}.
 @item
 To enclose a complicated expression for the postfix operators @samp{*},
 @samp{+} and @samp{?} to operate on.  Thus, @samp{ba\(na\)*} matches
-@samp{bananana}, etc., with any (zero or more) number of @samp{na}
-strings.@refill
+@samp{ba}, @samp{bana}, @samp{banana}, @samp{bananana}, etc., with any
+number (zero or more) of @samp{na} strings.
 
 @item
 To record a matched substring for future reference.
@@ -530,8 +531,8 @@ whitespace:
 @end example
 @end defun
 
-@tindex regexp-opt
 @defun regexp-opt strings &optional paren
+@tindex regexp-opt
 This function returns an efficient regular expression that will match
 any of the strings @var{strings}.  This is useful when you need to make
 matching or searching as fast as possible---for example, for Font Lock
@@ -555,8 +556,8 @@ regular expression which is equivalent to the actual value
 @end example
 @end defun
 
-@tindex regexp-opt-depth
 @defun regexp-opt-depth regexp
+@tindex regexp-opt-depth
 This function returns the total number of grouping constructs
 (parenthesized expressions) in @var{regexp}.
 @end defun
@@ -1091,6 +1092,10 @@ subexpression is numbered 1, the second 2, and so on.  Only regular
 expressions can have subexpressions---after a simple string search, the
 only information available is about the entire match.
 
+  A search which fails may or may not alter the match data.  In the
+past, a failing search did not do this, but we may change it in the
+future.
+
 @defun match-string count &optional in-string
 This function returns, as a string, the text matched in the last search
 or match operation.  It returns the entire text if @var{count} is zero,
diff --git a/lispref/sequences.texi b/lispref/sequences.texi
index 8f19d6f9a1b..26263831d1c 100644
--- a/lispref/sequences.texi
+++ b/lispref/sequences.texi
@@ -82,7 +82,7 @@ This function returns the number of elements in @var{sequence}.  If
 @sc{cdr} is not @code{nil}), a @code{wrong-type-argument} error is
 signaled.
 
-@xref{List Elements}, for the related function @code{safe-list}.
+@xref{List Elements}, for the related function @code{safe-length}.
 
 @example
 @group
@@ -132,11 +132,11 @@ otherwise, they trigger an @code{args-out-of-range} error.
 @end group
 @group
 (elt [1 2 3 4] 4)
-     @error{}Args out of range: [1 2 3 4], 4
+     @error{} Args out of range: [1 2 3 4], 4
 @end group
 @group
 (elt [1 2 3 4] -1)
-     @error{}Args out of range: [1 2 3 4], -1
+     @error{} Args out of range: [1 2 3 4], -1
 @end group
 @end example
 
@@ -218,12 +218,12 @@ be accessed in constant time.  In contrast, an element of a list
 requires access time that is proportional to the position of the element
 in the list.
 
-  Emacs defines four types of array, both of which are one-dimensional:
-@dfn{strings}, @dfn{vectors}, @dfn{bool-vectors} and @dfn{char-tables}.
-A vector is a general array; its elements can be any Lisp objects.  A
-string is a specialized array; its elements must be characters (i.e.,
-integers between 0 and 255).  Each type of array has its own read
-syntax.  @xref{String Type}, and @ref{Vector Type}.
+  Emacs defines four types of array, all one-dimensional: @dfn{strings},
+@dfn{vectors}, @dfn{bool-vectors} and @dfn{char-tables}.  A vector is a
+general array; its elements can be any Lisp objects.  A string is a
+specialized array; its elements must be characters (i.e., integers
+between 0 and 255).  Each type of array has its own read syntax.
+@xref{String Type}, and @ref{Vector Type}.
 
   All four kinds of array share these characteristics:
 
@@ -347,8 +347,8 @@ If @var{array} is a string and @var{object} is not a character, a
 @code{wrong-type-argument} error results.  If @var{array} is a string
 and @var{object} is character, but @var{object} does not use the same
 number of bytes as the character currently stored in @code{(aref
-@var{object} @var{index})}, that is also an error.  @xref{Chars and
-Bytes}.
+@var{object} @var{index})}, that is also an error.  @xref{Splitting
+Characters}.
 @end defun
 
 @defun fillarray array object
@@ -520,19 +520,25 @@ list with the same elements (@pxref{Building Lists}):
 @node Char-Tables
 @section Char-Tables
 @cindex char-tables
+@cindex extra slots of char-table
 
   A char-table is much like a vector, except that it is indexed by
 character codes.  Any valid character code, without modifiers, can be
 used as an index in a char-table.  You can access a char-table's
-elements with @code{aref} and @code{aset}, as with any array.
-Char-tables are constants when evaluated.
+elements with @code{aref} and @code{aset}, as with any array.  In
+addition, a char-table can have @dfn{extra slots} to hold additional
+data not associated with particular character codes.  Char-tables are
+constants when evaluated.
 
-@cindex extra slots of char-table
 @cindex subtype of char-table
-  Each char-table has a @dfn{subtype} which is a symbol.  In order to be
-a valid subtype, a symbol must have a @code{char-table-extra-slots}
-property which is an integer between 0 and 10.  This integer specifies
-the number of @dfn{extra slots} in the char-table.
+  Each char-table has a @dfn{subtype} which is a symbol.  The subtype
+has two purposes: to distinguish char-tables meant for different uses,
+and to control the number of extra slots.  For example, display tables
+are char-tables with @code{display-table} as the subtype, and syntax
+tables are char-tables with @code{syntax-table} as the subtype.  A valid
+subtype must have a @code{char-table-extra-slots} property which is an
+integer between 0 and 10.  This integer specifies the number of
+@dfn{extra slots} in the char-table.
 
 @cindex parent of char-table
   A char-table can have a @dfn{parent}. which is another char-table.  If
@@ -547,8 +553,8 @@ specifies @code{nil}.
 @code{(aref @var{char-table} @var{c})} returns the default value
 whenever the char-table does not specify any other non-@code{nil} value.
 
-@tindex make-char-table
 @defun make-char-table subtype &optional init
+@tindex make-char-table
 Return a newly created char-table, with subtype @var{subtype}.  Each
 element is initialized to @var{init}, which defaults to @code{nil}.  You
 cannot alter the subtype of a char-table after the char-table is
@@ -558,19 +564,19 @@ There is no argument to specify the length of the char-table, because
 all char-tables have room for any valid character code as an index.
 @end defun
 
-@tindex char-table-p
 @defun char-table-p object
+@tindex char-table-p
 This function returns @code{t} if @var{object} is a char-table,
 otherwise @code{nil}.
 @end defun
 
-@tindex char-table-subtype
 @defun char-table-subtype char-table
+@tindex char-table-subtype
 This function returns the subtype symbol of @var{char-table}.
 @end defun
 
-@tindex set-char-table-default
 @defun set-char-table-default char-table new-default
+@tindex set-char-table-default
 This function sets the default value of @var{char-table} to
 @var{new-default}.
 
@@ -578,26 +584,26 @@ There is no special function to access the default value of a char-table.
 To do that, use @code{(char-table-range @var{char-table} nil)}.
 @end defun
 
-@tindex char-table-parent
 @defun char-table-parent char-table
+@tindex char-table-parent
 This function returns the parent of @var{char-table}.  The parent is
 always either @code{nil} or another char-table.
 @end defun
 
-@tindex set-char-table-parent
 @defun set-char-table-parent char-table new-parent
+@tindex set-char-table-parent
 This function sets the parent of @var{char-table} to @var{new-parent}.
 @end defun
 
-@tindex char-table-extra-slot
 @defun char-table-extra-slot char-table n
+@tindex char-table-extra-slot
 This function returns the contents of extra slot @var{n} of
 @var{char-table}.  The number of extra slots in a char-table is
 determined by its subtype.
 @end defun
 
-@tindex set-char-table-extra-slot
 @defun set-char-table-extra-slot char-table n value
+@tindex set-char-table-extra-slot
 This function stores @var{value} in extra slot @var{n} of
 @var{char-table}.
 @end defun
@@ -605,28 +611,34 @@ This function stores @var{value} in extra slot @var{n} of
   A char-table can specify an element value for a single character code;
 it can also specify a value for an entire character set.
 
-@tindex char-table-range
 @defun char-table-range char-table range
+@tindex char-table-range
 This returns the value specified in @var{char-table} for a range of
-characters @var{range}.  Here @var{range} may be
+characters @var{range}.  Here are the possibilities for @var{range}:
 
 @table @asis
 @item @code{nil}
 Refers to the default value.
 
 @item @var{char}
-Refers to the element for character @var{char}.
+Refers to the element for character @var{char}
+(supposing @var{char} is a valid character code).
 
 @item @var{charset}
 Refers to the value specified for the whole character set
 @var{charset} (@pxref{Character Sets}).
+
+@item @var{generic-char}
+A generic character stands for a character set; specifying the generic
+character as argument is equivalent to specifying the character set
+name.  @xref{Splitting Characters}, for a description of generic characters.
 @end table
 @end defun
 
-@tindex set-char-table-range
 @defun set-char-table-range char-table range value
+@tindex set-char-table-range
 This function set the value in @var{char-table} for a range of
-characters @var{range}.  Here @var{range} may be
+characters @var{range}.  Here are the possibilities for @var{range}:
 
 @table @asis
 @item @code{nil}
@@ -636,24 +648,45 @@ Refers to the default value.
 Refers to the whole range of character codes.
 
 @item @var{char}
-Refers to the element for character @var{char}.
+Refers to the element for character @var{char}
+(supposing @var{char} is a valid character code).
 
 @item @var{charset}
 Refers to the value specified for the whole character set
 @var{charset} (@pxref{Character Sets}).
+
+@item @var{generic-char}
+A generic character stands for a character set; specifying the generic
+character as argument is equivalent to specifying the character set
+name.  @xref{Splitting Characters}, for a description of generic characters.
 @end table
 @end defun
 
-@tindex map-char-table
 @defun map-char-table function char-table
+@tindex map-char-table
 This function calls @var{function} for each element of @var{char-table}.
 @var{function} is called with two arguments, a key and a value.  The key
-is a possible @var{range} argument for @code{char-table-range}, and the
-value is @code{(char-table-range @var{char-table} @var{key})}.  Invalid
-character codes are never used as @var{key}.
+is a possible @var{range} argument for @code{char-table-range}---either
+a valid character or a generic character---and the value is
+@code{(char-table-range @var{char-table} @var{key})}.
 
 Overall, the key-value pairs passed to @var{function} describe all the
 values stored in @var{char-table}.
+
+The return value is always @code{nil}; to make this function useful,
+@var{function} should have side effects.  For example,
+here is how to examine each element of the syntax table:
+
+@example
+(map-char-table
+ #'(lambda (key value)
+     (setq accumulator
+           (cons (list key value) accumulator)))
+ (syntax-table))
+@result{}
+((475008 nil) (474880 nil) (474752 nil) (474624 nil)
+ ... (5 (3)) (4 (3)) (3 (3)) (2 (3)) (1 (3)) (0 (3)))
+@end example
 @end defun
 
 @node Bool-Vectors
@@ -671,13 +704,14 @@ Bool-vectors are constants when evaluated.
 from that, you manipulate them with same functions used for other kinds
 of arrays.
 
-@tindex make-bool-vector
 @defun make-bool-vector length initial
+@tindex make-bool-vector
 Return a new book-vector of @var{length} elements,
 each one initialized to @var{initial}.
 @end defun
 
 @defun bool-vector-p object
+@tindex bool-vector-p
 This returns @code{t} if @var{object} is a bool-vector,
 and @code{nil} otherwise.
 @end defun
diff --git a/lispref/streams.texi b/lispref/streams.texi
index 945e550fc0a..cf3f14a095f 100644
--- a/lispref/streams.texi
+++ b/lispref/streams.texi
@@ -255,7 +255,7 @@ useless-list
 @end example
 
 @noindent
-Note that the open and close parentheses remains in the list.  The Lisp
+Note that the open and close parentheses remain in the list.  The Lisp
 reader encountered the open parenthesis, decided that it ended the
 input, and unread it.  Another attempt to read from the stream at this
 point would read @samp{()} and return @code{nil}.
@@ -353,14 +353,15 @@ Point advances as characters are inserted.
 The output characters are inserted into the buffer that @var{marker}
 points into, at the marker position.  The marker position advances as
 characters are inserted.  The value of point in the buffer has no effect
-on printing when the stream is a marker.
+on printing when the stream is a marker, and this kind of printing
+does not move point.
 
 @item @var{function}
 @cindex function output stream
 The output characters are passed to @var{function}, which is responsible
 for storing them away.  It is called with a single character as
-argument, as many times as there are characters to be output, and is
-free to do anything at all with the characters it receives.
+argument, as many times as there are characters to be output, and
+is responsible for storing the characters wherever you want to put them.
 
 @item @code{t}
 @cindex @code{t} output stream
@@ -368,9 +369,9 @@ The output characters are displayed in the echo area.
 
 @item @code{nil}
 @cindex @code{nil} output stream
-@code{nil} specified as an output stream means to the value of
+@code{nil} specified as an output stream means to use the value of
 @code{standard-output} instead; that value is the @dfn{default output
-stream}, and must be a non-@code{nil} output stream.
+stream}, and must not be @code{nil}.
 
 @item @var{symbol}
 A symbol as output stream is equivalent to the symbol's function
@@ -425,7 +426,7 @@ effect.
 @example
 @group
 ---------- Buffer: foo ----------
-"This is the @point{}output"
+This is the @point{}output
 ---------- Buffer: foo ----------
 @end group
 
@@ -441,9 +442,9 @@ m
 
 @group
 ---------- Buffer: foo ----------
-"This is t
+This is t
 "More output for foo."
-he @point{}output"
+he @point{}output
 ---------- Buffer: foo ----------
 @end group
 
@@ -535,12 +536,13 @@ describe a Lisp object clearly for a Lisp programmer.  However, if the
 purpose of the output is to look nice for humans, then it is usually
 better to print without quoting.
 
-  Printing a self-referent Lisp object in the normal way would require
-an infinite amount of text, and could even result in stack overflow.
-Emacs detects such recursion and prints @samp{#@var{level}} instead of
-recursively printing an object already being printed.  For example, here
-@samp{#0} indicates a recursive reference to the object at level 0 of
-the current print operation:
+  Lisp objects can refer to themselves.  Printing a self-referential
+object in the normal way would require an infinite amount of text, and
+the attempt could cause infinite recursion.  Emacs detects such
+recursion and prints @samp{#@var{level}} instead of recursively printing
+an object already being printed.  For example, here @samp{#0} indicates
+a recursive reference to the object at level 0 of the current print
+operation:
 
 @example
 (setq foo (list nil))
@@ -661,10 +663,10 @@ See @code{format}, in @ref{String Conversion}, for other ways to obtain
 the printed representation of a Lisp object as a string.
 @end defun
 
-@tindex with-output-to-string
 @defmac with-output-to-string body...
-This macro executes the @var{body} forms with standard-output set up so
-that all output feeds into a string.  Then it returns that string.
+@tindex with-output-to-string
+This macro executes the @var{body} forms with @code{standard-output} set
+up to feed output into a string.  Then it returns that string.
 
 For example, if the current buffer name is @samp{foo},
 
diff --git a/lispref/strings.texi b/lispref/strings.texi
index 71300010f37..5e511a5d331 100644
--- a/lispref/strings.texi
+++ b/lispref/strings.texi
@@ -28,7 +28,7 @@ keyboard character events.
 * Modifying Strings::         Altering the contents of an existing string.
 * Text Comparison::           Comparing characters or strings.
 * String Conversion::         Converting characters or strings and vice versa.
-* Formatting Strings::        @code{format}: Emacs's analog of @code{printf}.
+* Formatting Strings::        @code{format}: Emacs's analogue of @code{printf}.
 * Case Conversion::           Case conversion functions.
 * Case Tables::		      Customizing case conversion.
 @end menu
@@ -97,12 +97,12 @@ For more information about general sequence and array predicates,
 see @ref{Sequences Arrays Vectors}, and @ref{Arrays}.
 
 @defun stringp object
-  This function returns @code{t} if @var{object} is a string, @code{nil}
+This function returns @code{t} if @var{object} is a string, @code{nil}
 otherwise.
 @end defun
 
 @defun char-or-string-p object
-  This function returns @code{t} if @var{object} is a string or a
+This function returns @code{t} if @var{object} is a string or a
 character (i.e., an integer), @code{nil} otherwise.
 @end defun
 
@@ -113,7 +113,7 @@ character (i.e., an integer), @code{nil} otherwise.
 putting strings together, or by taking them apart.
 
 @defun make-string count character
-  This function returns a string made up of @var{count} repetitions of
+This function returns a string made up of @var{count} repetitions of
 @var{character}.  If @var{count} is negative, an error is signaled.
 
 @example
@@ -128,8 +128,8 @@ putting strings together, or by taking them apart.
 @code{make-list} (@pxref{Building Lists}).
 @end defun
 
-@tindex string
 @defun string &rest characters
+@tindex string
 This returns a string containing the characters @var{characters}.
 
 @example
@@ -232,7 +232,7 @@ returns an empty string.
 @example
 (concat "abc" "-def")
      @result{} "abc-def"
-(concat "abc" (list 120 (+ 256 121)) [122])
+(concat "abc" (list 120 121) [122])
      @result{} "abcxyz"
 ;; @r{@code{nil} is an empty sequence.}
 (concat "abc" nil "-def")
@@ -244,10 +244,6 @@ returns an empty string.
 @end example
 
 @noindent
-The second example above shows how characters stored in strings are
-taken modulo 256.  In other words, each character in the string is
-stored in one byte.
-
 The @code{concat} function always constructs a new string that is
 not @code{eq} to any existing string.
 
@@ -274,8 +270,8 @@ description of @code{mapconcat} in @ref{Mapping Functions},
 Lists}.
 @end defun
 
-@tindex split-string
 @defun split-string string separators
+@tindex split-string
 Split @var{string} into substrings in between matches for the regular
 expression @var{separators}.  Each match for @var{separators} defines a
 splitting point; the substrings between the splitting points are made
@@ -322,8 +318,8 @@ that index, @code{aset} signals an error.
 
   A more powerful function is @code{store-substring}:
 
-@tindex store-substring
 @defun store-substring string idx obj
+@tindex store-substring
 This function alters part of the contents of the string @var{string}, by
 storing @var{obj} starting at index @var{idx}.  The argument @var{obj}
 may be either a character or a (smaller) string.
@@ -434,6 +430,41 @@ no characters is less than any other string.
 @code{string-lessp} is another name for @code{string<}.
 @end defun
 
+@defun compare-strings string1 start1 end1 string2 start2 end2 &optional ignore-case
+@tindex compare-strings
+This function compares a specified part of @var{string1} with a
+specified part of @var{string2}.  The specified part of @var{string1}
+runs from index @var{start1} up to index @var{end1} (default, the end of
+the string).  The specified part of @var{string2} runs from index
+@var{start2} up to index @var{end2} (default, the end of the string).
+
+The strings are both converted to multibyte for the comparison
+(@pxref{Text Representations}) so that a unibyte string can be usefully
+compared with a multibyte string.  If @var{ignore-case} is
+non-@code{nil}, then case is ignored as well.
+
+If the specified portions of the two strings match, the value is
+@code{t}.  Otherwise, the value is an integer which indicates how many
+leading characters agree, and which string is less.  Its absolute value
+is one plus the number of characters that agree at the beginning of the
+two strings.  The sign is negative if @var{string1} (or its specified
+portion) is less.
+@end defun
+
+@defun assoc-ignore-case key alist
+@tindex assoc-ignore-case
+This function works like @code{assoc}, except that @var{key} must be a
+string, and comparison is done using @code{compare-strings}.
+Case differences are ignored in this comparison.
+@end defun
+
+@defun assoc-ignore-representation key alist
+@tindex assoc-ignore-representation
+This function works like @code{assoc}, except that @var{key} must be a
+string, and comparison is done using @code{compare-strings}.
+Case differences are significant.
+@end defun
+
   See also @code{compare-buffer-substrings} in @ref{Comparing Text}, for
 a way to compare text in buffers.  The function @code{string-match},
 which matches a regular expression against a string, can be used
@@ -509,7 +540,7 @@ negative.
 See also the function @code{format} in @ref{Formatting Strings}.
 @end defun
 
-@defun string-to-number string base
+@defun string-to-number string &optional base
 @cindex string to number
 This function returns the numeric value of the characters in
 @var{string}.  If @var{base} is non-@code{nil}, integers are converted
@@ -522,7 +553,7 @@ The parsing skips spaces and tabs at the beginning of @var{string}, then
 reads as much of @var{string} as it can interpret as a number.  (On some
 systems it ignores other whitespace at the beginning, not just spaces
 and tabs.)  If the first character after the ignored whitespace is not a
-digit or a minus sign, this function returns 0.
+digit or a plus or minus sign, this function returns 0.
 
 @example
 (string-to-number "256")
@@ -600,10 +631,9 @@ second such value, and so on.  Any extra format specifications (those
 for which there are no corresponding values) cause unpredictable
 behavior.  Any extra values to be formatted are ignored.
 
-  Certain format specifications require values of particular types.
-However, no error is signaled if the value actually supplied fails to
-have the expected type.  Instead, the output is likely to be
-meaningless.
+  Certain format specifications require values of particular types.  If
+you supply a value that doesn't fit the requirements, an error is
+signaled.
 
   Here is a table of valid format specifications:
 
@@ -652,7 +682,7 @@ point number.
 
 @item %g
 Replace the specification with notation for a floating point number,
-using either exponential notation or decimal-point notation whichever
+using either exponential notation or decimal-point notation, whichever
 is shorter.
 
 @item %%
@@ -741,10 +771,14 @@ not truncated.  In the third case, the padding is on the right.
 @cindex case conversion in Lisp
 
   The character case functions change the case of single characters or
-of the contents of strings.  The functions convert only alphabetic
-characters (the letters @samp{A} through @samp{Z} and @samp{a} through
-@samp{z}); other characters are not altered.  The functions do not
-modify the strings that are passed to them as arguments.
+of the contents of strings.  The functions normally convert only
+alphabetic characters (the letters @samp{A} through @samp{Z} and
+@samp{a} through @samp{z}, as well as non-ASCII letters); other
+characters are not altered.  (You can specify a different case
+conversion mapping by specifying a case table---@pxref{Case Tables}.)
+
+  These functions do not modify the strings that are passed to them as
+arguments.
 
   The examples below use the characters @samp{X} and @samp{x} which have
 @sc{ASCII} codes 88 and 120 respectively.
@@ -823,8 +857,8 @@ has the same result as @code{upcase}.
 @defun upcase-initials string
 This function capitalizes the initials of the words in @var{string}.
 without altering any letters other than the initials.  It returns a new
-string whose contents are a copy of @var{string-or-char}, in which each
-word has been converted to upper case.
+string whose contents are a copy of @var{string}, in which each word has
+been converted to upper case.
 
 The definition of a word is any sequence of consecutive characters that
 are assigned to the word constituent syntax class in the current syntax
@@ -838,6 +872,9 @@ table (@xref{Syntax Class Table}).
 @end example
 @end defun
 
+  @xref{Text Comparison}, for functions that compare strings; some of
+them ignore case differences, or can optionally ignore case differences.
+
 @node Case Tables
 @section The Case Table
 
@@ -860,10 +897,10 @@ The upcase table maps each character into the corresponding upper
 case character.
 @item canonicalize
 The canonicalize table maps all of a set of case-related characters
-into some one of them.
+into a particular member of that set.
 @item equivalences
-The equivalences table maps each of a set of case-related characters
-into the next one in that set.
+The equivalences table maps each one of a set of case-related characters
+into the next character in that set.
 @end table
 
   In simple cases, all you need to specify is the mapping to lower-case;
diff --git a/lispref/symbols.texi b/lispref/symbols.texi
index 9f52fc0e5be..7e9c6a4a9a6 100644
--- a/lispref/symbols.texi
+++ b/lispref/symbols.texi
@@ -121,12 +121,12 @@ The property list cell contains the list @code{(variable-documentation
 documentation string for the variable @code{buffer-file-name} in the
 @file{DOC-@var{version}} file.  (29529 is the offset from the beginning
 of the @file{DOC-@var{version}} file to where that documentation string
-begins---@pxref{Documentation Basics}) The function cell contains the
-function for returning the name of the file.  @code{buffer-file-name}
-names a primitive function, which has no read syntax and prints in hash
-notation (@pxref{Primitive Function Type}).  A symbol naming a function
-written in Lisp would have a lambda expression (or a byte-code object)
-in this cell.
+begins---see @ref{Documentation Basics}.)  The function cell contains
+the function for returning the name of the file.
+@code{buffer-file-name} names a primitive function, which has no read
+syntax and prints in hash notation (@pxref{Primitive Function Type}).  A
+symbol naming a function written in Lisp would have a lambda expression
+(or a byte-code object) in this cell.
 
 @node Definitions, Creating Symbols, Symbol Components, Symbols
 @section Defining Symbols
diff --git a/lispref/syntax.texi b/lispref/syntax.texi
index 3200c40ac83..b6a5ea9a132 100644
--- a/lispref/syntax.texi
+++ b/lispref/syntax.texi
@@ -10,7 +10,7 @@
 @cindex text parsing
 
   A @dfn{syntax table} specifies the syntactic textual function of each
-character.  This information is used by the parsing commands, the
+character.  This information is used by the @dfn{parsing functions}, the
 complex movement commands, and others to determine where words, symbols,
 and other syntactic constructs begin and end.  The current syntax table
 controls the meaning of the word motion functions (@pxref{Word Motion})
@@ -524,8 +524,8 @@ If the property is @code{nil}, the character's syntax is determined from
 the current syntax table in the usual way.
 @end table
 
-@tindex parse-sexp-lookup-properties
 @defvar parse-sexp-lookup-properties
+@tindex parse-sexp-lookup-properties
 If this is non-@code{nil}, the syntax scanning functions pay attention
 to syntax text properties.  Otherwise they use only the current syntax
 table.
@@ -765,43 +765,50 @@ a character to match was specified.
 to each syntactic type.
 
 @multitable @columnfractions .05 .3 .3 .3
-@item@tab
+@item
+@tab
 @i{Integer} @i{Class}
 @tab
 @i{Integer} @i{Class}
 @tab
 @i{Integer} @i{Class}
-@item@tab
+@item
+@tab
 0 @ @  whitespace
 @tab
 5 @ @  close parenthesis
 @tab
 10 @ @  character quote
-@item@tab
+@item
+@tab
 1 @ @  punctuation
 @tab
 6 @ @  expression prefix
 @tab
 11 @ @  comment-start
-@item@tab
+@item
+@tab
 2 @ @  word
 @tab
 7 @ @  string quote
 @tab
 12 @ @  comment-end
-@item@tab
+@item
+@tab
 3 @ @  symbol
 @tab
 8 @ @  paired delimiter
 @tab
 13 @ @  inherit
-@item@tab
+@item
+@tab
 4 @ @  open parenthesis
 @tab
 9 @ @  escape
 @tab
 14 @ @  comment-fence
-@item@tab
+@item
+@tab
 15 @  string-fence
 @end multitable
 
@@ -813,19 +820,22 @@ least significant bit.  This table gives the power of two which
 corresponds to each syntax flag.
 
 @multitable @columnfractions .05 .3 .3 .3
-@item@tab
+@item
+@tab
 @i{Prefix} @i{Flag}
 @tab
 @i{Prefix} @i{Flag}
 @tab
 @i{Prefix} @i{Flag}
-@item@tab
+@item
+@tab
 @samp{1} @ @  @code{(lsh 1 16)}
 @tab
 @samp{3} @ @  @code{(lsh 1 18)}
 @tab
 @samp{p} @ @  @code{(lsh 1 20)}
-@item@tab
+@item
+@tab
 @samp{2} @ @  @code{(lsh 1 17)}
 @tab
 @samp{4} @ @  @code{(lsh 1 19)}
diff --git a/lispref/text.texi b/lispref/text.texi
index 96b527d23fa..69f0c002293 100644
--- a/lispref/text.texi
+++ b/lispref/text.texi
@@ -196,8 +196,11 @@ properties, just the characters themselves.  @xref{Text Properties}.
 
 @defun buffer-string
 This function returns the contents of the entire accessible portion of
-the current buffer as a string.  This is the portion between
-@code{(point-min)} and @code{(point-max)} (@pxref{Narrowing}).
+the current buffer as a string.  It is equivalent to
+
+@example
+(buffer-substring (point-min) (point-max))
+@end example
 
 @example
 @group
@@ -302,6 +305,13 @@ properties as the characters they were copied from.  By contrast,
 characters specified as separate arguments, not part of a string or
 buffer, inherit their text properties from the neighboring text.
 
+  The insertion functions convert text from unibyte to multibyte in
+order to insert in a multibyte buffer, and vice versa---if the text
+comes from a string or from a buffer.  However, they do not convert
+unibyte character codes 128 through 255 to multibyte characters, not
+even if the current buffer is a multibyte buffer.  @xref{Converting
+Representations}.
+
 @defun insert &rest args
 This function inserts the strings and/or characters @var{args} into the
 current buffer, at point, moving point forward.  In other words, it
@@ -328,6 +338,10 @@ current buffer before point.  The argument @var{count} should be a
 number (@code{nil} means 1), and @var{character} must be a character.
 The value is @code{nil}.
 
+This function does not convert unibyte character codes 128 through 255
+to multibyte characters, not even if the current buffer is a multibyte
+buffer.  @xref{Converting Representations}.
+
 If @var{inherit} is non-@code{nil}, then the inserted characters inherit
 sticky text properties from the two characters before and after the
 insertion point.  @xref{Sticky Properties}.
@@ -524,8 +538,8 @@ the kill ring.
 The value returned is always @code{nil}.
 @end deffn
 
-@tindex backward-delete-char-untabify-method
 @defopt backward-delete-char-untabify-method
+@tindex backward-delete-char-untabify-method
 This option specifies how @code{backward-delete-char-untabify} should
 deal with whitespace.  Possible values include @code{untabify}, the
 default, meaning convert a tab to many spaces and delete one;
@@ -579,7 +593,7 @@ This function joins the line point is on to the previous line, deleting
 any whitespace at the join and in some cases replacing it with one
 space.  If @var{join-following-p} is non-@code{nil},
 @code{delete-indentation} joins this line to the following line
-instead.  The value is @code{nil}.
+instead.  The function returns @code{nil}.
 
 If there is a fill prefix, and the second of the lines being joined
 starts with the prefix, then @code{delete-indentation} deletes the
@@ -612,7 +626,7 @@ responsible for deciding whether to leave a space at the junction.
 @end deffn
 
 @defun fixup-whitespace
-This function replaces all the white space surrounding point with either
+This function replaces all the whitespace surrounding point with either
 one space or no space, according to the context.  It returns @code{nil}.
 
 At the beginning or end of a line, the appropriate amount of space is
@@ -728,9 +742,9 @@ new entry automatically deletes the last entry.
 
   When kill commands are interwoven with other commands, each kill
 command makes a new entry in the kill ring.  Multiple kill commands in
-succession build up a single entry in the kill ring, which would be
-yanked as a unit; the second and subsequent consecutive kill commands
-add text to the entry made by the first one.
+succession build up a single kill-ring entry, which would be yanked as a
+unit; the second and subsequent consecutive kill commands add text to
+the entry made by the first one.
 
   For yanking, one entry in the kill ring is designated the ``front'' of
 the ring.  Some yank commands ``rotate'' the ring by designating a
@@ -825,7 +839,7 @@ The sequence of kills in the kill ring wraps around, so that after the
 oldest one comes the newest one, and before the newest one goes the
 oldest.
 
-The value is always @code{nil}.
+The return value is always @code{nil}.
 @end deffn
 
 @node Low-Level Kill Ring
@@ -837,8 +851,8 @@ take care of interaction with window system selections
 (@pxref{Window System Selections}).
 
 @defun current-kill n &optional do-not-move
-The function @code{current-kill} rotates the yanking pointer which
-designates the ``front'' of the kill ring by @var{n} places (from newer
+The function @code{current-kill} rotates the yanking pointer, which
+designates the ``front'' of the kill ring, by @var{n} places (from newer
 kills to older ones), and returns the text at that place in the ring.
 
 If the optional second argument @var{do-not-move} is non-@code{nil},
@@ -1049,8 +1063,8 @@ not make boundaries, and then the 20th does, and so on as long as
 self-inserting characters continue.
 
 All buffer modifications add a boundary whenever the previous undoable
-change was made in some other buffer.  This way, a command that modifies
-several buffers makes a boundary in each buffer it changes.
+change was made in some other buffer.  This is to ensure that
+each command makes a boundary in each buffer where it makes changes.
 
 Calling this function explicitly is useful for splitting the effects of
 a command into more than one unit.  For example, @code{query-replace}
@@ -1096,8 +1110,8 @@ In an interactive call, @var{buffer-or-name} is the current buffer.
 You cannot specify any other buffer.
 @end deffn
 
-@defun buffer-disable-undo &optional buffer
-@defunx buffer-flush-undo &optional buffer
+@deffn Command buffer-disable-undo &optional buffer
+@deffnx Command buffer-flush-undo &optional buffer
 @cindex disable undo
 This function discards the undo list of @var{buffer}, and disables
 further recording of undo information.  As a result, it is no longer
@@ -1105,11 +1119,11 @@ possible to undo either previous changes or any subsequent changes.  If
 the undo list of @var{buffer} is already disabled, this function
 has no effect.
 
-This function returns @code{nil}.  It cannot be called interactively.
+This function returns @code{nil}.
 
 The name @code{buffer-flush-undo} is not considered obsolete, but the
 preferred name is @code{buffer-disable-undo}.
-@end defun
+@end deffn
 
   As editing continues, undo lists get longer and longer.  To prevent
 them from using up all available memory space, garbage collection trims
@@ -1214,6 +1228,7 @@ filling when @var{justify} is non-@code{nil}.
 
 In an interactive call, any prefix argument requests justification.
 
+@cindex Adaptive Fill mode
 In Adaptive Fill mode, which is enabled by default, calling the function
 @code{fill-region-as-paragraph} on an indented paragraph when there is
 no fill prefix uses the indentation of the second line of the paragraph
@@ -1279,7 +1294,8 @@ newlines'' act as paragraph separators.
 @section Margins for Filling
 
 @defopt fill-prefix
-This variable specifies a string of text that appears at the beginning
+This buffer-local variable specifies a string of text that appears at
+the beginning
 of normal text lines and should be disregarded when filling them.  Any
 line that fails to start with the fill prefix is considered the start of
 a paragraph; so is any line that starts with the fill prefix followed by
@@ -1290,7 +1306,7 @@ together.  The resulting filled lines also start with the fill prefix.
 The fill prefix follows the left margin whitespace, if any.
 @end defopt
 
-@defopt fill-column
+@defvar fill-column
 This buffer-local variable specifies the maximum width of filled lines.
 Its value should be an integer, which is a number of columns.  All the
 filling, justification, and centering commands are affected by this
@@ -1300,7 +1316,7 @@ As a practical matter, if you are writing text for other people to
 read, you should set @code{fill-column} to no more than 70.  Otherwise
 the line will be too long for people to read comfortably, and this can
 make the text seem clumsy.
-@end defopt
+@end defvar
 
 @defvar default-fill-column
 The value of this variable is the default value for @code{fill-column} in
@@ -1367,8 +1383,8 @@ mode, @kbd{C-j} indents to this column.  This variable automatically
 becomes buffer-local when set in any fashion.
 @end defvar
 
-@tindex fill-nobreak-predicate
 @defvar fill-nobreak-predicate
+@tindex fill-nobreak-predicate
 This variable gives major modes a way to specify not to break a line at
 certain places.  Its value should be a function.  This function is
 called during filling, with no arguments and with point located at the
@@ -1787,8 +1803,8 @@ indent the current line in a way appropriate for the current major mode.
 
 @deffn Command indent-for-tab-command
 This command calls the function in @code{indent-line-function} to indent
-the current line; except that if that function is
-@code{indent-to-left-margin}, it calls @code{insert-tab} instead.  (That
+the current line; however, if that function is
+@code{indent-to-left-margin}, @code{insert-tab} is called instead.  (That
 is a trivial command that inserts a tab character.)
 @end deffn
 
@@ -1842,7 +1858,8 @@ by making it start with the fill prefix.
 
 @defvar indent-region-function
 The value of this variable is a function that can be used by
-@code{indent-region} as a short cut.  You should design the function so
+@code{indent-region} as a short cut.  It should take two arguments, the
+start and end of the region.  You should design the function so
 that it will produce the same results as indenting the lines of the
 region one by one, but presumably faster.
 
@@ -2389,16 +2406,16 @@ position less than or equal to @var{pos}; it equals @var{pos} only if
 @var{limit} equals @var{pos}.
 @end defun
 
-@tindex next-char-property-change
 @defun next-char-property-change position &optional limit
+@tindex next-char-property-change
 This is like @code{next-property-change} except that it considers
 overlay properties as well as text properties.  There is no @var{object}
 operand because this function operates only on the current buffer.  It
 returns the next address at which either kind of property changes.
 @end defun
 
-@tindex previous-char-property-change
 @defun previous-char-property-change position &optional limit
+@tindex previous-char-property-change
 This is like @code{next-char-property-change}, but scans back from
 @var{position} instead of forward.
 @end defun
@@ -3160,17 +3177,14 @@ end of the region just changed, and the length of the text that existed
 before the change.  All three arguments are integers.  The buffer that's
 about to change is always the current buffer.
 
-The length of the old text is measured in bytes; it is the difference
-between the buffer positions before and after that text, before the
-change.  As for the changed text, its length in bytes is simply the
-difference between the first two arguments.  If you want the length
-in @emph{characters} of the text before the change, you should use
-a @code{before-change-functions} function that calls @code{chars-in-region}
-(@pxref{Chars and Bytes}).
+The length of the old text the difference between the buffer positions
+before and after that text as it was before the change.  As for the
+changed text, its length is simply the difference between the first two
+arguments.
 @end defvar
 
-@tindex combine-after-change-calls
 @defmac combine-after-change-calls body...
+@tindex combine-after-change-calls
 The macro executes @var{body} normally, but arranges to call the
 after-change functions just once for a series of several changes---if
 that seems safe.
diff --git a/lispref/tips.texi b/lispref/tips.texi
index 11522391a3f..264875768b9 100644
--- a/lispref/tips.texi
+++ b/lispref/tips.texi
@@ -46,7 +46,7 @@ instead.
 If you write a function that you think ought to be added to Emacs under
 a certain name, such as @code{twiddle-files}, don't call it by that name
 in your program.  Call it @code{mylib-twiddle-files} in your program,
-and send mail to @samp{bug-gnu-emacs@@prep.ai.mit.edu} suggesting we add
+and send mail to @samp{bug-gnu-emacs@@gnu.org} suggesting we add
 it to Emacs.  If and when we do, we can change the name easily enough.
 
 If one prefix is insufficient, your package may use two or three
@@ -104,6 +104,8 @@ If a user option variable records a true-or-false condition, give it a
 name that ends in @samp{-flag}.
 
 @item
+@cindex reserved keys
+@cindex keys, reserved
 Please do not define @kbd{C-c @var{letter}} as a key in your major
 modes.  These sequences are reserved for users; they are the
 @strong{only} sequences reserved for users, so do not block them.
@@ -262,7 +264,7 @@ Try to avoid compiler warnings about undefined free variables, by adding
 If you bind a variable in one function, and use it or set it in another
 function, the compiler warns about the latter function unless the
 variable has a definition.  But often these variables have short names,
-and it is not clean for Lisp packages to define such variables names.
+and it is not clean for Lisp packages to define such variable names.
 Therefore, you should rename the variable to start with the name prefix
 used for the other functions and variables in your package.
 
@@ -317,8 +319,10 @@ Lisp programs.
 @cindex profiling
 @cindex timing programs
 @cindex @file{profile.el}
-Use the @file{profile} library to profile your program.  See the file
-@file{profile.el} for instructions.
+@cindex @file{elp.el}
+Profile your program with the @file{profile} library or the @file{elp}
+library.  See the files @file{profile.el} and @file{elp.el} for
+instructions.
 
 @item
 Use iteration rather than recursion whenever possible.
@@ -340,19 +344,13 @@ property.  If the property is non-@code{nil}, then the function is
 handled specially.
 
 For example, the following input will show you that @code{aref} is
-compiled specially (@pxref{Array Functions}) while @code{elt} is not
-(@pxref{Sequence Functions}):
+compiled specially (@pxref{Array Functions}):
 
 @example
 @group
 (get 'aref 'byte-compile)
      @result{} byte-compile-two-args
 @end group
-
-@group
-(get 'elt 'byte-compile)
-     @result{} nil
-@end group
 @end example
 
 @item
@@ -480,14 +478,39 @@ t and nil without single-quotes.  (In this manual, we use a different
 convention, with single-quotes for all symbols.)
 @end ifinfo
 
-For example:
+Help mode automatically creates hyperlinks when documentation strings
+use symbol names inside single quotes, when the symbol has either a
+function or a variable definition.  You do not need to do anything
+special to make use of this feature.  However, when a symbol has both a
+function definition and a variable definition, and you want to refer to
+just one of them, you can specify which one by writing one of the words
+@samp{variable}, @samp{option}, @samp{function}, or @samp{command},
+immediately before the symbol name.  (Case makes no difference in
+recognizing these indicator words.)  For example, if you write
+
+@example
+This function sets the variable `buffer-file-name'.
+@end example
+
+@noindent
+then the hyperlink will refer only to the variable documentation of
+@code{buffer-file-name}, and not to its function documentation.
+
+If a symbol has a function definition and/or a variable definition, but
+those are irrelevant to the use of the symbol that you are documenting,
+you can write the word @samp{symbol} before the symbol name to prevent
+making any hyperlink.  For example,
 
 @example
-The value of `swim-speed' specifies how fast to swim.
-Possible values are t for high speed, nil for low speed,
-and `medium' for medium speed.
+If the argument KIND-OF-RESULT is the symbol `list',
+this function returns a list of all the objects
+that satisfy the criterion.
 @end example
 
+@noindent
+does not make a hyperlink to the documentation, irrelevant here, of the
+function @code{list}.
+
 @item
 Don't write key sequences directly in documentation strings.  Instead,
 use the @samp{\\[@dots{}]} construct to stand for them.  For example,
@@ -692,6 +715,8 @@ example).
 
 @item Keywords
 This line lists keywords for the @code{finder-by-keyword} help command.
+Please use that command to see a list of the meaningful keywords.
+
 This field is important; it's how people will find your package when
 they're looking for things by topic area.  To separate the keywords, you
 can use spaces, commas, or both.
@@ -708,14 +733,21 @@ library file.  Here is a table of them:
 @table @samp
 @item ;;; Commentary:
 This begins introductory comments that explain how the library works.
-It should come right after the copying permissions.
+It should come right after the copying permissions, terminated by a
+@samp{Change Log}, @samp{History} or @samp{Code} comment line.  This
+text is used by the Finder package, so it should make sense in that
+context.
+
+@item ;;; Documentation
+This has been used in some files in place of @samp{;;; Commentary:},
+but @samp{;;; Commentary:} is preferred.
 
-@item ;;; Change log:
+@item ;;; Change Log:
 This begins change log information stored in the library file (if you
 store the change history there).  For most of the Lisp
 files distributed with Emacs, the change history is kept in the file
 @file{ChangeLog} and not in the source file at all; these files do
-not have a @samp{;;; Change log:} line.
+not have a @samp{;;; Change Log:} line.
 
 @item ;;; Code:
 This begins the actual code of the program.
diff --git a/lispref/variables.texi b/lispref/variables.texi
index 4517d6bb02f..1451db07d06 100644
--- a/lispref/variables.texi
+++ b/lispref/variables.texi
@@ -104,7 +104,7 @@ include @code{nil} and @code{t}, as well as any symbol whose name starts
 with @samp{:}.  These symbols cannot be rebound, nor can their values be
 changed.  Any attempt to set or bind @code{nil} or @code{t} signals a
 @code{setting-constant} error.  The same is true for a symbol whose name
-starts with @samp{:}, except that you are allowed to set such symbol to
+starts with @samp{:}, except that you are allowed to set such a symbol to
 itself.
 
 @example
@@ -118,8 +118,8 @@ nil @equiv{} 'nil
 @end group
 @end example
 
-@tindex keyword-symbols-constant-flag
 @defvar keyword-symbols-constant-flag
+@tindex keyword-symbols-constant-flag
 If this variable is @code{nil}, you are allowed to set and bind symbols
 whose names start with @samp{:} as you wish.  This is to make it
 possible to run old Lisp programs which do that.
@@ -247,27 +247,29 @@ Macro calls (@pxref{Macros}).
 @end itemize
 
   Variables can also have buffer-local bindings (@pxref{Buffer-Local
-Variables}); a few variables have terminal-local bindings
-(@pxref{Multiple Displays}).  These kinds of bindings work somewhat like
-ordinary local bindings, but they are localized depending on ``where''
-you are in Emacs, rather than localized in time.
+Variables}) and frame-local bindings (@pxref{Frame-Local Variables}); a
+few variables have terminal-local bindings (@pxref{Multiple Displays}).
+These kinds of bindings work somewhat like ordinary local bindings, but
+they are localized depending on ``where'' you are in Emacs, rather than
+localized in time.
 
 @defvar max-specpdl-size
 @cindex variable limit error
 @cindex evaluation error
 @cindex infinite recursion
-  This variable defines the limit on the total number of local variable
+This variable defines the limit on the total number of local variable
 bindings and @code{unwind-protect} cleanups (@pxref{Nonlocal Exits})
 that are allowed before signaling an error (with data @code{"Variable
 binding depth exceeds max-specpdl-size"}).
 
-  This limit, with the associated error when it is exceeded, is one way
+This limit, with the associated error when it is exceeded, is one way
 that Lisp avoids infinite recursion on an ill-defined function.
-
-  The default value is 600.
-
-  @code{max-lisp-eval-depth} provides another limit on depth of nesting.
+@code{max-lisp-eval-depth} provides another limit on depth of nesting.
 @xref{Eval}.
+
+The default value is 600.  Entry to the Lisp debugger increases the
+value, if there is little room left, to make sure the debugger itself
+has room to execute.
 @end defvar
 
 @node Void Variables
@@ -430,14 +432,15 @@ already has a value (i.e., it is not void), @var{value} is not even
 evaluated, and @var{symbol}'s value remains unchanged.  If @var{value}
 is omitted, the value of @var{symbol} is not changed in any case.
 
+If @var{symbol} has a buffer-local binding in the current buffer,
+@code{defvar} operates on the default value, which is buffer-independent,
+not the current (buffer-local) binding.  It sets the default value if
+the default value is void.  @xref{Buffer-Local Variables}.
+
 When you evaluate a top-level @code{defvar} form with @kbd{C-M-x} in
 Emacs Lisp mode (@code{eval-defun}), a special feature of
-@code{eval-defun} arranges to set the variable unconditionally even if
-the variable already has a value.
-
-If @var{symbol} has a buffer-local binding in the current buffer,
-@code{defvar} sets the default (buffer-independent) value, not the
-buffer-local value.  @xref{Buffer-Local Variables}.
+@code{eval-defun} arranges to set the variable unconditionally, without
+testing whether its value is void.
 
 If the @var{doc-string} argument appears, it specifies the documentation
 for the variable.  (This opportunity to specify documentation is one of
@@ -518,9 +521,10 @@ symbol to be defined must appear explicitly in the @code{defconst}.
 
 @code{defconst} always evaluates @var{value}, and sets the value of
 @var{symbol} to the result if @var{value} is given.  If @var{symbol}
-does has a buffer-local binding in the current buffer, @code{defconst}
-sets the default value, not the buffer-local value.  But you should not
-be making the symbol buffer-local if it is defined with @code{defconst}.
+does have a buffer-local binding in the current buffer, @code{defconst}
+sets the default value, not the buffer-local value.  (But you should not
+be making buffer-local bindings for a symbol that is defined with
+@code{defconst}.)
 
 Here, @code{pi} is a constant that presumably ought not to be changed
 by anyone (attempts by the Indiana State Legislature notwithstanding).
@@ -560,7 +564,7 @@ then the variable is a user option.
 the @code{set-variable} command uses that value to control reading the
 new value for the variable.  The property's value is used as if it were
 to @code{interactive} (@pxref{Using Interactive}).  However, this feature
-is largely obsoleted by the @code{defcustom} (@pxref{Customization}).
+is largely obsoleted by @code{defcustom} (@pxref{Customization}).
 
   @strong{Warning:} If the @code{defconst} and @code{defvar} special
 forms are used while the variable has a local binding, they set the
@@ -1069,7 +1073,7 @@ and/or frames is an important customization method.
 
   This section describes buffer-local bindings; for frame-local
 bindings, see the following section, @ref{Frame-Local Variables}.  (A few
-variables have bindings that are local to a X terminal; see
+variables have bindings that are local to each X terminal; see
 @ref{Multiple Displays}.)
 
 @menu
@@ -1137,8 +1141,8 @@ can scramble the values of the buffer-local and default bindings.
 
   To preserve your sanity, avoid using a variable in that way.  If you
 use @code{save-excursion} around each piece of code that changes to a
-different current buffer, you will not have this problem.  Here is an
-example of what to avoid:
+different current buffer, you will not have this problem
+(@pxref{Excursions}).  Here is an example of what to avoid:
 
 @example
 @group
@@ -1288,7 +1292,7 @@ then the variable appears directly in the resulting list.
 (setq lcl (buffer-local-variables))
     ;; @r{First, built-in variables local in all buffers:}
 @result{} ((mark-active . nil)
-    (buffer-undo-list nil)
+    (buffer-undo-list . nil)
     (mode-name . "Fundamental")
     @dots{}
 @group
@@ -1331,8 +1335,9 @@ result, the buffer will see the default values of most variables.
 
 This function also resets certain other information pertaining to the
 buffer: it sets the local keymap to @code{nil}, the syntax table to the
-value of @code{standard-syntax-table}, and the abbrev table to the value
-of @code{fundamental-mode-abbrev-table}.
+value of @code{(standard-syntax-table)}, the case table to
+@code{(standard-case-table)}, and the abbrev table to the value of
+@code{fundamental-mode-abbrev-table}.
 
 The very first thing this function does is run the normal hook
 @code{change-major-mode-hook} (see below).
@@ -1400,10 +1405,11 @@ default value is nonvoid.  If @code{(default-boundp 'foo)} returns
 @code{symbol-value}.
 @end defun
 
-@defspec setq-default symbol value
-This sets the default value of @var{symbol} to @var{value}.  It does not
-evaluate @var{symbol}, but does evaluate @var{value}.  The value of the
-@code{setq-default} form is @var{value}.
+@defspec setq-default [symbol form]@dots{}
+This special form gives each @var{symbol} a new default value, which is
+the result of evaluating the corresponding @var{form}.  It does not
+evaluate @var{symbol}, but does evaluate @var{form}.  The value of the
+@code{setq-default} form is the value of the last @var{form}.
 
 If a @var{symbol} is not buffer-local for the current buffer, and is not
 marked automatically buffer-local, @code{setq-default} has the same
@@ -1492,17 +1498,18 @@ name as the parameter name.
   To enable frame-local bindings for a certain variable, call the function
 @code{make-variable-frame-local}.
 
-@defun make-variable-frame-local variable
+@deffn Command make-variable-frame-local variable
 Enable the use of frame-local bindings for @var{variable}.  This does
 not in itself create any frame-local bindings for the variable; however,
 if some frame already has a value for @var{variable} as a frame
 parameter, that value automatically becomes a frame-local binding.
 
-If the variable is terminal-local, this function signals an error.  Such
-variables cannot have buffer-local bindings as well.  @xref{Multiple
-Displays}.  A few variables that are implemented specially in Emacs
-can be (and usually are) buffer-local, but can never be frame-local.
-@end defun
+If the variable is terminal-local, this function signals an error,
+because such variables cannot have frame-local bindings as well.
+@xref{Multiple Displays}.  A few variables that are implemented
+specially in Emacs can be (and usually are) buffer-local, but can never
+be frame-local.
+@end deffn
 
   Buffer-local bindings take precedence over frame-local bindings.  Thus,
 consider a variable @code{foo}: if the current buffer has a buffer-local
diff --git a/lispref/windows.texi b/lispref/windows.texi
index 9199ff0f8d2..bd4bad02137 100644
--- a/lispref/windows.texi
+++ b/lispref/windows.texi
@@ -597,7 +597,9 @@ when you need complete control.
 
 @defun set-window-buffer window buffer-or-name
 This function makes @var{window} display @var{buffer-or-name} as its
-contents.  It returns @code{nil}.
+contents.  It returns @code{nil}.  This is the fundamental primitive
+for changing which buffer is displayed in a window, and all ways
+of doing that call this function.
 
 @example
 @group
@@ -669,6 +671,16 @@ If it is a frame, consider windows on that frame.
 @end itemize
 @end defun
 
+@defvar buffer-display-time
+@tindex buffer-display-time
+This variable records the time at which a buffer was last made visible
+in a window.  It is always local in each buffer; each time
+@code{set-window-buffer} is called, it sets this variable to
+@code{(current-time)} in the specified buffer (@pxref{Time of Day}).
+When a buffer is first created, @code{buffer-display-count} starts out
+with the value @code{nil}.
+@end defvar
+
 @node Displaying Buffers
 @section Displaying Buffers in Windows
 @cindex switching to a buffer
@@ -685,7 +697,8 @@ See the preceding section for
 @ifinfo
 @xref{Buffers and Windows}, for
 @end ifinfo
-low-level functions that give you more precise control.
+low-level functions that give you more precise control.  All of these
+functions work by calling @code{set-window-buffer}.
 
   Do not use the functions in this section in order to make a buffer
 current so that a Lisp program can access or modify it; they are too
@@ -786,14 +799,6 @@ don't care which other buffer is used; you just want to make sure that
 This function returns @code{nil}.
 @end deffn
 
-@tindex buffer-display-count
-@defvar buffer-display-count
-This variable is always buffer-local in each buffer.  When the buffer is
-created, @code{buffer-display-count} has value 0.  Each time the buffer
-is displayed in a window, that increments the value of
-@code{buffer-display-count}.
-@end defvar
-
 @node Choosing Window
 @section Choosing a Window for Display
 
@@ -1308,13 +1313,14 @@ Replaces three keystroke sequence C-u 0 C-l."
 @section Horizontal Scrolling
 @cindex horizontal scrolling
 
-  Because we read English first from top to bottom and second from left
-to right, horizontal scrolling is not like vertical scrolling.  Vertical
-scrolling involves selection of a contiguous portion of text to display.
-Horizontal scrolling causes part of each line to go off screen.  The
-amount of horizontal scrolling is therefore specified as a number of
-columns rather than as a position in the buffer.  It has nothing to do
-with the display-start position returned by @code{window-start}.
+  Because we read English from left to right in the ``inner loop'', and
+from top to bottom in the ``outer loop'', horizontal scrolling is not
+like vertical scrolling.  Vertical scrolling involves selection of a
+contiguous portion of text to display, but horizontal scrolling causes
+part of each line to go off screen.  The amount of horizontal scrolling
+is therefore specified as a number of columns rather than as a position
+in the buffer.  It has nothing to do with the display-start position
+returned by @code{window-start}.
 
   Usually, no horizontal scrolling is in effect; then the leftmost
 column is at the left edge of the window.  In this state, scrolling to
@@ -1838,8 +1844,8 @@ over.  In most cases, @code{save-selected-window} (@pxref{Selecting
 Windows}) is what you need here.
 @end defvar
 
-@tindex redisplay-end-trigger-functions
 @defvar redisplay-end-trigger-functions
+@tindex redisplay-end-trigger-functions
 This abnormal hook is run whenever redisplay in window uses text that
 extends past a specified end trigger position.  You set the end trigger
 position with the function @code{set-window-redisplay-end-trigger}.  The
@@ -1849,19 +1855,19 @@ feature, and the trigger value is automatically reset to @code{nil} just
 after the hook is run.
 @end defvar
 
-@tindex set-window-redisplay-end-trigger
 @defun set-window-redisplay-end-trigger window position
+@tindex set-window-redisplay-end-trigger
 This function sets @var{window}'s end trigger position at
 @var{position}.
 @end defun
 
-@tindex window-redisplay-end-trigger
 @defun window-redisplay-end-trigger window
+@tindex window-redisplay-end-trigger
 This function returns @var{window}'s current end trigger position.
 @end defun
 
-@tindex window-configuration-change-hook
 @defvar window-configuration-change-hook
+@tindex window-configuration-change-hook
 A normal hook that is run every time you change the window configuration
 of an existing frame.  This includes splitting or deleting windows,
 changing the sizes of windows, or displaying a different buffer in a