upstream

15 files changed, 601 insertions, 612 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index a823f4272fc..c5848ca8b2d 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,5 +1,77 @@
+2012-02-12  Chong Yidong  <cyd@gnu.org>
+
+        * debugging.texi (Debugger Commands): Continuing is now allowed
+        for errors.
+
+2012-02-11  Chong Yidong  <cyd@gnu.org>
+
+        * display.texi (Fringe Indicators): Add xref to Fringe Bitmaps.
+        Move the list of standard bitmaps there.
+        (Fringe Cursors): Rewrite for clarity.
+        (Fringe Bitmaps): Consolidate the list of standard bitmaps here.
+
+        * commands.texi (Command Overview): Mention read-key.
+        (Using Interactive, Interactive Call): Minor clarifications.
+        (Function Keys, Click Events): Avoid "input stream" terminology.
+        (Click Events): Add xref to Window Sizes and Accessing Mouse.
+        Clarify column and row components.
+        (Accessing Mouse): Add xref to Click Events.  Minor fixes.
+        (Special Events): Copyedits.
+
+        * streams.texi (Input Streams): De-document get-file-char.
+        (Output Variables): Don't refer to old backquote syntax.
+
+        * debugging.texi (Debugging): Copyedits.  Describe testcover, ERT.
+        (Error Debugging): Note that debug-ignored-errors overrides list
+        values of debug-on-error too.  Add xref to Signaling Errors.  Note
+        that debug-on-signal is not customizable.  Mention
+        condition-case-unless-debug.
+        (Compilation Errors): Node deleted.
+
+        * compile.texi (Compiler Errors): Move a paragraph here from
+        deleted node Compilation Errors.
+
+2012-02-10  Leo Liu  <sdl.web@gmail.com>
+
+        * control.texi (Handling Errors): Change condition-case-no-debug
+        to condition-case-unless-debug.
+
+2012-02-10  Chong Yidong  <cyd@gnu.org>
+
+        * advice.texi (Defining Advice): Clarify ad-unadvise.
+        (Activation of Advice): Specifying the ACTIVATE flag in defadvice
+        is not abnormal.
+        (Advising Primitives): Node deleted; ad-define-subr-args has been
+        removed.
+
+        * compile.texi (Speed of Byte-Code): Use float-time in example.
+        (Compilation Functions): Note that the log uses Compilation mode.
+        Don't discuss the contents of byte-code function object here.
+        (Compilation Functions): De-document internal function byte-code.
+        (Docs and Compilation): Minor clarifications.
+
+        * objects.texi (Byte-Code Type): Add xref to Byte-Code Function
+        Objects.
+
+2012-02-10  Glenn Morris  <rgm@gnu.org>
+
+        * text.texi (Checksum/Hash): Rename node from MD5 Checksum.
+        Mention secure-hash.
+        * elisp.texi, vol1.texi, vol2.texi: Update menu entry.
+
+2012-02-10  Chong Yidong  <cyd@gnu.org>
+
+        * loading.texi (Loading): Don't emphasize "library" terminology.
+        (Library Search): load-path is not a user option.  Mention role of
+        -L option and packages.  Improve examples.
+        (Loading Non-ASCII): Don't mention unibyte Emacs, which is
+        obsolete.
+        (Autoload): Minor clarifications.
+
 2012-02-10  Glenn Morris  <rgm@gnu.org>
 
+        * files.texi (Magic File Names): Tweak remote-file-name-inhibit-cache.
+
         * modes.texi (Basic Major Modes): Mention tabulated-list-mode.
 
 2012-02-08  Glenn Morris  <rgm@gnu.org>
diff --git a/doc/lispref/advice.texi b/doc/lispref/advice.texi
index ee1950a589a..78b4ac9aa2d 100644
--- a/doc/lispref/advice.texi
+++ b/doc/lispref/advice.texi
@@ -13,30 +13,35 @@ for a library to customize functions defined within Emacs---cleaner
 than redefining the whole function.
 
 @cindex piece of advice
-  Each function can have multiple @dfn{pieces of advice}, separately
-defined.  Each defined piece of advice can be @dfn{enabled} or
-@dfn{disabled} explicitly.  All the enabled pieces of advice for any given
-function actually take effect when you @dfn{activate} advice for that
+  Each function can have multiple @dfn{pieces of advice}, each of
+which can be separately defined and then @dfn{enabled} or
+@dfn{disabled}.  All the enabled pieces of advice for any given
+function actually take effect when you @dfn{activate advice} for that
 function, or when you define or redefine the function.  Note that
-enabling a piece of advice and activating advice for a function
-are not the same thing.
-
-  @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, you should define a new function
-(or a new command) which uses the existing function.
-
-  @strong{Usage note:} Advising a function can cause confusion in
-debugging, since people who debug calls to the original function may
-not notice that it has been modified with advice.  Therefore, if you
-have the possibility to change the code of that function (or ask
-someone to do so) to run a hook, please solve the problem that way.
-Advice should be reserved for the cases where you cannot get the
-function changed.
-
-  In particular, this means that a file in Emacs should not put advice
-on a function in Emacs.  There are currently a few exceptions to this
-convention, but we aim to correct them.
+enabling a piece of advice and activating advice for a function are
+not the same thing.
+
+  Advice is useful for altering the behavior of existing calls to an
+existing function.  If you want the new behavior for new function
+calls or new key bindings, you should define a new function or
+command, and have it use the existing function as a subroutine.
+
+  Advising a function can cause confusion in debugging, since people
+who debug calls to the original function may not notice that it has
+been modified with advice.  Therefore, if you have the possibility to
+change the code of that function to run a hook, please solve the
+problem that way.  Advice should be reserved for the cases where you
+cannot get the function changed.  In particular, Emacs' own source
+files should not put advice on functions in Emacs.  There are
+currently a few exceptions to this convention, but we aim to correct
+them.
+
+  Unless you know what you are doing, do @emph{not} advise a primitive
+(@pxref{What Is a Function}).  Some primitives are used by the advice
+mechanism; advising them could cause an infinite recursion.  Also,
+many primitives are called directly from C code.  Calls to the
+primitive from Lisp code will take note of the advice, but calls from
+C code will ignore the advice.
 
 @menu
 * Simple Advice::           A simple example to explain the basics of advice.
@@ -48,7 +53,6 @@ convention, but we aim to correct them.
 * Preactivation::           Preactivation is a way of speeding up the
                               loading of compiled advice.
 * Argument Access in Advice:: How advice can access the function's arguments.
-* Advising Primitives::     Accessing arguments when advising a primitive.
 * Combined Definition::     How advice is implemented.
 @end menu
 
@@ -258,7 +262,7 @@ All subroutines used by the advice need to be available when the byte
 compiler expands the macro.
 
 @deffn Command ad-unadvise function
-This command deletes the advice from @var{function}.
+This command deletes all pieces of advice from @var{function}.
 @end deffn
 
 @deffn Command ad-unadvise-all
@@ -355,13 +359,13 @@ replaced with the new one.
 @cindex advice, activating
 
 By default, advice does not take effect when you define it---only when
-you @dfn{activate} advice for the function that was advised.  However,
-the advice will be activated automatically if you define or redefine
-the function later.  You can request the activation of advice for a
-function when you define the advice, by specifying the @code{activate}
-flag in the @code{defadvice}.  But normally you activate the advice
-for a function by calling the function @code{ad-activate} or one of
-the other activation commands listed below.
+you @dfn{activate} advice for the function.  However, the advice will
+be activated automatically if you define or redefine the function
+later.  You can request the activation of advice for a function when
+you define the advice, by specifying the @code{activate} flag in the
+@code{defadvice}; or you can activate the advice separately by calling
+the function @code{ad-activate} or one of the other activation
+commands listed below.
 
 Separating the activation of advice from the act of defining it permits
 you to add several pieces of advice to one function efficiently, without
@@ -680,39 +684,6 @@ 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.
 
-@node Advising Primitives
-@section Advising Primitives
-@cindex advising primitives
-
-  Advising a primitive function (@pxref{What Is a Function}) is risky.
-Some primitive functions are used by the advice mechanism; advising
-them could cause an infinite recursion.  Also, many primitive
-functions are called directly from C code.  Calls to the primitive
-from Lisp code will take note of the advice, but calls from C code
-will ignore the advice.
-
-When the advice facility constructs the combined definition, it needs
-to know the argument list of the original function.  This is not
-always possible for primitive functions.  When advice cannot determine
-the argument list, it uses @code{(&rest ad-subr-args)}, which always
-works but is inefficient because it constructs a list of the argument
-values.  You can use @code{ad-define-subr-args} to declare the proper
-argument names for a primitive function:
-
-@defun ad-define-subr-args function arglist
-This function specifies that @var{arglist} should be used as the
-argument list for function @var{function}.
-@end defun
-
-For example,
-
-@example
-(ad-define-subr-args 'fset '(sym newdef))
-@end example
-
-@noindent
-specifies the argument list for the function @code{fset}.
-
 @node Combined Definition
 @section The Combined Definition
 
diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi
index 91e224a439f..f4e7c922331 100644
--- a/doc/lispref/commands.texi
+++ b/doc/lispref/commands.texi
@@ -37,13 +37,13 @@ are done, and the subroutines that allow Lisp programs to do them.
 @node Command Overview
 @section Command Loop Overview
 
-  The first thing the command loop must do is read a key sequence, which
-is a sequence of events that translates into a command.  It does this by
-calling the function @code{read-key-sequence}.  Your Lisp code can also
-call this function (@pxref{Key Sequence Input}).  Lisp programs can also
-do input at a lower level with @code{read-event} (@pxref{Reading One
-Event}) or discard pending input with @code{discard-input}
-(@pxref{Event Input Misc}).
+  The first thing the command loop must do is read a key sequence,
+which is a sequence of input events that translates into a command.
+It does this by calling the function @code{read-key-sequence}.  Lisp
+programs can also call this function (@pxref{Key Sequence Input}).
+They can also read input at a lower level with @code{read-key} or
+@code{read-event} (@pxref{Reading One Event}), or discard pending
+input with @code{discard-input} (@pxref{Event Input Misc}).
 
   The key sequence is translated into a command through the currently
 active keymaps.  @xref{Key Lookup}, for information on how this is done.
@@ -67,12 +67,9 @@ use the minibuffer, so if you call @code{find-file} as a function from
 Lisp code, you must supply the file name string as an ordinary Lisp
 function argument.
 
-  If the command is a string or vector (i.e., a keyboard macro) then
-@code{execute-kbd-macro} is used to execute it.  You can call this
-function yourself (@pxref{Keyboard Macros}).
-
-  To terminate the execution of a running command, type @kbd{C-g}.  This
-character causes @dfn{quitting} (@pxref{Quitting}).
+  If the command is a keyboard macro (i.e.@: a string or vector),
+Emacs executes it using @code{execute-kbd-macro} (@pxref{Keyboard
+Macros}).
 
 @defvar pre-command-hook
 This normal hook is run by the editor command loop before it executes
@@ -175,8 +172,8 @@ or more arguments.
 
 @item
 It may be a string; its contents are a sequence of elements separated
-by newlines, one for each parameter@footnote{Some elements actually
-supply two parameters.}.  Each element consists of a code character
+by newlines, one for each argument@footnote{Some elements actually
+supply two arguments.}.  Each element consists of a code character
 (@pxref{Interactive Codes}) optionally followed by a prompt (which
 some code characters use and some ignore).  Here is an example:
 
@@ -575,21 +572,24 @@ the command is a function, @code{command-execute} calls
 @code{call-interactively}, which reads the arguments and calls the
 command.  You can also call these functions yourself.
 
-@defun commandp object &optional for-call-interactively
-Returns @code{t} if @var{object} is suitable for calling interactively;
-that is, if @var{object} is a command.  Otherwise, returns @code{nil}.
-
-Interactively-callable objects include strings and vectors (which are
-treated as keyboard macros), lambda expressions that contain a
-top-level @code{interactive} form (@pxref{Using Interactive}),
-byte-code function objects made from such lambda expressions, autoload
-objects that are declared as interactive (non-@code{nil} fourth
-argument to @code{autoload}), and some primitive functions.
+  Note that the term ``command'', in this context, refers to an
+interactively callable function (or function-like object), or a
+keyboard macro.  It does not refer to the key sequence used to invoke
+a command (@pxref{Keymaps}).
 
-A symbol satisfies @code{commandp} if it has a non-@code{nil}
+@defun commandp object &optional for-call-interactively
+This function returns @code{t} if @var{object} is a command.
+Otherwise, it returns @code{nil}.
+
+Commands include strings and vectors (which are treated as keyboard
+macros), lambda expressions that contain a top-level
+@code{interactive} form (@pxref{Using Interactive}), byte-code
+function objects made from such lambda expressions, autoload objects
+that are declared as interactive (non-@code{nil} fourth argument to
+@code{autoload}), and some primitive functions.  Also, a symbol is
+considered a command if it has a non-@code{nil}
 @code{interactive-form} property, or if its function definition
-satisfies @code{commandp}.  Keys and keymaps are not commands.
-Rather, they are used to look up commands (@pxref{Keymaps}).
+satisfies @code{commandp}.
 
 If @var{for-call-interactively} is non-@code{nil}, then
 @code{commandp} returns @code{t} only for objects that
@@ -649,14 +649,14 @@ callable function or a keyboard macro.
 
 A string or vector as @var{command} is executed with
 @code{execute-kbd-macro}.  A function is passed to
-@code{call-interactively}, along with the optional @var{record-flag}
-and @var{keys}.
+@code{call-interactively} (see above), along with the
+@var{record-flag} and @var{keys} arguments.
 
-A symbol is handled by using its function definition in its place.  A
-symbol with an @code{autoload} definition counts as a command if it was
-declared to stand for an interactively callable function.  Such a
-definition is handled by loading the specified library and then
-rechecking the definition of the symbol.
+If @var{command} is a symbol, its function definition is used in its
+place.  A symbol with an @code{autoload} definition counts as a
+command if it was declared to stand for an interactively callable
+function.  Such a definition is handled by loading the specified
+library and then rechecking the definition of the symbol.
 
 The argument @var{special}, if given, means to ignore the prefix
 argument and not clear it.  This is used for executing special events
@@ -1131,9 +1131,9 @@ The
 @ifnottex
 2**22
 @end ifnottex
-bit in the character code indicates a character typed with
-the alt key held down.  (On some terminals, the key labeled @key{ALT}
-is actually the meta key.)
+bit in the character code indicates a character typed with the alt key
+held down.  (The key labeled @key{Alt} on most keyboards is actually
+treated as the meta key, not this.)
 @end table
 
   It is best to avoid mentioning specific bit numbers in your program.
@@ -1151,10 +1151,10 @@ specify the characters (@pxref{Changing Key Bindings}).  The function
 
 @cindex function keys
 Most keyboards also have @dfn{function keys}---keys that have names or
-symbols that are not characters.  Function keys are represented in Emacs
-Lisp as symbols; the symbol's name is the function key's label, in lower
-case.  For example, pressing a key labeled @key{F1} places the symbol
-@code{f1} in the input stream.
+symbols that are not characters.  Function keys are represented in
+Emacs Lisp as symbols; the symbol's name is the function key's label,
+in lower case.  For example, pressing a key labeled @key{F1} generates
+an input event represented by the symbol @code{f1}.
 
 The event type of a function key event is the event symbol itself.
 @xref{Classifying Events}.
@@ -1287,6 +1287,11 @@ the marginal areas, @var{position} has this form:
  @var{image} (@var{dx} . @var{dy}) (@var{width} . @var{height}))
 @end example
 
+@noindent
+The meanings of these list elements are documented below.
+@xref{Accessing Mouse}, for functions that let you easily access these
+elements.
+
 @table @asis
 @item @var{window}
 This is the window in which the click occurred.
@@ -1298,39 +1303,36 @@ which the click occurred.  It is one of the symbols @code{mode-line},
 @code{header-line}, @code{vertical-line}, @code{left-margin},
 @code{right-margin}, @code{left-fringe}, or @code{right-fringe}.
 
-In one special case, @var{pos-or-area} is a list containing a symbol (one
-of the symbols listed above) instead of just the symbol.  This happens
-after the imaginary prefix keys for the event are inserted into the
-input stream.  @xref{Key Sequence Input}.
-
+In one special case, @var{pos-or-area} is a list containing a symbol
+(one of the symbols listed above) instead of just the symbol.  This
+happens after the imaginary prefix keys for the event are registered
+by Emacs.  @xref{Key Sequence Input}.
 
 @item @var{x}, @var{y}
-These are the pixel coordinates of the click, relative to
-the top left corner of @var{window}, which is @code{(0 . 0)}.
-For a click on text, these are relative to the top left corner of
-the window's text area.  For the mode or header line, they are
-relative to the top left window edge.  For fringes, margins, and the
-vertical border, @var{x} does not have meaningful data.  For fringes
-and margins, @var{y} is relative to the bottom edge of the header
-line.
+These are the relative pixel coordinates of the click.  For clicks in
+the text area of a window, the coordinate origin @code{(0 . 0)} is
+taken to be the top left corner of the text area.  @xref{Window
+Sizes}.  For clicks in a mode line or header line, the coordinate
+origin is the top left corner of the window itself.  For fringes,
+margins, and the vertical border, @var{x} does not have meaningful
+data.  For fringes and margins, @var{y} is relative to the bottom edge
+of the header line.  In all cases, the @var{x} and @var{y} coordinates
+increase rightward and downward respectively.
 
 @item @var{timestamp}
 This is the time at which the event occurred, in milliseconds.
 
 @item @var{object}
-This is the object on which the click occurred.  It is either
-@code{nil} if there is no string property, or it has the form
-(@var{string} . @var{string-pos}) when there is a string-type text
-property at the click position.
+This is either @code{nil} if there is no string-type text property at
+the click position, or a cons cell of the form (@var{string}
+. @var{string-pos}) if there is one:
 
 @table @asis
 @item @var{string}
-This is the string on which the click occurred, including any
-properties.
+The string which was clicked on, including any properties.
 
 @item @var{string-pos}
-This is the position in the string on which the click occurred,
-relevant if properties at the click need to be looked up.
+The position in the string where the click occurred.
 @end table
 
 @item @var{text-pos}
@@ -1340,14 +1342,17 @@ the window.  For other events, it is the current buffer position in
 the window.
 
 @item @var{col}, @var{row}
-These are the actual coordinates of the glyph under the @var{x},
-@var{y} position, possibly padded with default character width
-glyphs if @var{x} is beyond the last glyph on the line.  For clicks on
-the header or mode line, these are measured from the top left edge of
-the header or mode line.  For clicks on the fringes and on the
-vertical border, these have no meaningful data.  For clicks on the
-margins, @var{col} is measured from the left edge of the margin area
-and @var{row} is measured from the top of the margin area.
+These are the actual column and row coordinate numbers of the glyph
+under the @var{x}, @var{y} position.  If @var{x} lies beyond the last
+column of actual text on its line, @var{col} is reported by adding
+fictional extra columns that have the default character width.  Row 0
+is taken to be the header line if the window has one, or the topmost
+row of the text area otherwise.  Column 0 is taken to be the leftmost
+column of the text area for clicks on a window text area, or the
+leftmost mode line or header line column for clicks there.  For clicks
+on fringes or vertical borders, these have no meaningful data.  For
+clicks on margins, @var{col} is measured from the left edge of the
+margin area and @var{row} is measured from the top of the margin area.
 
 @item @var{image}
 This is the image object on which the click occurred.  It is either
@@ -1885,7 +1890,7 @@ must be the last element of the list.  For example,
 a mouse button or motion event.
 
   These two functions return the starting or ending position of a
-mouse-button event, as a list of this form:
+mouse-button event, as a list of this form (@pxref{Click Events}):
 
 @example
 (@var{window} @var{pos-or-area} (@var{x} . @var{y}) @var{timestamp}
@@ -1936,12 +1941,13 @@ Return the pixel-based x and y coordinates in @var{position}, as a
 cons cell @code{(@var{x} . @var{y})}.  These coordinates are relative
 to the window given by @code{posn-window}.
 
-This example shows how to convert these window-relative coordinates
-into frame-relative coordinates:
+This example shows how to convert the window-relative coordinates in
+the text area of a window into frame-relative coordinates:
 
 @example
 (defun frame-relative-coordinates (position)
-  "Return frame-relative coordinates from POSITION."
+  "Return frame-relative coordinates from POSITION.
+POSITION is assumed to lie in a window text area."
   (let* ((x-y (posn-x-y position))
          (window (posn-window position))
          (edges (window-inside-pixel-edges window)))
@@ -1966,10 +1972,10 @@ window possesses a header line (@pxref{Header Lines}), it is
 
 @defun posn-actual-col-row position
 Return the actual row and column in @var{position}, as a cons cell
-@code{(@var{col} . @var{row})}.  The values are the actual row number
-in the window, and the actual character number in that row.  It returns
-@code{nil} if @var{position} does not include actual positions values.
-You can use @code{posn-col-row} to get approximate values.
+@code{(@var{col} . @var{row})}.  The values are the actual row and
+column numbers in the window.  @xref{Click Events}, for details.  It
+returns @code{nil} if @var{position} does not include actual positions
+values.
 @end defun
 
 @defun posn-string position
@@ -2680,9 +2686,9 @@ Likewise, incremental search uses this feature to unread events with no
 special meaning in a search, because these events should exit the search
 and then execute normally.
 
-The reliable and easy way to extract events from a key sequence so as to
-put them in @code{unread-command-events} is to use
-@code{listify-key-sequence} (@pxref{Strings of Events}).
+The reliable and easy way to extract events from a key sequence so as
+to put them in @code{unread-command-events} is to use
+@code{listify-key-sequence} (see below).
 
 Normally you add events to the front of this list, so that the events
 most recently unread will be reread first.
@@ -2787,28 +2793,29 @@ during the sleep.
 @section Special Events
 
 @cindex special events
-Special events are handled at a very low level---as soon as they are
-read.  The @code{read-event} function processes these events itself, and
-never returns them.  Instead, it keeps waiting for the first event
-that is not special and returns that one.
+Certain @dfn{special events} are handled at a very low level---as soon
+as they are read.  The @code{read-event} function processes these
+events itself, and never returns them.  Instead, it keeps waiting for
+the first event that is not special and returns that one.
 
-Events that are handled in this way do not echo, they are never grouped
-into key sequences, and they never appear in the value of
+  Special events do not echo, they are never grouped into key
+sequences, and they never appear in the value of
 @code{last-command-event} or @code{(this-command-keys)}.  They do not
 discard a numeric argument, they cannot be unread with
 @code{unread-command-events}, they may not appear in a keyboard macro,
 and they are not recorded in a keyboard macro while you are defining
 one.
 
-These events do, however, appear in @code{last-input-event} immediately
-after they are read, and this is the way for the event's definition to
-find the actual event.
+  Special events do, however, appear in @code{last-input-event}
+immediately after they are read, and this is the way for the event's
+definition to find the actual event.
 
-The events types @code{iconify-frame}, @code{make-frame-visible},
+  The events types @code{iconify-frame}, @code{make-frame-visible},
 @code{delete-frame}, @code{drag-n-drop}, and user signals like
 @code{sigusr1} are normally handled in this way.  The keymap which
-defines how to handle special events---and which events are special---is
-in the variable @code{special-event-map} (@pxref{Active Keymaps}).
+defines how to handle special events---and which events are
+special---is in the variable @code{special-event-map} (@pxref{Active
+Keymaps}).
 
 @node Waiting
 @section Waiting for Elapsed Time or Input
diff --git a/doc/lispref/compile.texi b/doc/lispref/compile.texi
index 4e21df78430..90d038c29d6 100644
--- a/doc/lispref/compile.texi
+++ b/doc/lispref/compile.texi
@@ -32,9 +32,6 @@ variable binding for @code{no-byte-compile} into it, like this:
 ;; -*-no-byte-compile: t; -*-
 @end example
 
-  @xref{Compilation Errors}, for how to investigate errors occurring in
-byte compilation.
-
 @menu
 * Speed of Byte-Code::          An example of speedup from byte compilation.
 * Compilation Functions::       Byte compilation functions.
@@ -56,18 +53,16 @@ Here is an example:
 @example
 @group
 (defun silly-loop (n)
-  "Return time before and after N iterations of a loop."
-  (let ((t1 (current-time-string)))
-    (while (> (setq n (1- n))
-              0))
-    (list t1 (current-time-string))))
+  "Return the time, in seconds, to run N iterations of a loop."
+  (let ((t1 (float-time)))
+    (while (> (setq n (1- n)) 0))
+    (- (float-time) t1)))
 @result{} silly-loop
 @end group
 
 @group
 (silly-loop 50000000)
-@result{} ("Wed Mar 11 21:10:19 2009"
-    "Wed Mar 11 21:10:41 2009")  ; @r{22 seconds}
+@result{} 10.235304117202759
 @end group
 
 @group
@@ -77,18 +72,17 @@ Here is an example:
 
 @group
 (silly-loop 50000000)
-@result{} ("Wed Mar 11 21:12:26 2009"
-    "Wed Mar 11 21:12:32 2009")  ; @r{6 seconds}
+@result{} 3.705854892730713
 @end group
 @end example
 
-  In this example, the interpreted code required 22 seconds to run,
-whereas the byte-compiled code required 6 seconds.  These results are
-representative, but actual results will vary greatly.
+  In this example, the interpreted code required 10 seconds to run,
+whereas the byte-compiled code required less than 4 seconds.  These
+results are representative, but actual results may vary.
 
 @node Compilation Functions
 @comment  node-name,  next,  previous,  up
-@section The Compilation Functions
+@section Byte-Compilation Functions
 @cindex compilation functions
 
   You can byte-compile an individual function or macro definition with
@@ -96,43 +90,36 @@ the @code{byte-compile} function.  You can compile a whole file with
 @code{byte-compile-file}, or several files with
 @code{byte-recompile-directory} or @code{batch-byte-compile}.
 
-  The byte compiler produces error messages and warnings about each file
-in a buffer called @samp{*Compile-Log*}.  These report things in your
-program that suggest a problem but are not necessarily erroneous.
+  Sometimes, the byte compiler produces warning and/or error messages
+(@pxref{Compiler Errors}, for details).  These messages are recorded
+in a buffer called @samp{*Compile-Log*}, which uses Compilation mode.
+@xref{Compilation Mode,,,emacs, The GNU Emacs Manual}.
 
 @cindex macro compilation
-  Be careful when writing macro calls in files that you may someday
-byte-compile.  Macro calls are expanded when they are compiled, so the
-macros must already be defined for proper compilation.  For more
-details, see @ref{Compiling Macros}.  If a program does not work the
-same way when compiled as it does when interpreted, erroneous macro
-definitions are one likely cause (@pxref{Problems with Macros}).
-Inline (@code{defsubst}) functions are less troublesome; if you
+  Be careful when writing macro calls in files that you intend to
+byte-compile.  Since macro calls are expanded when they are compiled,
+the macros need to be loaded into Emacs or the byte compiler will not
+do the right thing.  The usual way to handle this is with
+@code{require} forms which specify the files containing the needed
+macro definitions (@pxref{Named Features}).  Normally, the
+byte compiler does not evaluate the code that it is compiling, but it
+handles @code{require} forms specially, by loading the specified
+libraries.  To avoid loading the macro definition files when someone
+@emph{runs} the compiled program, write @code{eval-when-compile}
+around the @code{require} calls (@pxref{Eval During Compile}).  For
+more details, @xref{Compiling Macros}.
+
+  Inline (@code{defsubst}) functions are less troublesome; if you
 compile a call to such a function before its definition is known, the
 call will still work right, it will just run slower.
 
-  Normally, compiling a file does not evaluate the file's contents or
-load the file.  But it does execute any @code{require} calls at top
-level in the file.  One way to ensure that necessary macro definitions
-are available during compilation is to require the file that defines
-them (@pxref{Named Features}).  To avoid loading the macro definition files
-when someone @emph{runs} the compiled program, write
-@code{eval-when-compile} around the @code{require} calls (@pxref{Eval
-During Compile}).
-
 @defun byte-compile symbol
 This function byte-compiles the function definition of @var{symbol},
 replacing the previous definition with the compiled one.  The function
 definition of @var{symbol} must be the actual code for the function;
-i.e., the compiler does not follow indirection to another symbol.
-@code{byte-compile} returns the new, compiled definition of
-@var{symbol}.
-
-  If @var{symbol}'s definition is a byte-code function object,
-@code{byte-compile} does nothing and returns @code{nil}.  Lisp records
-only one function definition for any symbol, and if that is already
-compiled, non-compiled code is not available anywhere.  So there is no
-way to ``compile the same definition again.''
+@code{byte-compile} does not handle function indirection.  The return
+value is the byte-code function object which is the compiled
+definition of @var{symbol} (@pxref{Byte-Code Objects}).
 
 @example
 @group
@@ -153,16 +140,15 @@ way to ``compile the same definition again.''
 @end group
 @end example
 
-@noindent
-The result is a byte-code function object.  The string it contains is
-the actual byte-code; each character in it is an instruction or an
-operand of an instruction.  The vector contains all the constants,
-variable names and function names used by the function, except for
-certain primitives that are coded as special instructions.
-
-If the argument to @code{byte-compile} is a @code{lambda} expression,
-it returns the corresponding compiled code, but does not store
-it anywhere.
+If @var{symbol}'s definition is a byte-code function object,
+@code{byte-compile} does nothing and returns @code{nil}.  It does not
+``compile the symbol's definition again'', since the original
+(non-compiled) code has already been replaced in the symbol's function
+cell by the byte-compiled code.
+
+The argument to @code{byte-compile} can also be a @code{lambda}
+expression.  In that case, the function returns the corresponding
+compiled code but does not store it anywhere.
 @end defun
 
 @deffn Command compile-defun &optional arg
@@ -252,19 +238,6 @@ files that have an up-to-date @samp{.elc} file.
 @end example
 @end defun
 
-@defun byte-code code-string data-vector max-stack
-@cindex byte-code interpreter
-This function actually interprets byte-code.  A byte-compiled function
-is actually defined with a body that calls @code{byte-code}.  Don't call
-this function yourself---only the byte compiler knows how to generate
-valid calls to this function.
-
-In Emacs version 18, byte-code was always executed by way of a call to
-the function @code{byte-code}.  Nowadays, byte-code is usually executed
-as part of a byte-code function object, and only rarely through an
-explicit call to @code{byte-code}.
-@end defun
-
 @node Docs and Compilation
 @section Documentation Strings and Compilation
 @cindex dynamic loading of documentation
@@ -290,33 +263,11 @@ then further access to documentation strings in this file will
 probably give nonsense results.
 @end itemize
 
-  If your site installs Emacs following the usual procedures, these
-problems will never normally occur.  Installing a new version uses a new
-directory with a different name; as long as the old version remains
-installed, its files will remain unmodified in the places where they are
-expected to be.
-
-  However, if you have built Emacs yourself and use it from the
-directory where you built it, you will experience this problem
-occasionally if you edit and recompile Lisp files.  When it happens, you
-can cure the problem by reloading the file after recompiling it.
-
-  You can turn off this feature at compile time by setting
-@code{byte-compile-dynamic-docstrings} to @code{nil}; this is useful
-mainly if you expect to change the file, and you want Emacs processes
-that have already loaded it to keep working when the file changes.
-You can do this globally, or for one source file by specifying a
-file-local binding for the variable.  One way to do that is by adding
-this string to the file's first line:
-
-@example
--*-byte-compile-dynamic-docstrings: nil;-*-
-@end example
-
-@defvar byte-compile-dynamic-docstrings
-If this is non-@code{nil}, the byte compiler generates compiled files
-that are set up for dynamic loading of documentation strings.
-@end defvar
+@noindent
+These problems normally occur only if you build Emacs yourself and use
+it from the directory where you built it, and you happen to edit
+and/or recompile the Lisp source files.  They can be easily cured by
+reloading each file after recompiling it.
 
 @cindex @samp{#@@@var{count}}
 @cindex @samp{#$}
@@ -328,6 +279,23 @@ string.''  It is usually best not to use these constructs in Lisp source
 files, since they are not designed to be clear to humans reading the
 file.
 
+  You can disable the dynamic documentation string feature at compile
+time by setting @code{byte-compile-dynamic-docstrings} to @code{nil};
+this is useful mainly if you expect to change the file, and you want
+Emacs processes that have already loaded it to keep working when the
+file changes.  You can do this globally, or for one source file by
+specifying a file-local binding for the variable.  One way to do that
+is by adding this string to the file's first line:
+
+@example
+-*-byte-compile-dynamic-docstrings: nil;-*-
+@end example
+
+@defvar byte-compile-dynamic-docstrings
+If this is non-@code{nil}, the byte compiler generates compiled files
+that are set up for dynamic loading of documentation strings.
+@end defvar
+
 @node Dynamic Loading
 @section Dynamic Loading of Individual Functions
 
@@ -477,13 +445,22 @@ to what @code{eval-when-compile} does.
   Byte compilation outputs all errors and warnings into the buffer
 @samp{*Compile-Log*}.  The messages include file names and line
 numbers that identify the location of the problem.  The usual Emacs
-commands for operating on compiler diagnostics work properly on
-these messages.
-
-  However, the warnings about functions that were used but not
-defined are always ``located'' at the end of the file, so these
-commands won't find the places they are really used.  To do that,
-you must search for the function names.
+commands for operating on compiler diagnostics work properly on these
+messages.
+
+  When an error is due to invalid syntax in the program, the byte
+compiler might get confused about the errors' exact location.  One way
+to investigate is to switch to the buffer @w{@samp{*Compiler Input*}}.
+(This buffer name starts with a space, so it does not show up in
+@kbd{M-x list-buffers}.)  This buffer contains the program being
+compiled, and point shows how far the byte compiler was able to read;
+the cause of the error might be nearby.  @xref{Syntax Errors}, for
+some tips for locating syntax errors.
+
+  When the byte compiler warns about functions that were used but not
+defined, it always reports the line number for the end of the file,
+not the locations where the missing functions were called.  To find
+the latter, you must search for the function names.
 
   You can suppress the compiler warning for calling an undefined
 function @var{func} by conditionalizing the function call on an
@@ -541,17 +518,16 @@ one you intend to suppress.
 @cindex byte-code function
 
   Byte-compiled functions have a special data type: they are
-@dfn{byte-code function objects}.
+@dfn{byte-code function objects}.  Whenever such an object appears as
+a function to be called, Emacs uses the byte-code interpreter to
+execute the byte-code.
 
-  Internally, a byte-code function object is much like a vector;
-however, the evaluator handles this data type specially when it appears
-as a function to be called.  The printed representation for a byte-code
-function object is like that for a vector, with an additional @samp{#}
-before the opening @samp{[}.
-
-  A byte-code function object must have at least four elements; there is
-no maximum number, but only the first six elements have any normal use.
-They are:
+  Internally, a byte-code function object is much like a vector; its
+elements can be accessed using @code{aref}.  Its printed
+representation is like that for a vector, with an additional @samp{#}
+before the opening @samp{[}.  It must have at least four elements;
+there is no maximum number, but only the first six elements have any
+normal use.  They are:
 
 @table @var
 @item arglist
@@ -588,7 +564,7 @@ representation.  It is the definition of the command
   [arg 1 forward-sexp]
   2
   254435
-  "p"]
+  "^p"]
 @end example
 
   The primitive way to create a byte-code object is with
@@ -604,10 +580,6 @@ function yourself, because if they are inconsistent, Emacs may crash
 when you call the function.  Always leave it to the byte compiler to
 create these objects; it makes the elements consistent (we hope).
 
-  You can access the elements of a byte-code object using @code{aref};
-you can also use @code{vconcat} to create a vector with the same
-elements.
-
 @node Disassembly
 @section Disassembled Byte-Code
 @cindex disassembled byte-code
diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi
index 3673f753a0a..c23c93300a6 100644
--- a/doc/lispref/control.texi
+++ b/doc/lispref/control.texi
@@ -948,8 +948,8 @@ The effect of @code{debug} here is only to prevent
 given error will invoke the debugger only if @code{debug-on-error} and
 the other usual filtering mechanisms say it should.  @xref{Error Debugging}.
 
-@defmac condition-case-no-debug var protected-form handlers@dots{}
-The macro @code{condition-case-no-debug} provides another way to
+@defmac condition-case-unless-debug var protected-form handlers@dots{}
+The macro @code{condition-case-unless-debug} provides another way to
 handle debugging of such forms.  It behaves exactly like
 @code{condition-case}, unless the variable @code{debug-on-error} is
 non-@code{nil}, in which case it does not handle any errors at all.
@@ -1131,9 +1131,9 @@ Here's the example at the beginning of this subsection rewritten using
 @defmac with-demoted-errors body@dots{}
 This macro is like a milder version of @code{ignore-errors}.  Rather
 than suppressing errors altogether, it converts them into messages.
-Use this form around code that is not expected to signal errors,
-but should be robust if one does occur.  Note that this macro
-uses @code{condition-case-no-debug} rather than @code{condition-case}.
+Use this form around code that is not expected to signal errors, but
+should be robust if one does occur.  Note that this macro uses
+@code{condition-case-unless-debug} rather than @code{condition-case}.
 @end defmac
 
 @node Error Symbols
diff --git a/doc/lispref/debugging.texi b/doc/lispref/debugging.texi
index cc92fc225f9..6e7d0078e07 100644
--- a/doc/lispref/debugging.texi
+++ b/doc/lispref/debugging.texi
@@ -6,41 +6,46 @@
 @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,
-depending on what you are doing with the program when the problem appears.
+  There are several ways to find and investigate problems in an Emacs
+Lisp program.
 
 @itemize @bullet
 @item
-If the problem occurs when you run the program, you can use a Lisp
-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.
+If a problem occurs when you run the program, you can use the built-in
+Emacs Lisp debugger to suspend the Lisp evaluator, and examine and/or
+alter its internal state.
 
 @item
-If the problem is syntactic, so that Lisp cannot even read the program,
-you can use the Emacs facilities for editing Lisp to localize it.
+You can use Edebug, a source-level debugger for Emacs Lisp.
 
 @item
-If the problem occurs when trying to compile the program with the byte
-compiler, you need to know how to examine the compiler's input buffer.
+If a syntactic problem is preventing Lisp from even reading the
+program, you can locate it using Lisp editing commands.
+
+@item
+You can look at the error and warning messages produced by the byte
+compiler when it compiles the program.  @xref{Compiler Errors}.
+
+@item
+You can use the Testcover package to perform coverage testing on the
+program.
+
+@item
+You can use the ERT package to write regression tests for the program.
+@xref{Top,the ERT manual,, ERT, ERT: Emacs Lisp Regression Testing}.
 @end itemize
 
+  Other useful tools for debugging input and output problems are the
+dribble file (@pxref{Terminal Input}) and the @code{open-termscript}
+function (@pxref{Terminal Output}).
+
 @menu
-* Debugger::            How the Emacs Lisp debugger is implemented.
+* Debugger::            A debugger for the Emacs Lisp evaluator.
 * Edebug::              A source-level Emacs Lisp debugger.
 * Syntax Errors::       How to find syntax errors.
 * Test Coverage::       Ensuring you have tested all branches in your code.
-* Compilation Errors::  How to find errors that show up in byte compilation.
 @end menu
 
-  Another useful debugging tool is the dribble file.  When a dribble
-file is open, Emacs copies all keyboard input characters to that file.
-Afterward, you can examine the file to find out what input was used.
-@xref{Terminal Input}.
-
-  For debugging problems in terminal descriptions, the
-@code{open-termscript} function can be useful.  @xref{Terminal Output}.
-
 @node Debugger
 @section The Lisp Debugger
 @cindex debugger for Emacs Lisp
@@ -76,25 +81,29 @@ 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 cause Lisp errors when invoked
-inappropriately, 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.)
+error.  Many commands signal Lisp errors when invoked inappropriately,
+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 kinds of errors call the debugger, except those listed in
 @code{debug-ignored-errors} (see below).  If it is @code{nil}, none
-call the debugger.  (Note that @code{eval-expression-debug-on-error}
-affects the setting of this variable in some cases; see below.)
+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.
+The value can also be a list of error conditions (@pxref{Signaling
+Errors}).  Then the debugger is called only for error conditions in
+this list (except those also listed in @code{debug-ignored-errors}).
+For example, if you set @code{debug-on-error} to the list
+@code{(void-variable)}, the debugger is only called for errors about a
+variable that has no value.
+
+Note that @code{eval-expression-debug-on-error} overrides this
+variable in some cases; see below.
 
 When this variable is non-@code{nil}, Emacs does not create an error
 handler around process filter functions and sentinels.  Therefore,
@@ -102,52 +111,50 @@ errors in these functions also invoke the debugger.  @xref{Processes}.
 @end defopt
 
 @defopt debug-ignored-errors
-This variable specifies certain kinds of errors that should not enter
-the debugger.  Its value is a list of error condition symbols and/or
-regular expressions.  If the error has any of those condition symbols,
-or if the error message matches any of the regular expressions, then
-that error does not enter the debugger, regardless of the value of
-@code{debug-on-error}.
-
-The normal value of this variable lists several errors that happen often
-during editing but rarely result from bugs in Lisp programs.  However,
-``rarely'' is not ``never''; if your program fails with an error that
-matches this list, you will need to change this list in order to debug
+This variable specifies errors which should not enter the debugger,
+regardless of the value of @code{debug-on-error}.  Its value is a list
+of error condition symbols and/or regular expressions.  If the error
+has any of those condition symbols, or if the error message matches
+any of the regular expressions, then that error does not enter the
+debugger.
+
+The normal value of this variable lists several errors that happen
+often during editing but rarely result from bugs in Lisp programs.
+However, ``rarely'' is not ``never''; if your program fails with an
+error that matches this list, you may try changing this list to debug
 the error.  The easiest way is usually to set
 @code{debug-ignored-errors} to @code{nil}.
 @end defopt
 
 @defopt eval-expression-debug-on-error
-If this variable has a non-@code{nil} value, then
-@code{debug-on-error} is set to @code{t} when evaluating with the
-command @code{eval-expression}.  If
-@code{eval-expression-debug-on-error} is @code{nil}, then the value of
-@code{debug-on-error} is not changed.  @xref{Lisp Eval,, Evaluating
+If this variable has a non-@code{nil} value (the default), running the
+command @code{eval-expression} causes @code{debug-on-error} to be
+temporarily bound to to @code{t}.  @xref{Lisp Eval,, Evaluating
 Emacs-Lisp Expressions, emacs, The GNU Emacs Manual}.
-@end defopt
 
-@defopt debug-on-signal
-Normally, errors that are caught by @code{condition-case} never run the
-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} 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
-criteria specified by the values of @code{debug-on-error} and
-@code{debug-ignored-errors}.
-
-@strong{Warning:} This variable is strong medicine!  Various parts of
-Emacs handle errors in the normal course of affairs, and you may not
-even realize that errors happen there.  If you set
-@code{debug-on-signal} to a non-@code{nil} value, those errors will
-enter the debugger.
-
-@strong{Warning:} @code{debug-on-signal} has no effect when
-@code{debug-on-error} is @code{nil}.
+If @code{eval-expression-debug-on-error} is @code{nil}, then the value
+of @code{debug-on-error} is not changed during @code{eval-expression}.
 @end defopt
 
+@defvar debug-on-signal
+Normally, errors caught by @code{condition-case} never invoke the
+debugger.  The @code{condition-case} gets a chance to handle the error
+before the debugger gets a chance.
+
+If you change @code{debug-on-signal} to a non-@code{nil} value, the
+debugger gets the first chance at every error, regardless of the
+presence of @code{condition-case}.  (To invoke the debugger, the error
+must still fulfill the criteria specified by @code{debug-on-error} and
+@code{debug-ignored-errors}.)
+
+@strong{Warning:} Setting this variable to non-@code{nil} may have
+annoying effects.  Various parts of Emacs catch errors in the normal
+course of affairs, and you may not even realize that errors happen
+there.  If you need to debug code wrapped in @code{condition-case},
+consider using @code{condition-case-unless-debug} (@pxref{Handling
+Errors}).
+@end defvar
+
 @defopt debug-on-event
 If you set @code{debug-on-event} to a special event (@pxref{Special
 Events}), Emacs will try to enter the debugger as soon as it receives
@@ -171,27 +178,26 @@ init file.
 @cindex stopping an infinite loop
 
   When a program loops infinitely and fails to return, your first
-problem is to stop the loop.  On most operating systems, you can do this
-with @kbd{C-g}, which causes a @dfn{quit}.
+problem is to stop the loop.  On most operating systems, you can do
+this with @kbd{C-g}, which causes a @dfn{quit}.  @xref{Quitting}.
 
   Ordinary quitting gives no information about why the program was
 looping.  To get more information, you can set the variable
-@code{debug-on-quit} to non-@code{nil}.  Quitting with @kbd{C-g} is not
-considered an error, and @code{debug-on-error} has no effect on the
-handling of @kbd{C-g}.  Likewise, @code{debug-on-quit} has no effect on
-errors.
+@code{debug-on-quit} to non-@code{nil}.  Once you have the debugger
+running in the middle of the infinite loop, you can proceed from the
+debugger using the stepping commands.  If you step through the entire
+loop, you may get enough information to solve the problem.
 
-  Once you have the debugger running in the middle of the infinite loop,
-you can proceed from the debugger using the stepping commands.  If you
-step through the entire loop, you will probably get enough information
-to solve the problem.
+  Quitting with @kbd{C-g} is not considered an error, and
+@code{debug-on-error} has no effect on the handling of @kbd{C-g}.
+Likewise, @code{debug-on-quit} has no effect on errors.
 
 @defopt debug-on-quit
-This variable determines whether the debugger is called when @code{quit}
-is signaled and not handled.  If @code{debug-on-quit} is non-@code{nil},
-then the debugger is called whenever you quit (that is, type @kbd{C-g}).
-If @code{debug-on-quit} is @code{nil}, then the debugger is not called
-when you quit.  @xref{Quitting}.
+This variable determines whether the debugger is called when
+@code{quit} is signaled and not handled.  If @code{debug-on-quit} is
+non-@code{nil}, then the debugger is called whenever you quit (that
+is, type @kbd{C-g}).  If @code{debug-on-quit} is @code{nil} (the
+default), then the debugger is not called when you quit.
 @end defopt
 
 @node Function Debugging
@@ -337,8 +343,8 @@ that exiting that frame will call the debugger again.  This is useful
 for examining the return value of a function.
 
   If a function name is underlined, that means the debugger knows
-where its source code is located.  You can click @kbd{Mouse-2} on that
-name, or move to it and type @key{RET}, to visit the source code.
+where its source code is located.  You can click with the mouse on
+that name, or move to it and type @key{RET}, to visit the source code.
 
   The debugger itself must be run byte-compiled, since it makes
 assumptions about how many stack frames are used for the debugger
@@ -364,14 +370,10 @@ to step through a primitive function.
 
 @table @kbd
 @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 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
-debugger was entered because of an error.
+Exit the debugger and continue execution.  This resumes execution of
+the program as if the debugger had never been entered (aside from any
+side-effects that you caused by changing variable values or data
+structures while inside the debugger).
 
 @item d
 Continue execution, but enter the debugger the next time any Lisp
@@ -790,29 +792,3 @@ never return.  If it ever does return, you get a run-time error.
   Edebug also has a coverage testing feature (@pxref{Coverage
 Testing}).  These features partly duplicate each other, and it would
 be cleaner to combine them.
-
-@node Compilation Errors
-@section Debugging Problems in Compilation
-@cindex debugging byte compilation problems
-
-  When an error happens during byte compilation, it is normally due to
-invalid syntax in the program you are compiling.  The compiler prints a
-suitable error message in the @samp{*Compile-Log*} buffer, and then
-stops.  The message may state a function name in which the error was
-found, or it may not.  Either way, here is how to find out where in the
-file the error occurred.
-
-  What you should do is switch to the buffer @w{@samp{ *Compiler Input*}}.
-(Note that the buffer name starts with a space, so it does not show
-up in @kbd{M-x list-buffers}.)  This buffer contains the program being
-compiled, and point shows how far the byte compiler was able to read.
-
-  If the error was due to invalid Lisp syntax, point shows exactly where
-the invalid syntax was @emph{detected}.  The cause of the error is not
-necessarily near by!  Use the techniques in the previous section to find
-the error.
-
-  If the error was detected while compiling a form that had been read
-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.
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index d5870fd3abb..ae8a5fde29f 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -3380,12 +3380,11 @@ indicator.
 Used for truncation and continuation lines.
 
 @item @code{up}, @code{down}, @code{top}, @code{bottom}, @code{top-bottom}
-Used to indicate buffer boundaries when
-@code{indicate-buffer-boundaries} is non-@code{nil}: @code{up} and
-@code{down} indicate a buffer boundary lying above or below the window
-edge; @code{top} and @code{bottom} indicate the topmost and bottommost
-buffer text line; and @code{top-bottom} indicates where there is just
-one line of text in the buffer.
+Used when @code{indicate-buffer-boundaries} is non-@code{nil}:
+@code{up} and @code{down} indicate a buffer boundary lying above or
+below the window edge; @code{top} and @code{bottom} indicate the
+topmost and bottommost buffer text line; and @code{top-bottom}
+indicates where there is just one line of text in the buffer.
 
 @item @code{empty-line}
 Used to indicate empty lines when @code{indicate-empty-lines} is
@@ -3407,24 +3406,9 @@ are used to indicate that the last text line has no final newline.
 Alternatively, @var{bitmaps} may be a single symbol which is used in
 both left and right fringes.
 
-  The standard symbols for fringe bitmaps are:
-
-@example
-left-arrow right-arrow up-arrow down-arrow
-left-curly-arrow right-curly-arrow
-left-triangle right-triangle
-top-left-angle top-right-angle
-bottom-left-angle bottom-right-angle
-left-bracket right-bracket
-filled-rectangle hollow-rectangle
-filled-square hollow-square
-vertical-bar horizontal-bar
-empty-line question-mark
-@end example
-
-@noindent
-In addition, @code{nil} represents the empty bitmap (i.e.@: an
-indicator that is not shown).
+  @xref{Fringe Bitmaps}, for a list of standard bitmap symbols and how
+to define your own.  In addition, @code{nil} represents the empty
+bitmap (i.e.@: an indicator that is not shown).
 
   When @code{fringe-indicator-alist} has a buffer-local value, and
 there is no bitmap defined for a logical indicator, or the bitmap is
@@ -3442,16 +3426,6 @@ cursor in the right fringe instead of using two lines.  Different
 bitmaps are used to represent the cursor in the fringe depending on
 the current buffer's cursor type.
 
-@table @asis
-@item Logical cursor types:
-@code{box} , @code{hollow}, @code{bar},
-@code{hbar}, @code{hollow-small}.
-@end table
-
-The @code{hollow-small} type is used instead of @code{hollow} when the
-normal @code{hollow-rectangle} bitmap is too tall to fit on a specific
-display line.
-
 @defopt overflow-newline-into-fringe
 If this is non-@code{nil}, lines exactly as wide as the window (not
 counting the final newline character) are not continued.  Instead,
@@ -3462,24 +3436,31 @@ fringe.
 @defvar fringe-cursor-alist
 This variable specifies the mapping from logical cursor type to the
 actual fringe bitmaps displayed in the right fringe.  The value is an
-alist where each element @code{(@var{cursor} . @var{bitmap})} specifies
-the fringe bitmaps used to display a specific logical cursor type in
-the fringe.  Here, @var{cursor} specifies the logical cursor type and
-@var{bitmap} is a symbol specifying the fringe bitmap to be displayed
-for that logical cursor type.
+alist where each element has the form @code{(@var{cursor-type}
+. @var{bitmap})}, which means to use the fringe bitmap @var{bitmap} to
+display cursors of type @var{cursor-type}.
+
+Each @var{cursor-type} should be one of @code{box}, @code{hollow},
+@code{bar}, @code{hbar}, or @code{hollow-small}.  The first four have
+the same meanings as in the @code{cursor-type} frame parameter
+(@pxref{Cursor Parameters}).  The @code{hollow-small} type is used
+instead of @code{hollow} when the normal @code{hollow-rectangle}
+bitmap is too tall to fit on a specific display line.
+
+Each @var{bitmap} should be a symbol specifying the fringe bitmap to
+be displayed for that logical cursor type.
+@iftex
+See the next subsection for details.
+@end iftex
+@ifnottex
+@xref{Fringe Bitmaps}.
+@end ifnottex
 
 When @code{fringe-cursor-alist} has a buffer-local value, and there is
 no bitmap defined for a cursor type, the corresponding value from the
 default value of @code{fringes-indicator-alist} is used.
 @end defvar
 
-Standard bitmaps for displaying the cursor in right fringe:
-@example
-filled-rectangle hollow-rectangle filled-square hollow-square
-vertical-bar horizontal-bar
-@end example
-
-
 @node Fringe Bitmaps
 @subsection Fringe Bitmaps
 @cindex fringe bitmaps
@@ -3487,22 +3468,74 @@ vertical-bar horizontal-bar
 
   The @dfn{fringe bitmaps} are the actual bitmaps which represent the
 logical fringe indicators for truncated or continued lines, buffer
-boundaries, overlay arrow, etc.  Fringe bitmap symbols have their own
-name space.  The fringe bitmaps are shared by all frames and windows.
-You can redefine the built-in fringe bitmaps, and you can define new
-fringe bitmaps.
-
-  The way to display a bitmap in the left or right fringes for a given
-line in a window is by specifying the @code{display} property for one
-of the characters that appears in it.  Use a display specification of
-the form @code{(left-fringe @var{bitmap} [@var{face}])} or
-@code{(right-fringe @var{bitmap} [@var{face}])} (@pxref{Display
-Property}).  Here, @var{bitmap} is a symbol identifying the bitmap you
-want, and @var{face} (which is optional) is the name of the face whose
-colors should be used for displaying the bitmap, instead of the
-default @code{fringe} face.  @var{face} is automatically merged with
-the @code{fringe} face, so normally @var{face} need only specify the
-foreground color for the bitmap.
+boundaries, overlay arrows, etc.  Each bitmap is represented by a
+symbol.
+@iftex
+These symbols are referred to by the variables
+@code{fringe-indicator-alist} and @code{fringe-cursor-alist},
+described in the previous subsections.
+@end iftex
+@ifnottex
+These symbols are referred to by the variable
+@code{fringe-indicator-alist}, which maps fringe indicators to bitmaps
+(@pxref{Fringe Indicators}), and the variable
+@code{fringe-cursor-alist}, which maps fringe cursors to bitmaps
+(@pxref{Fringe Cursors}).
+@end ifnottex
+
+  Lisp programs can also directly display a bitmap in the left or
+right fringe, by using a @code{display} property for one of the
+characters appearing in the line (@pxref{Other Display Specs}).  Such
+a display specification has the form
+
+@example
+(left-fringe @var{bitmap} [@var{face}])
+@end example
+
+@noindent
+or
+
+@example
+(right-fringe @var{bitmap} [@var{face}])
+@end example
+
+@noindent
+The symbol @var{bitmap} identifies the bitmap to display.  The
+optional @var{face} names a face whose foreground color is used to
+display the bitmap; this face is automatically merged with the
+@code{fringe} face.
+
+  Here is a list of the standard fringe bitmaps defined in Emacs, and
+how they are currently used in Emacs (via
+@code{fringe-indicator-alist} and @code{fringe-cursor-alist}):
+
+@table @asis
+@item @code{left-arrow}, @code{right-arrow}
+Used to indicate truncated lines.
+
+@item @code{left-curly-arrow}, @code{right-curly-arrow}
+Used to indicate continued lines.
+
+@item @code{right-triangle}, @code{left-triangle}
+The former is used by overlay arrows.  The latter is unused.
+
+@item @code{up-arrow}, @code{down-arrow}, @code{top-left-angle} @code{top-right-angle}
+@itemx @code{bottom-left-angle}, @code{bottom-right-angle}
+@itemx @code{top-right-angle}, @code{top-left-angle}
+@itemx @code{left-bracket}, @code{right-bracket}, @code{top-right-angle}, @code{top-left-angle}
+Used to indicate buffer boundaries.
+
+@item @code{filled-rectangle}, @code{hollow-rectangle}
+@itemx @code{filled-square}, @code{hollow-square}
+@itemx @code{vertical-bar}, @code{horizontal-bar}
+Used for different types of fringe cursors.
+
+@item @code{empty-line}, @code{question-mark}
+Unused.
+@end table
+
+@noindent
+The next subsection describes how to define your own fringe bitmaps.
 
 @defun fringe-bitmaps-at-pos &optional pos window
 This function returns the fringe bitmaps of the display line
diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index f69823101d0..42c3613dd0b 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -548,17 +548,14 @@ Advising Emacs Lisp Functions
 * Preactivation::           Preactivation is a way of speeding up the
                               loading of compiled advice.
 * Argument Access in Advice:: How advice can access the function's arguments.
-* Advising Primitives::     Accessing arguments when advising a primitive.
 * Combined Definition::     How advice is implemented.
 
 Debugging Lisp Programs
 
-* Debugger::                How the Emacs Lisp debugger is implemented.
+* Debugger::                A debugger for the Emacs Lisp evaluator.
 * Edebug::                  A source-level Emacs Lisp debugger.
 * Syntax Errors::           How to find syntax errors.
 * Test Coverage::           Ensuring you have tested all branches in your code.
-* Compilation Errors::      How to find errors that show up in
-                              byte compilation.
 
 The Lisp Debugger
 
@@ -1061,7 +1058,7 @@ Text
 * Registers::               How registers are implemented.  Accessing
                               the text or position stored in a register.
 * Base 64::                 Conversion to or from base 64 encoding.
-* MD5 Checksum::            Compute the MD5 "message digest"/"checksum".
+* Checksum/Hash::           Computing "message digests"/"checksums"/"hashes".
 * Atomic Changes::          Installing several buffer changes "atomically".
 * Change Hooks::            Supplying functions to be run when text is changed.
 
diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index 087eb6ef1db..cf093ba36cb 100644
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -2862,24 +2862,21 @@ is a good way to come up with one.
 @end defun
 
 @defopt remote-file-name-inhibit-cache
-Whether to use the remote file-name cache for read access.
-
-File attributes of remote files are cached for better performance.  If
-they are changed out of Emacs' control, the cached values become
+The attributes of remote files can be cached for better performance.  If
+they are changed outside of Emacs's control, the cached values become
 invalid, and must be reread.
 
-When set to @code{nil}, cached values are always used.  This shall be
-set with care.  When set to @code{t}, cached values are never used.
-ALthough this is the safest value, it could result in performance
-degradation.
+When this variable is set to @code{nil}, cached values are never
+expired.  Use this setting with caution, only if you are sure nothing
+other than Emacs ever changes the remote files.  If it is set to
+@code{t}, cached values are never used.  This is the safest value, but
+could result in performance degradation.
 
 A compromise is to set it to a positive number.  This means that
 cached values are used for that amount of seconds since they were
-cached.
-
-In case a remote file is checked regularly, it might be reasonable to
-let-bind this variable to a value less then the time period between
-two checks.  Example:
+cached.  If a remote file is checked regularly, it might be a good
+idea to let-bind this variable to a value less than the time period
+between consecutive checks.  For example:
 
 @example
 (defun display-time-file-nonempty-p (file)
diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi
index 0b822751df6..3c2fa60248e 100644
--- a/doc/lispref/loading.texi
+++ b/doc/lispref/loading.texi
@@ -10,9 +10,10 @@
 @cindex library
 @cindex Lisp library
 
-  Loading a file of Lisp code means bringing its contents into the Lisp
-environment in the form of Lisp objects.  Emacs finds and opens the
-file, reads the text, evaluates each form, and then closes the file.
+  Loading a file of Lisp code means bringing its contents into the
+Lisp environment in the form of Lisp objects.  Emacs finds and opens
+the file, reads the text, evaluates each form, and then closes the
+file.  Such a file is also called a @dfn{Lisp library}.
 
   The load functions evaluate all the expressions in a file just
 as the @code{eval-buffer} function evaluates all the
@@ -29,11 +30,6 @@ into a buffer and evaluated there.  (Indeed, most code is tested this
 way.)  Most often, the forms are function definitions and variable
 definitions.
 
-  A file containing Lisp code is often called a @dfn{library}.  Thus,
-the ``Rmail library'' is a file containing code for Rmail mode.
-Similarly, a ``Lisp library directory'' is a directory of files
-containing Lisp code.
-
 @menu
 * How Programs Do Loading:: The @code{load} function and others.
 * Load Suffixes::           Details about the suffixes that @code{load} tries.
@@ -88,8 +84,8 @@ this case, you must specify the precise file name you want, except
 that, if Auto Compression mode is enabled, @code{load} will still use
 @code{jka-compr-load-suffixes} to find compressed versions.  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.
+@var{nosuffix}, you can prevent file names like @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
@@ -238,73 +234,37 @@ it skips the latter group.
   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
+@defvar 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).
-@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/epaths.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};
-@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
-a @code{csh} @file{.login} file:
-
-@smallexample
-setenv EMACSLOADPATH .:/user/bil/emacs:/usr/local/share/emacs/20.3/lisp
-@end smallexample
+@end defvar
 
-  Here is how to set it using @code{sh}:
+  Each time Emacs starts up, it sets up the value of @code{load-path}
+in several steps.  First, it initializes @code{load-path} to the
+directories specified by the environment variable @env{EMACSLOADPATH},
+if that exists.  The syntax of @env{EMACSLOADPATH} is the same as used
+for @code{PATH}; directory names are separated by @samp{:} (or
+@samp{;}, on some operating systems), and @samp{.} stands for the
+current default directory.  Here is an example of how to set
+@env{EMACSLOADPATH} variable from @command{sh}:
 
 @smallexample
 export EMACSLOADPATH
-EMACSLOADPATH=.:/user/bil/emacs:/usr/local/share/emacs/20.3/lisp
+EMACSLOADPATH=/home/foo/.emacs.d/lisp:/opt/emacs/lisp
 @end smallexample
 
-  Here is an example of code you can place in your init file (@pxref{Init
-File}) to add several directories to the front of your default
-@code{load-path}:
+@noindent
+Here is how to set it from @code{csh}:
 
 @smallexample
-@group
-(setq load-path
-      (append (list nil "/user/bil/emacs"
-                    "/usr/local/lisplib"
-                    "~/emacs")
-              load-path))
-@end group
+setenv EMACSLOADPATH /home/foo/.emacs.d/lisp:/opt/emacs/lisp
 @end smallexample
 
-@c Wordy to rid us of an overfull hbox.  --rjc 15mar92
-@noindent
-In this example, the path searches the current working directory first,
-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
-@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
-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}.
-
-  The default value of @code{load-path}, when running an Emacs which has
-been installed on the system, includes two special directories (and
-their subdirectories as well):
+  If @env{EMACSLOADPATH} is not set (which is usually the case), Emacs
+initializes @code{load-path} with the following two directories:
 
 @smallexample
 "/usr/local/share/emacs/@var{version}/site-lisp"
@@ -319,33 +279,42 @@ and
 
 @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
-updating for incompatible changes in Emacs; sometimes they depend on
-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} or @file{CVS} 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.
+version; the second is for locally installed packages meant for use
+with all installed Emacs versions.
 
   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
+executable that has not been formally installed---Emacs puts two more
+directories in @code{load-path}.  These are the @code{lisp} and
+@code{site-lisp} subdirectories of the main build directory.  (Both
 are represented as absolute file names.)
 
+  Next, Emacs ``expands'' the initial list of directories in
+@code{load-path} by adding the subdirectories of those directories.
+Both immediate subdirectories and subdirectories multiple levels down
+are added.  But it excludes subdirectories whose names do not start
+with a letter or digit, and subdirectories named @file{RCS} or
+@file{CVS}, and subdirectories containing a file named
+@file{.nosearch}.
+
+  Next, Emacs adds any extra load directory that you specify using the
+@samp{-L} command-line option (@pxref{Action Arguments,,,emacs, The
+GNU Emacs Manual}).  It also adds the directories where optional
+packages are installed, if any (@pxref{Packaging Basics}).
+
+  It is common to add code to one's init file (@pxref{Init File}) to
+add one or more directories to @code{load-path}.  For example:
+
+@smallexample
+(push "~/.emacs.d/lisp" load-path)
+@end smallexample
+
+  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.
+
 @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
@@ -401,30 +370,26 @@ 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}.
 
-  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.
-
-  In most Emacs Lisp programs, the fact that non-@acronym{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{-*-unibyte: t;-*-} in a
-comment on the file's first line.  With that designator, the file will
-unconditionally be interpreted as unibyte, even in an ordinary
-multibyte Emacs session.  This can matter when making keybindings to
-non-@acronym{ASCII} characters written as @code{?v@var{literal}}.
+  In most Emacs Lisp programs, the fact that non-@acronym{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{-*-unibyte: t;-*-} in a comment on the file's first line.  With
+that designator, the file will unconditionally be interpreted as
+unibyte, even in an ordinary multibyte Emacs session.  This can matter
+when making keybindings to non-@acronym{ASCII} characters written as
+@code{?v@var{literal}}.
 
 @node Autoload
 @section Autoload
 @cindex autoload
 
-  The @dfn{autoload} facility allows you to make a function or macro
-known in Lisp, but put off loading the file that defines it.  The first
-call to the function automatically reads the proper file to install the
-real definition and other associated code, then runs the real definition
-as if it had been loaded all along.
+  The @dfn{autoload} facility allows you to register the existence of
+a function or macro, but put off loading the file that defines it.
+The first call to the function automatically reads the proper file, in
+order to install the real definition and other associated code, then
+runs the real definition as if it had been loaded all along.
 
   There are two ways to set up an autoloaded function: by calling
 @code{autoload}, and by writing a special ``magic'' comment in the
diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi
index 445cb800d33..995a4d89352 100644
--- a/doc/lispref/objects.texi
+++ b/doc/lispref/objects.texi
@@ -1323,11 +1323,11 @@ with the name of the subroutine.
 @node Byte-Code Type
 @subsection Byte-Code Function Type
 
-The byte compiler produces @dfn{byte-code function objects}.
-Internally, a byte-code function object is much like a vector; however,
-the evaluator handles this data type specially when it appears as a
-function to be called.  @xref{Byte Compilation}, for information about
-the byte compiler.
+@dfn{Byte-code function objects} are produced by byte-compiling Lisp
+code (@pxref{Byte Compilation}).  Internally, a byte-code function
+object is much like a vector; however, the evaluator handles this data
+type specially when it appears in a function call.  @xref{Byte-Code
+Objects}.
 
 The printed representation and read syntax for a byte-code function
 object is like that for a vector, with an additional @samp{#} before the
diff --git a/doc/lispref/streams.texi b/doc/lispref/streams.texi
index 36691624405..1628f32aa29 100644
--- a/doc/lispref/streams.texi
+++ b/doc/lispref/streams.texi
@@ -266,12 +266,6 @@ 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}.
 
-@defun get-file-char
-This function is used internally as an input stream to read from the
-input file opened by the function @code{load}.  Don't use this function
-yourself.
-@end defun
-
 @node Input Functions
 @section Input Functions
 
@@ -702,9 +696,8 @@ The default is @code{t}, meaning display in the echo area.
 
 @defvar print-quoted
 If this is non-@code{nil}, that means to print quoted forms using
-abbreviated reader syntax.  @code{(quote foo)} prints as @code{'foo},
-@code{(function foo)} as @code{#'foo}, and backquoted forms print
-using modern backquote syntax.
+abbreviated reader syntax, e.g.@: @code{(quote foo)} prints as
+@code{'foo}, and @code{(function foo)} as @code{#'foo}.
 @end defvar
 
 @defvar print-escape-newlines
diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index 8e7434de2ed..416bfef4a60 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -56,7 +56,7 @@ the character after point.
 * Registers::        How registers are implemented.  Accessing the text or
                        position stored in a register.
 * Base 64::          Conversion to or from base 64 encoding.
-* MD5 Checksum::     Compute the MD5 "message digest"/"checksum".
+* Checksum/Hash::    Computing "message digests"/"checksums"/"hashes".
 * Parsing HTML::     Parsing HTML and XML.
 * Atomic Changes::   Installing several buffer changes "atomically".
 * Change Hooks::     Supplying functions to be run when text is changed.
@@ -4071,9 +4071,11 @@ decoded text.
 The decoding functions ignore newline characters in the encoded text.
 @end defun
 
-@node MD5 Checksum
-@section MD5 Checksum
+@node Checksum/Hash
+@section Checksum/Hash
 @cindex MD5 checksum
+@cindex hashing, secure
+@cindex SHA-1
 @cindex message digest computation
 
   MD5 cryptographic checksums, or @dfn{message digests}, are 128-bit
@@ -4084,7 +4086,7 @@ RFC@footnote{
 For an explanation of what is an RFC, see the footnote in @ref{Base
 64}.
 }1321.  This section describes the Emacs facilities for computing
-message digests.
+message digests and other forms of ``secure hash''.
 
 @defun md5 object &optional start end coding-system noerror
 This function returns the MD5 message digest of @var{object}, which
@@ -4119,6 +4121,16 @@ using the specified or chosen coding system.  However, if
 coding instead.
 @end defun
 
+@defun secure-hash algorithm object &optional start end binary
+This function provides a general interface to a variety of secure
+hashing algorithms.  As well as the MD5 algorithm, it supports SHA-1,
+SHA-2, SHA-224, SHA-256, SHA-384 and SHA-512.  The argument
+@var{algorithm} is a symbol stating which hash to compute.  The
+arguments @var{object}, @var{start}, and @var{end} are as for the
+@code{md5} function.  If the optional argument @var{binary} is
+non-@code{nil}, returns a string in binary form.
+@end defun
+
 @node Parsing HTML
 @section Parsing HTML
 @cindex parsing html
diff --git a/doc/lispref/vol1.texi b/doc/lispref/vol1.texi
index 0f4a4447ed3..cc96726745f 100644
--- a/doc/lispref/vol1.texi
+++ b/doc/lispref/vol1.texi
@@ -568,17 +568,14 @@ Advising Emacs Lisp Functions
 * Preactivation::           Preactivation is a way of speeding up the
                               loading of compiled advice.
 * Argument Access in Advice:: How advice can access the function's arguments.
-* Advising Primitives::     Accessing arguments when advising a primitive.
 * Combined Definition::     How advice is implemented.
 
 Debugging Lisp Programs
 
-* Debugger::                How the Emacs Lisp debugger is implemented.
+* Debugger::                A debugger for the Emacs Lisp evaluator.
 * Edebug::                  A source-level Emacs Lisp debugger.
 * Syntax Errors::           How to find syntax errors.
 * Test Coverage::           Ensuring you have tested all branches in your code.
-* Compilation Errors::      How to find errors that show up in
-                              byte compilation.
 
 The Lisp Debugger
 
@@ -1082,7 +1079,7 @@ Text
 * Registers::               How registers are implemented.  Accessing
                               the text or position stored in a register.
 * Base 64::                 Conversion to or from base 64 encoding.
-* MD5 Checksum::            Compute the MD5 "message digest"/"checksum".
+* Checksum/Hash::           Computing "message digests"/"checksums"/"hashes".
 * Atomic Changes::          Installing several buffer changes "atomically".
 * Change Hooks::            Supplying functions to be run when text is changed.
 
diff --git a/doc/lispref/vol2.texi b/doc/lispref/vol2.texi
index 241728fd1d2..33246cb567d 100644
--- a/doc/lispref/vol2.texi
+++ b/doc/lispref/vol2.texi
@@ -567,17 +567,14 @@ Advising Emacs Lisp Functions
 * Preactivation::           Preactivation is a way of speeding up the
                               loading of compiled advice.
 * Argument Access in Advice:: How advice can access the function's arguments.
-* Advising Primitives::     Accessing arguments when advising a primitive.
 * Combined Definition::     How advice is implemented.
 
 Debugging Lisp Programs
 
-* Debugger::                How the Emacs Lisp debugger is implemented.
+* Debugger::                A debugger for the Emacs Lisp evaluator.
 * Edebug::                  A source-level Emacs Lisp debugger.
 * Syntax Errors::           How to find syntax errors.
 * Test Coverage::           Ensuring you have tested all branches in your code.
-* Compilation Errors::      How to find errors that show up in
-                              byte compilation.
 
 The Lisp Debugger
 
@@ -1081,7 +1078,7 @@ Text
 * Registers::               How registers are implemented.  Accessing
                               the text or position stored in a register.
 * Base 64::                 Conversion to or from base 64 encoding.
-* MD5 Checksum::            Compute the MD5 "message digest"/"checksum".
+* Checksum/Hash::           Computing "message digests"/"checksums"/"hashes".
 * Atomic Changes::          Installing several buffer changes "atomically".
 * Change Hooks::            Supplying functions to be run when text is changed.