ustream

32 files changed, 968 insertions, 751 deletions

diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog
index 871422f9bfe..ab4161c75b8 100644
--- a/doc/emacs/ChangeLog
+++ b/doc/emacs/ChangeLog
@@ -1,3 +1,23 @@
+2012-02-05  Glenn Morris  <rgm@gnu.org>
+
+        * trouble.texi (Checklist): Mention debug-on-event.
+
+        * maintaining.texi (Maintaining): Add cross-ref to ERT.
+
+2012-02-04  Glenn Morris  <rgm@gnu.org>
+
+        * macos.texi (Customization options specific to Mac OS / GNUstep):
+        New subsection.
+
+        * display.texi (Colors): Mention list-colors-sort.
+
+        * files.texi (File Conveniences): Mention image animation.
+
+2012-01-31  Chong Yidong  <cyd@gnu.org>
+
+        * windows.texi (Split Window): C-mouse-2 doesn't work on GTK+
+        scroll bars (Bug#10666).
+
 2012-01-28  Chong Yidong  <cyd@gnu.org>
 
         * files.texi (Filesets): Fix typos.
@@ -8,7 +28,7 @@
 
         * buffers.texi (Select Buffer): Clarify explanation of switching
         to new buffers.  Fix description of next-buffer and
-        previous-buffer (Bug#10334).
+        previous-buffer (Bug#10334).
         (Misc Buffer): Add xref to View Mode.
 
         * text.texi (Fill Commands): Fix description of
diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi
index 6e69b723204..8159b8cc6aa 100644
--- a/doc/emacs/display.texi
+++ b/doc/emacs/display.texi
@@ -524,16 +524,18 @@ specify a color for a face---for instance, when customizing the face
 or an @dfn{RGB triplet}.
 
 @findex list-colors-display
+@vindex list-colors-sort
   A color name is a pre-defined name, such as @samp{dark orange} or
 @samp{medium sea green}.  To view a list of color names, type @kbd{M-x
-list-colors-display}.  If you run this command on a graphical display,
-it shows the full range of color names known to Emacs (these are the
-standard X11 color names, defined in X's @file{rgb.txt} file).  If you
-run the command on a text-only terminal, it shows only a small subset
-of colors that can be safely displayed on such terminals.  However,
-Emacs understands X11 color names even on text-only terminals; if a
-face is given a color specified by an X11 color name, it is displayed
-using the closest-matching terminal color.
+list-colors-display}.  To control the order in which colors are shown,
+customize @code{list-colors-sort}.  If you run this command on a
+graphical display, it shows the full range of color names known to Emacs
+(these are the standard X11 color names, defined in X's @file{rgb.txt}
+file).  If you run the command on a text-only terminal, it shows only a
+small subset of colors that can be safely displayed on such terminals.
+However, Emacs understands X11 color names even on text-only terminals;
+if a face is given a color specified by an X11 color name, it is
+displayed using the closest-matching terminal color.
 
   An RGB triplet is a string of the form @samp{#RRGGBB}.  Each of the
 R, G, and B components is a hexadecimal number specifying the
diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi
index 081614aa3b9..b2eb68d2812 100644
--- a/doc/emacs/files.texi
+++ b/doc/emacs/files.texi
@@ -1907,7 +1907,10 @@ point.  Partial Completion mode offers other features extending
 
 @findex image-mode
 @findex image-toggle-display
+@findex image-toggle-animation
 @cindex images, viewing
+@cindex image animation
+@cindex animated images
   Visiting image files automatically selects Image mode.  This major
 mode allows you to toggle between displaying the file as an image in
 the Emacs buffer, and displaying its underlying text representation,
@@ -1915,7 +1918,12 @@ using the command @kbd{C-c C-c} (@code{image-toggle-display}).  This
 works only when Emacs can display the specific image type.  If the
 displayed image is wider or taller than the frame, the usual point
 motion keys (@kbd{C-f}, @kbd{C-p}, and so forth) cause different parts
-of the image to be displayed.
+of the image to be displayed.  If the image can be animated, then
+the command @kbd{RET} (@code{image-toggle-animation}), will start (or
+stop) animating it.  Animation plays once, unless the option
+@code{image-animate-loop} is non-@code{nil}.  Currently, Emacs only
+supports animated GIF files (@pxref{Animated Images,,, elisp, The Emacs
+Lisp Reference Manual}).
 
 @findex thumbs-mode
 @findex mode, thumbs
diff --git a/doc/emacs/frames.texi b/doc/emacs/frames.texi
index 1adeee480a6..38ee620dbd5 100644
--- a/doc/emacs/frames.texi
+++ b/doc/emacs/frames.texi
@@ -370,7 +370,6 @@ side-by-side windows with the boundary running through the click
 position (@pxref{Split Window}).
 @end table
 
-@kindex C-Mouse-2 @r{(scroll bar)}
 @kindex Mouse-1 @r{(scroll bar)}
   Furthermore, by clicking and dragging @kbd{Mouse-1} on the divider
 between two side-by-side mode lines, you can move the vertical
diff --git a/doc/emacs/macos.texi b/doc/emacs/macos.texi
index a36dc0cbcc5..e6d936e8e9f 100644
--- a/doc/emacs/macos.texi
+++ b/doc/emacs/macos.texi
@@ -130,6 +130,18 @@ open the dragged files in the current frame use the following line:
 @end lisp
 
 
+@subsection Customization options specific to Mac OS / GNUstep
+
+The following customization options are specific to the Nextstep port.
+
+@table @code
+@item ns-auto-hide-menu-bar
+Non-nil means the menu-bar is hidden by default, but appears if you
+move the mouse pointer over it.  (Requires OS X 10.6 or later.)
+
+@end table
+
+
 @node Mac / GNUstep Events, GNUstep Support, Mac / GNUstep Customization, Mac OS / GNUstep
 @section Windowing System Events under Mac OS / GNUstep
 
diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi
index 2ec477031ca..d2f92bf0da5 100644
--- a/doc/emacs/maintaining.texi
+++ b/doc/emacs/maintaining.texi
@@ -6,7 +6,10 @@
 @chapter Maintaining Large Programs
 
   This chapter describes Emacs features for maintaining large
-programs.
+programs.  If you are maintaining a large Lisp program, then in
+addition to the features described here, you may find
+the @file{ERT} (``Emacs Lisp Regression Testing'') library useful
+(@pxref{Top,,ERT,ert, Emacs Lisp Regression Testing}).
 
 @menu
 * Version Control::     Using version control systems.
diff --git a/doc/emacs/trouble.texi b/doc/emacs/trouble.texi
index 8cb5ab44a2e..6c6dbea9525 100644
--- a/doc/emacs/trouble.texi
+++ b/doc/emacs/trouble.texi
@@ -784,6 +784,12 @@ non-@code{nil} will start the Lisp debugger and show a backtrace.
 This backtrace is useful for debugging such long loops, so if you can
 produce it, copy it into the bug report.
 
+@vindex debug-on-event
+If you cannot get Emacs to respond to @kbd{C-g} (e.g., because
+@code{inhibit-quit} is set), then you can try sending the signal
+specified by @code{debug-on-event} (default SIGUSR2) from outside
+Emacs to cause it to enter the debugger.
+
 @item
 Check whether any programs you have loaded into the Lisp world,
 including your initialization file, set any variables that may affect
diff --git a/doc/emacs/windows.texi b/doc/emacs/windows.texi
index 76ab79361e4..3733eed3eca 100644
--- a/doc/emacs/windows.texi
+++ b/doc/emacs/windows.texi
@@ -72,7 +72,7 @@ Split the selected window into two windows, one above the other
 Split the selected window into two windows, positioned side by side
 (@code{split-window-right}).
 @item C-Mouse-2
-In the mode line or scroll bar of a window, split that window.
+In the mode line of a window, split that window.
 @end table
 
 @kindex C-x 2
@@ -125,11 +125,14 @@ lines in every partial-width window regardless of its width.
   On text terminals, side-by-side windows are separated by a vertical
 divider which is drawn using the @code{vertical-border} face.
 
+@kindex C-Mouse-2 @r{(mode line)}
 @kindex C-Mouse-2 @r{(scroll bar)}
-  You can also split a window horizontally or vertically by clicking
-@kbd{C-Mouse-2} in the mode line or the scroll bar.  If you click on
-the mode line, that puts the vertical divider where you click; if you
-click in the scroll bar, that puts the new mode-line where you click.
+  If you click @kbd{C-Mouse-2} in the mode line of a window, that
+splits the window, putting a vertical divider where you click.
+Depending on how Emacs is compiled, you can also split a window by
+clicking @kbd{C-Mouse-2} in the scroll bar, which puts a horizontal
+divider where you click (this feature does not work when Emacs uses
+GTK+ scroll bars).
 
 @node Other Window
 @section Using Other Windows
diff --git a/doc/lispintro/ChangeLog b/doc/lispintro/ChangeLog
index 66f9d3cace4..bf08571f6fb 100644
--- a/doc/lispintro/ChangeLog
+++ b/doc/lispintro/ChangeLog
@@ -1,7 +1,7 @@
 2012-01-28  Andreas Schwab  <schwab@linux-m68k.org>
 
         * emacs-lisp-intro.texi (Top): Move setting of COUNT-WORDS outside
-        of @menu. (Bug#10628)
+        of @menu.  (Bug#10628)
 
 2012-01-19  Juanma Barranquero  <lekktu@gmail.com>
 
diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 8f949eb24dd..bd7b27bbe60 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,109 @@
+2012-02-05  Chong Yidong  <cyd@gnu.org>
+
+        * customize.texi (Common Keywords): Minor clarifications.
+        Document custom-unlispify-remove-prefixes.
+        (Variable Definitions): Backquotes in defcustom seem to work fine
+        now.  Various other copyedits.
+
+        * eval.texi (Backquote): Move from macros.texi.
+
+        * macros.texi (Expansion): Minor clarification.
+        (Backquote): Move node to eval.texi.
+        (Defining Macros): Move an example from Backquote node.
+        (Argument Evaluation): No need to mention Pascal.
+        (Indenting Macros): Add xref to Defining Macros.
+
+2012-02-05  Glenn Morris  <rgm@gnu.org>
+
+        * debugging.texi (Error Debugging): Mention debug-on-event default.
+
+2012-02-04  Glenn Morris  <rgm@gnu.org>
+
+        * backups.texi (Reverting): Mention revert-buffer-in-progress-p.
+
+        * debugging.texi (Error Debugging): Mention debug-on-event.
+        * commands.texi (Misc Events): Mention sigusr1,2 and debugging.
+
+        * modes.texi (Running Hooks): Try to clarify with-wrapper-hook.
+
+        * text.texi (Buffer Contents):
+        Update filter-buffer-substring description.
+
+2012-02-04  Chong Yidong  <cyd@gnu.org>
+
+        * functions.texi (What Is a Function): Add closures.  Mention
+        "return value" terminology.  Add xref for command-execute.  Remove
+        unused "keystroke command" terminology.
+        (Lambda Expressions): Give a different example than in the
+        following subsection.  Add xref to Anonymous Functions.
+        (Function Documentation): Remove gratuitous markup.
+        (Function Names): Move introductory text to `What Is a Function'.
+        (Defining Functions): Fix defun argument spec.
+        (Anonymous Functions): Document lambda macro explicitly.  Mention
+        effects on lexical binding.
+        (Function Cells): Downplay direct usage of fset.
+        (Closures): New node.
+        (Inline Functions): Remove "open-code" terminology.
+        (Declaring Functions): Minor tweak; .m is not C code.
+
+        * variables.texi (Variables): Don't refer to "global value".
+        (Local Variables, Void Variables): Copyedits.
+        (Lexical Binding): Minor clarification of example.
+        (File Local Variables): Mention :safe and :risky defcustom args.
+        (Lexical Binding): Add xref to Closures node.
+
+2012-02-04  Glenn Morris  <rgm@gnu.org>
+
+        * minibuf.texi (High-Level Completion): Updates for read-color.
+
+2012-02-03  Glenn Morris  <rgm@gnu.org>
+
+        * display.texi (GIF Images): Mention animation.
+        Remove commented-out old example of animation.
+        (Animated Images): New subsection.
+        * elisp.texi (Top):
+        * vol1.texi (Top):
+        * vol2.texi (Top): Add Animated Images menu entry.
+
+        * display.texi (Image Formats): Remove oddly specific information
+        on versions of image libraries.
+        (GIF Images, TIFF Images): Minor rephrasing.
+
+2012-02-02  Glenn Morris  <rgm@gnu.org>
+
+        * processes.texi (Synchronous Processes):
+        Mention call-process's :file gets overwritten.
+
+        * commands.texi (Reading One Event):
+        * help.texi (Help Functions): Document read-char-choice.
+
+        * hooks.texi (Standard Hooks):
+        * modes.texi (Keymaps and Minor Modes):
+        * text.texi (Commands for Insertion): Document post-self-insert-hook.
+
+        * hooks.texi (Standard Hooks): Add prog-mode-hook.
+
+        * hooks.texi (Standard Hooks):
+        * modes.texi (Major Mode Conventions, Mode Hooks):
+        Document change-major-mode-after-body-hook.
+
+2012-02-01  Glenn Morris  <rgm@gnu.org>
+
+        * modes.texi (Defining Minor Modes):
+        Mention disabling global minor modes on a per-major-mode basis.
+
+2012-01-31  Chong Yidong  <cyd@gnu.org>
+
+        * syntax.texi (Parsing Expressions): Clarify intro (Bug#10657).
+        (Parser State): Remove unnecessary statement (Bug#10661).
+
+        * eval.texi (Intro Eval): Add footnote about "sexp" terminology.
+
+2012-01-31  Glenn Morris  <rgm@gnu.org>
+
+        * modes.texi (Defining Minor Modes):
+        Document define-minor-mode's new :variable keyword.
+
 2012-01-29  Chong Yidong  <cyd@gnu.org>
 
         * syntax.texi (Syntax Class Table): Tweak description of newline
diff --git a/doc/lispref/backups.texi b/doc/lispref/backups.texi
index 969220845d0..a4b3a0b9bef 100644
--- a/doc/lispref/backups.texi
+++ b/doc/lispref/backups.texi
@@ -696,6 +696,9 @@ operation, reverting preserves all the markers.  If they are not
 identical, reverting does change the buffer; in that case, it preserves
 the markers in the unchanged text (if any) at the beginning and end of
 the buffer.  Preserving any additional markers would be problematical.
+
+This command binds @code{revert-buffer-in-progress-p} to a
+non-@code{nil} value while it operates.
 @end deffn
 
 You can customize how @code{revert-buffer} does its work by setting
diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi
index 3d2b813b592..91e224a439f 100644
--- a/doc/lispref/commands.texi
+++ b/doc/lispref/commands.texi
@@ -1696,6 +1696,7 @@ parameters are used to display the help-echo text are described in
 These events are generated when the Emacs process receives
 the signals @code{SIGUSR1} and @code{SIGUSR2}.  They contain no
 additional data because signals do not carry additional information.
+They can be useful for debugging (@pxref{Error Debugging}).
 
 To catch a user signal, bind the corresponding event to an interactive
 command in the @code{special-event-map} (@pxref{Active Keymaps}).
@@ -2472,6 +2473,17 @@ The argument @var{prompt} is either a string to be displayed in the
 echo area as a prompt, or @code{nil}, meaning not to display a prompt.
 @end defun
 
+@defun read-char-choice prompt chars &optional inhibit-quit
+This function uses @code{read-key} to read and return a single
+character.  It ignores any input that is not a member of @var{chars},
+a list of accepted characters.  Optionally, it will also ignore
+keyboard-quit events while it is waiting for valid input.  If you bind
+@code{help-form} (@pxref{Help Functions}) to a non-@code{nil} value
+while calling @code{read-char-choice}, then pressing @code{help-char}
+causes it to evaluate @code{help-form} and display the result.  It
+then continues to wait for a valid input character, or keyboard-quit.
+@end defun
+
 @node Event Mod
 @subsection Modifying and Translating Input Events
 
diff --git a/doc/lispref/customize.texi b/doc/lispref/customize.texi
index 6d6c5df10ed..b8c30fff8ae 100644
--- a/doc/lispref/customize.texi
+++ b/doc/lispref/customize.texi
@@ -24,9 +24,10 @@ definitions---as well as face definitions (@pxref{Defining Faces}).
 @section Common Item Keywords
 
 @cindex customization keywords
-  All kinds of customization declarations (for variables and groups, and
-for faces) accept keyword arguments for specifying various information.
-This section describes some keywords that apply to all kinds.
+  The customization declarations that we will describe in the next few
+sections (@code{defcustom}, @code{defgroup}, etc.) all accept keyword
+arguments for specifying various information.  This section describes
+keywords that apply to all types of customization declarations.
 
   All of these keywords, except @code{:tag}, can be used more than once
 in a given item.  Each use of the keyword has an independent effect.
@@ -108,8 +109,7 @@ You can specify the text to use in the customization buffer by adding
 for example, @code{(info-link :tag "foo" "(emacs)Top")} makes a link to
 the Emacs manual which appears in the buffer as @samp{foo}.
 
-An item can have more than one external link; however, most items have
-none at all.
+You can use this keyword more than once, to add multiple links.
 
 @item :load @var{file}
 @kindex load@r{, customization keyword}
@@ -136,14 +136,13 @@ version.  The value @var{version} must be a string.
 @kindex package-version@r{, customization keyword}
 This keyword specifies that the item was first introduced in
 @var{package} version @var{version}, or that its meaning or default
-value was changed in that version.  The value of @var{package} is a
-symbol and @var{version} is a string.
+value was changed in that version.  This keyword takes priority over
+@code{:version}.
 
-This keyword takes priority over @code{:version}.
-
-@var{package} should be the official name of the package, such as MH-E
-or Gnus.  If the package @var{package} is released as part of Emacs,
-@var{package} and @var{version} should appear in the value of
+@var{package} should be the official name of the package, as a symbol
+(e.g.@: @code{MH-E}).  @var{version} should be a string.  If the
+package @var{package} is released as part of Emacs, @var{package} and
+@var{version} should appear in the value of
 @code{customize-package-emacs-version-alist}.
 @end table
 
@@ -226,41 +225,31 @@ also use this keyword in @code{defgroup}:
 @table @code
 @item :prefix @var{prefix}
 @kindex prefix@r{, @code{defgroup} keyword}
-If the name of an item in the group starts with @var{prefix}, then the
-tag for that item is constructed (by default) by omitting @var{prefix}.
-
-One group can have any number of prefixes.
+If the name of an item in the group starts with @var{prefix}, and the
+customizable variable @code{custom-unlispify-remove-prefixes} is
+non-@code{nil}, the item's tag will omit @var{prefix}.  A group can
+have any number of prefixes.
 @end table
 @end defmac
 
-  The prefix-discarding feature is currently turned off, which means
-that @code{:prefix} currently has no effect.  We did this because we
-found that discarding the specified prefixes often led to confusing
-names for options.  This happened because the people who wrote the
-@code{defgroup} definitions for various groups added @code{:prefix}
-keywords whenever they make logical sense---that is, whenever the
-variables in the library have a common prefix.
-
-  In order to obtain good results with @code{:prefix}, it would be
-necessary to check the specific effects of discarding a particular
-prefix, given the specific items in a group and their names and
-documentation.  If the resulting text is not clear, then @code{:prefix}
-should not be used in that case.
+@defopt custom-unlispify-remove-prefixes
+If this variable is non-@code{nil}, the prefixes specified by a
+group's @code{:prefix} keyword are omitted from tag names, whenever
+the user customizes the group.
 
-  It should be possible to recheck all the customization groups, delete
-the @code{:prefix} specifications which give unclear results, and then
-turn this feature back on, if someone would like to do the work.
+The default value is @code{nil}, i.e.@: the prefix-discarding feature
+is disabled.  This is because discarding prefixes often leads to
+confusing names for options and faces.
+@end defopt
 
 @node Variable Definitions
 @section Defining Customization Variables
 @cindex define customization options
 @cindex customization variables, how to define
 
-  Use @code{defcustom} to declare user-customizable variables.
-
 @defmac defcustom option standard doc [keyword value]@dots{}
-This macro declares @var{option} as a customizable @dfn{user option}.
-You should not quote @var{option}.
+This macro declares @var{option} as a user option (i.e.@: a
+customizable variable).  You should not quote @var{option}.
 
 The argument @var{standard} is an expression that specifies the
 standard value for @var{option}.  Evaluating the @code{defcustom} form
@@ -275,31 +264,25 @@ cases applies, @code{defcustom} installs the result of evaluating
 The expression @var{standard} can be evaluated at various other times,
 too---whenever the customization facility needs to know @var{option}'s
 standard value.  So be sure to use an expression which is harmless to
-evaluate at any time.  We recommend avoiding backquotes in
-@var{standard}, because they are not expanded when editing the value,
-so list values will appear to have the wrong structure.
+evaluate at any time.
 
 The argument @var{doc} specifies the documentation string for the
 variable.
 
 Every @code{defcustom} should specify @code{:group} at least once.
 
-If you specify the @code{:set} keyword, to make the variable take other
-special actions when set through the customization buffer, the
-variable's documentation string should tell the user specifically how
-to do the same job in hand-written Lisp code.
-
 When you evaluate a @code{defcustom} 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, without testing whether
 its value is void.  (The same feature applies to @code{defvar}.)
 @xref{Defining Variables}.
 
-If you put a @code{defcustom} in a file that is preloaded at dump time
-(@pxref{Building Emacs}), and the standard value installed for the
-variable at that time might not be correct, use
+If you put a @code{defcustom} in a pre-loaded Emacs Lisp file
+(@pxref{Building Emacs}), the standard value installed at dump time
+might be incorrect, e.g.@: because another variable that it depends on
+has not been assigned the right value yet.  In that case, use
 @code{custom-reevaluate-setting}, described below, to re-evaluate the
-standard value during or after Emacs startup.
+standard value after Emacs starts up.
 @end defmac
 
   @code{defcustom} accepts the following additional keywords:
@@ -330,6 +313,9 @@ the value properly for this option (which may not mean simply setting
 the option as a Lisp variable).  The default for @var{setfunction} is
 @code{set-default}.
 
+If you specify this keyword, the variable's documentation string
+should describe how to do the same job in hand-written Lisp code.
+
 @item :get @var{getfunction}
 @kindex get@r{, @code{defcustom} keyword}
 Specify @var{getfunction} as the way to extract the value of this
@@ -341,7 +327,7 @@ value).  The default is @code{default-value}.
 You have to really understand the workings of Custom to use
 @code{:get} correctly.  It is meant for values that are treated in
 Custom as variables but are not actually stored in Lisp variables.  It
-is almost surely a mistake to specify @code{getfunction} for a value
+is almost surely a mistake to specify @var{getfunction} for a value
 that really is stored in a Lisp variable.
 
 @item :initialize @var{function}
@@ -380,16 +366,15 @@ already set or has been customized; otherwise, just use
 These functions behave like @code{custom-initialize-set}
 (@code{custom-initialize-default}, respectively), but catch errors.
 If an error occurs during initialization, they set the variable to
-@code{nil} using @code{set-default}, and throw no error.
-
-These two functions are only meant for options defined in pre-loaded
-files, where some variables or functions used to compute the option's
-value may not yet be defined.  The option normally gets updated in
-@file{startup.el}, ignoring the previously computed value.  Because of
-this typical usage, the value which these two functions compute
-normally only matters when, after startup, one unsets the option's
-value and then reevaluates the defcustom.  By that time, the necessary
-variables and functions will be defined, so there will not be an error.
+@code{nil} using @code{set-default}, and signal no error.
+
+These functions are meant for options defined in pre-loaded files,
+where the @var{standard} expression may signal an error because some
+required variable or function is not yet defined.  The value normally
+gets updated in @file{startup.el}, ignoring the value computed by
+@code{defcustom}.  After startup, if one unsets the value and
+reevaluates the @code{defcustom}, the @var{standard} expression can be
+evaluated without error.
 @end table
 
 @item :risky @var{value}
@@ -457,18 +442,16 @@ is an expression that evaluates to the value.
 
 @defun custom-reevaluate-setting symbol
 This function re-evaluates the standard value of @var{symbol}, which
-should be a user option declared via @code{defcustom}.  (If the
+should be a user option declared via @code{defcustom}.  If the
 variable was customized, this function re-evaluates the saved value
-instead.)  This is useful for customizable options that are defined
-before their value could be computed correctly, such as variables
-defined in packages that are loaded at dump time, but depend on the
-run-time information.  For example, the value could be a file whose
-precise name depends on the hierarchy of files when Emacs runs, or a
-name of a program that needs to be searched at run time.
-
-A good place to put calls to this function is in the function
-@code{command-line} that is run during startup (@pxref{Startup Summary})
-or in the various hooks it calls.
+instead.  Then it sets the user option to that value (using the
+option's @code{:set} property if that is defined).
+
+This is useful for customizable options that are defined before their
+value could be computed correctly.  For example, during startup Emacs
+calls this function for some user options that were defined in
+pre-loaded Emacs Lisp files, but whose initial values depend on
+information available only at run-time.
 @end defun
 
 @defun custom-variable-p arg
diff --git a/doc/lispref/debugging.texi b/doc/lispref/debugging.texi
index 9466f21a563..cc92fc225f9 100644
--- a/doc/lispref/debugging.texi
+++ b/doc/lispref/debugging.texi
@@ -148,6 +148,15 @@ enter the debugger.
 @code{debug-on-error} is @code{nil}.
 @end defopt
 
+@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
+this event, bypassing @code{special-event-map}.  At present, the only
+supported values correspond to the signals @code{SIGUSR1} and
+@code{SIGUSR2} (this is the default).  This can be helpful when
+@code{inhibit-quit} is set and Emacs is not otherwise responding.
+@end defopt
+
   To debug an error that happens during loading of the init
 file, use the option @samp{--debug-init}.  This binds
 @code{debug-on-error} to @code{t} while loading the init file, and
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index a351dbfb407..e97e6c264a3 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -4134,6 +4134,7 @@ displayed (@pxref{Display Feature Testing}).
 * Other Image Types::   Various other formats are supported.
 * Defining Images::     Convenient ways to define an image for later use.
 * Showing Images::      Convenient ways to display an image once it is defined.
+* Animated Images::     Some image formats can be animated.
 * Image Cache::         Internal mechanisms of image display.
 @end menu
 
@@ -4151,12 +4152,10 @@ names for these dynamic libraries (though it is not possible to add
 new image formats).  Note that image types @code{pbm} and @code{xbm}
 do not depend on external libraries and are always available in Emacs.
 
-  The supported image formats include XBM, XPM (this requires the
-libraries @code{libXpm} version 3.4k and @code{libz}), GIF (requiring
-@code{libungif} 4.1.0), PostScript, PBM, JPEG (requiring the
-@code{libjpeg} library version v6a), TIFF (requiring @code{libtiff}
-v3.4), PNG (requiring @code{libpng} 1.0.2), and SVG (requiring
-@code{librsvg} 2.0.0).
+  The supported image formats (and the necessary library files)
+include XBM, XPM (@code{libXpm} and @code{libz}), GIF (@code{libgif}
+or @code{libungif}), PostScript, PBM, JPEG (@code{libjpeg}), TIFF
+(@code{libtiff}), PNG (@code{libpng}), and SVG (@code{librsvg}).
 
   You specify one of these formats with an image type symbol.  The image
 type symbols are @code{xbm}, @code{xpm}, @code{gif}, @code{postscript},
@@ -4471,33 +4470,13 @@ specifies the actual color to use for displaying that name.
 
 @table @code
 @item :index @var{index}
-You can use @code{:index} to specify one image from a GIF file that
-contains more than one image.  This property specifies use of image
-number @var{index} from the file.  If the GIF file doesn't contain an
-image with index @var{index}, the image displays as a hollow box.
+You can use @code{:index} to specify image number @var{index} from a
+GIF file that contains more than one image.  If the GIF file doesn't
+contain an image with the specified index, the image displays as a
+hollow box.  GIF files with more than one image can be animated,
+@pxref{Animated Images}.
 @end table
 
-@ignore
-This could be used to implement limited support for animated GIFs.
-For example, the following function displays a multi-image GIF file
-at point-min in the current buffer, switching between sub-images
-every 0.1 seconds.
-
-(defun show-anim (file max)
-  "Display multi-image GIF file FILE which contains MAX subimages."
-  (display-anim (current-buffer) file 0 max t))
-
-(defun display-anim (buffer file idx max first-time)
-  (when (= idx max)
-    (setq idx 0))
-  (let ((img (create-image file nil :image idx)))
-    (with-current-buffer buffer
-      (goto-char (point-min))
-      (unless first-time (delete-char 1))
-      (insert-image img))
-    (run-with-timer 0.1 nil 'display-anim buffer file (1+ idx) max nil)))
-@end ignore
-
 @node TIFF Images
 @subsection TIFF Images
 @cindex TIFF
@@ -4506,10 +4485,10 @@ every 0.1 seconds.
 
 @table @code
 @item :index @var{index}
-You can use @code{:index} to specify one image from a TIFF file that
-contains more than one image.  This property specifies use of image
-number @var{index} from the file.  If the TIFF file doesn't contain an
-image with index @var{index}, the image displays as a hollow box.
+You can use @code{:index} to specify image number @var{index} from a
+TIFF file that contains more than one image.  If the TIFF file doesn't
+contain an image with the specified index, the image displays as a
+hollow box.
 @end table
 
 @node PostScript Images
@@ -4857,6 +4836,39 @@ cache, it can always be displayed, even if the value of
 @var{max-image-size} is subsequently changed (@pxref{Image Cache}).
 @end defvar
 
+@node Animated Images
+@subsection Animated Images
+
+@cindex animation
+@cindex image animation
+Some image files can contain more than one image.  This can be used to
+create animation.  Currently, Emacs only supports animated GIF files.
+The following functions related to animated images are available.
+
+@defun image-animated-p image
+This function returns non-nil if @var{image} can be animated.
+The actual return value is a cons @code{(@var{nimages} . @var{delay})}, 
+where @var{nimages} is the number of frames and @var{delay} is the
+delay in seconds between them.
+@end defun
+
+@defun image-animate image &optional index limit
+This function animates @var{image}.  The optional integer @var{index}
+specifies the frame from which to start (default 0).  The optional
+argument @var{limit} controls the length of the animation.  If omitted
+or @code{nil}, the image animates once only; if @code{t} it loops
+forever; if a number animation stops after that many seconds.
+@end defun
+
+@noindent Animation operates by means of a timer.  Note that Emacs imposes a
+minimum frame delay of 0.01 seconds.
+
+@defun image-animate-timer image
+This function returns the timer responsible for animating @var{image},
+if there is one.
+@end defun
+
+
 @node Image Cache
 @subsection Image Cache
 @cindex image cache
diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index 31e887ea68b..f69823101d0 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -374,6 +374,7 @@ Evaluation
 * Forms::                   How various sorts of objects are evaluated.
 * Quoting::                 Avoiding evaluation (to put constants in
                               the program).
+* Backquote::               Easier construction of list structure.
 * Eval::                    How to invoke the Lisp interpreter explicitly.
 
 Kinds of Forms
@@ -459,6 +460,7 @@ Functions
 * Anonymous Functions::     Lambda expressions are functions with no names.
 * Function Cells::          Accessing or setting the function definition
                               of a symbol.
+* Closures::                Functions that enclose a lexical environment.
 * Obsolete Functions::      Declaring functions obsolete.
 * Inline Functions::        Defining functions that the compiler
                               will open code.
@@ -481,7 +483,6 @@ Macros
 * Expansion::               How, when and why macros are expanded.
 * Compiling Macros::        How macros are expanded by the compiler.
 * Defining Macros::         How to write a macro definition.
-* Backquote::               Easier construction of list structure.
 * Problems with Macros::    Don't evaluate the macro arguments too many times.
                               Don't hide the user's variables.
 * Indenting Macros::        Specifying how to indent macro calls.
@@ -1351,6 +1352,7 @@ Images
 * Defining Images::         Convenient ways to define an image for later use.
 * Showing Images::          Convenient ways to display an image once
                               it is defined.
+* Animated Images::         Some image formats can be animated.
 * Image Cache::             Internal mechanisms of image display.
 
 Buttons
diff --git a/doc/lispref/eval.texi b/doc/lispref/eval.texi
index fc18e503543..cb3a4c54fac 100644
--- a/doc/lispref/eval.texi
+++ b/doc/lispref/eval.texi
@@ -23,6 +23,7 @@ function @code{eval}.
 * Intro Eval::  Evaluation in the scheme of things.
 * Forms::       How various sorts of objects are evaluated.
 * Quoting::     Avoiding evaluation (to put constants in the program).
+* Backquote::   Easier construction of list structure.
 * Eval::        How to invoke the Lisp interpreter explicitly.
 @end menu
 
@@ -39,12 +40,15 @@ interpreter.
 
 @cindex form
 @cindex expression
-  A Lisp object that is intended for evaluation is called an
-@dfn{expression} or a @dfn{form}.  The fact that forms are data
-objects and not merely text is one of the fundamental differences
-between Lisp-like languages and typical programming languages.  Any
-object can be evaluated, but in practice only numbers, symbols, lists
-and strings are evaluated very often.
+@cindex S-expression
+  A Lisp object that is intended for evaluation is called a @dfn{form}
+or @dfn{expression}@footnote{It is sometimes also referred to as an
+@dfn{S-expression} or @dfn{sexp}, but we generally do not use this
+terminology in this manual.}.  The fact that forms are data objects
+and not merely text is one of the fundamental differences between
+Lisp-like languages and typical programming languages.  Any object can
+be evaluated, but in practice only numbers, symbols, lists and strings
+are evaluated very often.
 
   In subsequent sections, we will describe the details of what
 evaluation means for each kind of form.
@@ -96,12 +100,12 @@ interpretation.  @xref{Command Loop}.
 @node Forms
 @section Kinds of Forms
 
-  A Lisp object that is intended to be evaluated is called a @dfn{form}.
-How Emacs evaluates a form depends on its data type.  Emacs has three
-different kinds of form that are evaluated differently: symbols, lists,
-and ``all other types.''  This section describes all three kinds, one by
-one, starting with the ``all other types'' which are self-evaluating
-forms.
+  A Lisp object that is intended to be evaluated is called a
+@dfn{form} (or an @dfn{expression}).  How Emacs evaluates a form
+depends on its data type.  Emacs has three different kinds of form
+that are evaluated differently: symbols, lists, and ``all other
+types.''  This section describes all three kinds, one by one, starting
+with the ``all other types'' which are self-evaluating forms.
 
 @menu
 * Self-Evaluating Forms::   Forms that evaluate to themselves.
@@ -576,6 +580,96 @@ Functions}), which causes an anonymous lambda expression written in Lisp
 to be compiled, and @samp{`} (@pxref{Backquote}), which is used to quote
 only part of a list, while computing and substituting other parts.
 
+@node Backquote
+@section Backquote
+@cindex backquote (list substitution)
+@cindex ` (list substitution)
+@findex `
+
+  @dfn{Backquote constructs} allow you to quote a list, but
+selectively evaluate elements of that list.  In the simplest case, it
+is identical to the special form @code{quote}
+@iftex
+@end iftex
+@ifnottex
+(described in the previous section; @pxref{Quoting}).
+@end ifnottex
+For example, these two forms yield identical results:
+
+@example
+@group
+`(a list of (+ 2 3) elements)
+     @result{} (a list of (+ 2 3) elements)
+@end group
+@group
+'(a list of (+ 2 3) elements)
+     @result{} (a list of (+ 2 3) elements)
+@end group
+@end example
+
+@findex , @r{(with backquote)}
+  The special marker @samp{,} inside of the argument to backquote
+indicates a value that isn't constant.  The Emacs Lisp evaluator
+evaluates the argument of @samp{,}, and puts the value in the list
+structure:
+
+@example
+@group
+`(a list of ,(+ 2 3) elements)
+     @result{} (a list of 5 elements)
+@end group
+@end example
+
+@noindent
+Substitution with @samp{,} is allowed at deeper levels of the list
+structure also.  For example:
+
+@example
+@group
+`(1 2 (3 ,(+ 4 5)))
+     @result{} (1 2 (3 9))
+@end group
+@end example
+
+@findex ,@@ @r{(with backquote)}
+@cindex splicing (with backquote)
+  You can also @dfn{splice} an evaluated value into the resulting list,
+using the special marker @samp{,@@}.  The elements of the spliced list
+become elements at the same level as the other elements of the resulting
+list.  The equivalent code without using @samp{`} is often unreadable.
+Here are some examples:
+
+@example
+@group
+(setq some-list '(2 3))
+     @result{} (2 3)
+@end group
+@group
+(cons 1 (append some-list '(4) some-list))
+     @result{} (1 2 3 4 2 3)
+@end group
+@group
+`(1 ,@@some-list 4 ,@@some-list)
+     @result{} (1 2 3 4 2 3)
+@end group
+
+@group
+(setq list '(hack foo bar))
+     @result{} (hack foo bar)
+@end group
+@group
+(cons 'use
+  (cons 'the
+    (cons 'words (append (cdr list) '(as elements)))))
+     @result{} (use the words foo bar as elements)
+@end group
+@group
+`(use the words ,@@(cdr list) as elements)
+     @result{} (use the words foo bar as elements)
+@end group
+@end example
+
+
 @node Eval
 @section Eval
 
diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi
index ada00867bd0..9ee94557066 100644
--- a/doc/lispref/functions.texi
+++ b/doc/lispref/functions.texi
@@ -21,8 +21,9 @@ define them.
 * Anonymous Functions::   Lambda expressions are functions with no names.
 * Function Cells::        Accessing or setting the function definition
                             of a symbol.
+* Closures::              Functions that enclose a lexical environment.
 * Obsolete Functions::    Declaring functions obsolete.
-* Inline Functions::      Defining functions that the compiler will open code.
+* Inline Functions::      Functions that the compiler will expand inline.
 * Declaring Functions::   Telling the compiler that a function is defined.
 * Function Safety::       Determining whether a function is safe to call.
 * Related Topics::        Cross-references to specific Lisp primitives
@@ -32,104 +33,117 @@ define them.
 @node What Is a Function
 @section What Is a Function?
 
-  In a general sense, a function is a rule for carrying on a computation
-given several values called @dfn{arguments}.  The result of the
-computation is called the value of the function.  The computation can
-also have side effects: lasting changes in the values of variables or
-the contents of data structures.
-
-  Here are important terms for functions in Emacs Lisp and for other
-function-like objects.
+@cindex return value
+@cindex value of function
+@cindex argument
+  In a general sense, a function is a rule for carrying out a
+computation given input values called @dfn{arguments}.  The result of
+the computation is called the @dfn{value} or @dfn{return value} of the
+function.  The computation can also have side effects, such as lasting
+changes in the values of variables or the contents of data structures.
+
+  In most computer languages, every function has a name.  But in Lisp,
+a function in the strictest sense has no name: it is an object which
+can @emph{optionally} be associated with a symbol (e.g.@: @code{car})
+that serves as the function name.  @xref{Function Names}.  When a
+function has been given a name, we usually also refer to that symbol
+as a ``function'' (e.g.@: we refer to ``the function @code{car}'').
+In this manual, the distinction between a function name and the
+function object itself is usually unimportant, but we will take note
+wherever it is relevant.
+
+  Certain function-like objects, called @dfn{special forms} and
+@dfn{macros}, also accept arguments to carry out computations.
+However, as explained below, these are not considered functions in
+Emacs Lisp.
+
+  Here are important terms for functions and function-like objects:
 
 @table @dfn
-@item function
-@cindex function
-In Emacs Lisp, a @dfn{function} is anything that can be applied to
-arguments in a Lisp program.  In some cases, we use it more
-specifically to mean a function written in Lisp.  Special forms and
-macros are not functions.
+@item lambda expression
+A function (in the strict sense, i.e.@: a function object) which is
+written in Lisp.  These are described in the following section.
+@ifnottex
+@xref{Lambda Expressions}.
+@end ifnottex
 
 @item primitive
 @cindex primitive
 @cindex subr
 @cindex built-in function
-A @dfn{primitive} is a function callable from Lisp that is written in C,
-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 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.
-These are described in the following section.
-@ifnottex
-@xref{Lambda Expressions}.
-@end ifnottex
+A function which is callable from Lisp but is actually written in C.
+Primitives are also called @dfn{built-in functions}, or @dfn{subrs}.
+Examples include functions like @code{car} and @code{append}.  In
+addition, all special forms (see below) are also considered
+primitives.
+
+Usually, a function is implemented as a primitive because it is a
+fundamental part of Lisp (e.g.@: @code{car}), or because it provides a
+low-level interface to operating system services, or because it needs
+to run fast.  Unlike functions defined in Lisp, primitives can be
+modified or added only by changing the C sources and recompiling
+Emacs.  See @ref{Writing Emacs Primitives}.
 
 @item special form
-A @dfn{special form} is a primitive that is like a function but does not
-evaluate all of its arguments in the usual way.  It may evaluate only
-some of the arguments, or may evaluate them in an unusual order, or
-several times.  Many special forms are described in @ref{Control
-Structures}.
+A primitive that is like a function but does not evaluate all of its
+arguments in the usual way.  It may evaluate only some of the
+arguments, or may evaluate them in an unusual order, or several times.
+Examples include @code{if}, @code{and}, and @code{while}.
+@xref{Special Forms}.
 
 @item macro
 @cindex macro
-A @dfn{macro} is a construct defined in Lisp by the programmer.  It
-differs from a function in that it translates a Lisp expression that you
-write into an equivalent expression to be evaluated instead of the
-original expression.  Macros enable Lisp programmers to do the sorts of
-things that special forms can do.  @xref{Macros}, for how to define and
-use macros.
+A construct defined in Lisp, which differs from a function in that it
+translates a Lisp expression into another expression which is to be
+evaluated instead of the original expression.  Macros enable Lisp
+programmers to do the sorts of things that special forms can do.
+@xref{Macros}.
 
 @item command
 @cindex command
-A @dfn{command} is an object that @code{command-execute} can invoke; it
-is a possible definition for a key sequence.  Some functions are
-commands; a function written in Lisp is a command if it contains an
-interactive declaration (@pxref{Defining Commands}).  Such a function
-can be called from Lisp expressions like other functions; in this case,
-the fact that the function is a command makes no difference.
+An object which can be invoked via the @code{command-execute}
+primitive, usually due to the user typing in a key sequence
+@dfn{bound} to that command.  @xref{Interactive Call}.  A command is
+usually a function; if the function is written in Lisp, it is made
+into a command by an @code{interactive} form in the function
+definition (@pxref{Defining Commands}).  Commands that are functions
+can also be called from Lisp expressions, just like other functions.
 
 Keyboard macros (strings and vectors) are commands also, even though
-they are not functions.  A symbol is a command if its function
-definition is a command; such symbols can be invoked with @kbd{M-x}.
-The symbol is a function as well if the definition is a function.
-@xref{Interactive Call}.
-
-@item keystroke command
-@cindex keystroke command
-A @dfn{keystroke command} is a command that is bound to a key sequence
-(typically one to three keystrokes).  The distinction is made here
-merely to avoid confusion with the meaning of ``command'' in non-Emacs
-editors; for Lisp programs, the distinction is normally unimportant.
+they are not functions.  @xref{Keyboard Macros}.  We say that a symbol
+is a command if its function cell contains a command (@pxref{Symbol
+Components}); such a @dfn{named command} can be invoked with
+@kbd{M-x}.
+
+@item closure
+A function object that is much like a lambda expression, except that
+it also encloses an ``environment'' of lexical variable bindings.
+@xref{Closures}.
 
 @item byte-code function
-A @dfn{byte-code function} is a function that has been compiled by the
-byte compiler.  @xref{Byte-Code Type}.
+A function that has been compiled by the byte compiler.
+@xref{Byte-Code Type}.
 
 @item autoload object
 @cindex autoload object
-An @dfn{autoload object} is a place-holder for a real function.  If
-the autoload object is called, it will make Emacs load the file
-containing the definition of the real function, and then call the real
-function instead.
+A place-holder for a real function.  If the autoload object is called,
+Emacs loads the file containing the definition of the real function,
+and then calls the real function.  @xref{Autoload}.
 @end table
 
+  You can use the function @code{functionp} to test if an object is a
+function:
+
 @defun functionp object
 This function returns @code{t} if @var{object} is any kind of
 function, i.e.@: can be passed to @code{funcall}.  Note that
-@code{functionp} returns @code{nil} for special forms (@pxref{Special
-Forms}).
+@code{functionp} returns @code{t} for symbols that are function names,
+and returns @code{nil} for special forms.
 @end defun
 
-Unlike @code{functionp}, the next three functions do @emph{not}
-treat a symbol as its function definition.
+@noindent
+Unlike @code{functionp}, the next three functions do @emph{not} treat
+a symbol as its function definition.
 
 @defun subrp object
 This function returns @code{t} if @var{object} is a built-in function
@@ -172,21 +186,26 @@ function with @code{&rest} arguments, or the symbol @code{unevalled} if
 @section Lambda Expressions
 @cindex lambda expression
 
-  A function written in Lisp is a list that looks like this:
+  A lambda expression is a function object written in Lisp.  Here is
+an example:
 
 @example
-(lambda (@var{arg-variables}@dots{})
-  @r{[}@var{documentation-string}@r{]}
-  @r{[}@var{interactive-declaration}@r{]}
-  @var{body-forms}@dots{})
+(lambda (x)
+  "Return the hyperbolic cosine of X."
+  (* 0.5 (+ (exp x) (exp (- x)))))
 @end example
 
 @noindent
-Such a list is called a @dfn{lambda expression}.  In Emacs Lisp, it
-actually is valid as an expression---it evaluates to itself.  In some
-other Lisp dialects, a lambda expression is not a valid expression at
-all.  In either case, its main use is not to be evaluated as an
-expression, but to be called as a function.
+In Emacs Lisp, such a list is valid as an expression---it evaluates to
+itself.  But its main use is not to be evaluated as an expression, but
+to be called as a function.
+
+  A lambda expression, by itself, has no name; it is an @dfn{anonymous
+function}.  Although lambda expressions can be used this way
+(@pxref{Anonymous Functions}), they are more commonly associated with
+symbols to make @dfn{named functions} (@pxref{Function Names}).
+Before going into these details, the following subsections describe
+the components of a lambda expression and what they do.
 
 @menu
 * Lambda Components::       The parts of a lambda expression.
@@ -198,10 +217,7 @@ expression, but to be called as a function.
 @node Lambda Components
 @subsection Components of a Lambda Expression
 
-@ifnottex
-
-  A function written in Lisp (a ``lambda expression'') is a list that
-looks like this:
+  A lambda expression is a list that looks like this:
 
 @example
 (lambda (@var{arg-variables}@dots{})
@@ -209,7 +225,6 @@ looks like this:
   [@var{interactive-declaration}]
   @var{body-forms}@dots{})
 @end example
-@end ifnottex
 
 @cindex lambda list
   The first element of a lambda expression is always the symbol
@@ -243,9 +258,9 @@ code to do the work of the function (or, as a Lisp programmer would say,
 function is the value returned by the last element of the body.
 
 @node Simple Lambda
-@subsection A Simple Lambda-Expression Example
+@subsection A Simple Lambda Expression Example
 
-  Consider for example the following function:
+  Consider the following example:
 
 @example
 (lambda (a b c) (+ a b c))
@@ -283,18 +298,15 @@ This evaluates the arguments @code{1}, @code{(* 2 3)}, and @code{(- 5
 4)} from left to right.  Then it applies the lambda expression to the
 argument values 1, 6 and 1 to produce the value 8.
 
-  It is not often useful to write a lambda expression as the @sc{car} of
-a form in this way.  You can get the same result, of making local
-variables and giving them values, using the special form @code{let}
-(@pxref{Local Variables}).  And @code{let} is clearer and easier to use.
-In practice, lambda expressions are either stored as the function
-definitions of symbols, to produce named functions, or passed as
-arguments to other functions (@pxref{Anonymous Functions}).
-
-  However, calls to explicit lambda expressions were very useful in the
-old days of Lisp, before the special form @code{let} was invented.  At
-that time, they were the only way to bind and initialize local
-variables.
+  As these examples show, you can use a form with a lambda expression
+as its @sc{car} to make local variables and give them values.  In the
+old days of Lisp, this technique was the only way to bind and
+initialize local variables.  But nowadays, it is clearer to use the
+special form @code{let} for this purpose (@pxref{Local Variables}).
+Lambda expressions are mainly used as anonymous functions for passing
+as arguments to other functions (@pxref{Anonymous Functions}), or
+stored as symbol function definitions to produce named functions
+(@pxref{Function Names}).
 
 @node Argument List
 @subsection Other Features of Argument Lists
@@ -405,12 +417,12 @@ after a @code{&rest} argument.
 @subsection Documentation Strings of Functions
 @cindex documentation of function
 
-  A lambda expression may optionally have a @dfn{documentation string} just
-after the lambda list.  This string does not affect execution of the
-function; it is a kind of comment, but a systematized comment which
-actually appears inside the Lisp world and can be used by the Emacs help
-facilities.  @xref{Documentation}, for how the @var{documentation-string} is
-accessed.
+  A lambda expression may optionally have a @dfn{documentation string}
+just after the lambda list.  This string does not affect execution of
+the function; it is a kind of comment, but a systematized comment
+which actually appears inside the Lisp world and can be used by the
+Emacs help facilities.  @xref{Documentation}, for how the
+documentation string is accessed.
 
   It is a good idea to provide documentation strings for all the
 functions in your program, even those that are called only from within
@@ -463,55 +475,45 @@ way users think of the parts of the macro call.
 @cindex named function
 @cindex function name
 
-  In most computer languages, every function has a name; the idea of a
-function without a name is nonsensical.  In Lisp, a function in the
-strictest sense has no name.  It is simply a list whose first element is
-@code{lambda}, a byte-code function object, or a primitive subr-object.
-
-  However, a symbol can serve as the name of a function.  This happens
-when you put the function in the symbol's @dfn{function cell}
-(@pxref{Symbol Components}).  Then the symbol itself becomes a valid,
-callable function, equivalent to the list or subr-object that its
-function cell refers to.  The contents of the function cell are also
-called the symbol's @dfn{function definition}.  The procedure of using a
-symbol's function definition in place of the symbol is called
-@dfn{symbol function indirection}; see @ref{Function Indirection}.
-
-  In practice, nearly all functions are given names in this way and
-referred to through their names.  For example, the symbol @code{car} works
-as a function and does what it does because the primitive subr-object
-@code{#<subr car>} is stored in its function cell.
+  A symbol can serve as the name of a function.  This happens when the
+symbol's @dfn{function cell} (@pxref{Symbol Components}) contains a
+function object (e.g.@: a lambda expression).  Then the symbol itself
+becomes a valid, callable function, equivalent to the function object
+in its function cell.
+
+  The contents of the function cell are also called the symbol's
+@dfn{function definition}.  The procedure of using a symbol's function
+definition in place of the symbol is called @dfn{symbol function
+indirection}; see @ref{Function Indirection}.  If you have not given a
+symbol a function definition, its function cell is said to be
+@dfn{void}, and it cannot be used as a function.
+
+  In practice, nearly all functions have names, and are referred to by
+their names.  You can create a named Lisp function by defining a
+lambda expression and putting it in a function cell (@pxref{Function
+Cells}).  However, it is more common to use the @code{defun} special
+form, described in the next section.
+@ifnottex
+@xref{Defining Functions}.
+@end ifnottex
 
   We give functions names because it is convenient to refer to them by
-their names in Lisp expressions.  For primitive subr-objects such as
-@code{#<subr car>}, names are the only way you can refer to them: there
-is no read syntax for such objects.  For functions written in Lisp, the
-name is more convenient to use in a call than an explicit lambda
-expression.  Also, a function with a name can refer to itself---it can
-be recursive.  Writing the function's name in its own definition is much
-more convenient than making the function definition point to itself
-(something that is not impossible but that has various disadvantages in
-practice).
-
-  We often identify functions with the symbols used to name them.  For
-example, we often speak of ``the function @code{car},'' not
-distinguishing between the symbol @code{car} and the primitive
-subr-object that is its function definition.  For most purposes, the
-distinction is not important.
-
-  Even so, keep in mind that a function need not have a unique name.  While
-a given function object @emph{usually} appears in the function cell of only
-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.)  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.
+their names in Lisp expressions.  Also, a named Lisp function can
+easily refer to itself---it can be recursive.  Furthermore, primitives
+can only be referred to textually by their names, since primitive
+function objects (@pxref{Primitive Function Type}) have no read
+syntax.
+
+  A function need not have a unique name.  A given function object
+@emph{usually} appears in the function cell of only one symbol, but
+this is just a convention.  It is easy to store it in several symbols
+using @code{fset}; then each of the symbols is a valid name for the
+same function.
+
+  Note that 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.  (This is not the case in some dialects of Lisp, like
+Scheme.)
 
 @node Defining Functions
 @section Defining Functions
@@ -521,7 +523,7 @@ value as a variable makes no difference to this.
 is called @dfn{defining a function}, and it is done with the
 @code{defun} special form.
 
-@defspec defun name argument-list body-forms
+@defspec defun name argument-list body-forms...
 @code{defun} is the usual way to define new Lisp functions.  It
 defines the symbol @var{name} as a function that looks like this:
 
@@ -534,14 +536,9 @@ defines the symbol @var{name} as a function that looks like this:
 value.
 
 As described previously, @var{argument-list} is a list of argument
-names and may include the keywords @code{&optional} and @code{&rest}
-(@pxref{Lambda Expressions}).  Also, the first two of the
-@var{body-forms} may be a documentation string and an interactive
-declaration.
-
-There is no conflict if the same symbol @var{name} is also used as a
-variable, since the symbol's value cell is independent of the function
-cell.  @xref{Symbol Components}.
+names and may include the keywords @code{&optional} and @code{&rest}.
+Also, the first two of the @var{body-forms} may be a documentation
+string and an interactive declaration.  @xref{Lambda Components}.
 
 Here are some examples:
 
@@ -575,7 +572,7 @@ Here are some examples:
 
 @group
 (defun capitalize-backwards ()
-  "Upcase the last letter of a word."
+  "Upcase the last letter of the word at point."
   (interactive)
   (backward-word 1)
   (forward-word 1)
@@ -587,9 +584,10 @@ Here are some examples:
 
 Be careful not to redefine existing functions unintentionally.
 @code{defun} redefines even primitive functions such as @code{car}
-without any hesitation or notification.  Redefining a function already
-defined is often done deliberately, and there is no way to distinguish
-deliberate redefinition from unintentional redefinition.
+without any hesitation or notification.  Emacs does not prevent you
+from doing this, because redefining a function is sometimes done
+deliberately, and there is no way to distinguish deliberate
+redefinition from unintentional redefinition.
 @end defspec
 
 @cindex function aliases
@@ -626,7 +624,8 @@ call the primitive's C definition directly, so changing the symbol's
 definition will have no effect on them.
 
   See also @code{defsubst}, which defines a function like @code{defun}
-and tells the Lisp compiler to open-code it.  @xref{Inline Functions}.
+and tells the Lisp compiler to perform inline expansion on it.
+@xref{Inline Functions}.
 
 @node Calling Functions
 @section Calling Functions
@@ -790,11 +789,10 @@ This function returns @var{arg} and has no side effects.
 This function ignores any arguments and returns @code{nil}.
 @end defun
 
-  Emacs Lisp functions can also be user-visible @dfn{commands}.  A
-command is a function that has an @dfn{interactive} specification.
-You may want to call these functions as if they were called
-interactively.  See @ref{Interactive Call} for details on how to do
-that.
+  Some functions are user-visible @dfn{commands}, which can be called
+interactively (usually by a key sequence).  It is possible to invoke
+such a command exactly as though it was called interactively, by using
+the @code{call-interactively} function.  @xref{Interactive Call}.
 
 @node Mapping Functions
 @section Mapping Functions
@@ -802,12 +800,12 @@ that.
 
   A @dfn{mapping function} applies a given function (@emph{not} a
 special form or macro) to each element of a list or other collection.
-Emacs Lisp has several such functions; @code{mapcar} and
-@code{mapconcat}, which scan a list, are described here.
-@xref{Definition of mapatoms}, for the function @code{mapatoms} which
-maps over the symbols in an obarray.  @xref{Definition of maphash},
-for the function @code{maphash} which maps over key/value associations
-in a hash table.
+Emacs Lisp has several such functions; this section describes
+@code{mapcar}, @code{mapc}, and @code{mapconcat}, which map over a
+list.  @xref{Definition of mapatoms}, for the function @code{mapatoms}
+which maps over the symbols in an obarray.  @xref{Definition of
+maphash}, for the function @code{maphash} which maps over key/value
+associations in a hash table.
 
   These mapping functions do not allow char-tables because a char-table
 is a sparse array whose nominal range of indices is very large.  To map
@@ -898,48 +896,67 @@ bool-vector, or a string.
 @section Anonymous Functions
 @cindex anonymous function
 
-  In Lisp, a function is a list that starts with @code{lambda}, a
-byte-code function compiled from such a list, or alternatively a
-primitive subr-object; names are ``extra.''  Although functions are
-usually defined with @code{defun} and given names at the same time, it
-is occasionally more concise to use an explicit lambda expression---an
-anonymous function.  Such a list is valid wherever a function name is.
+  Although functions are usually defined with @code{defun} and given
+names at the same time, it is sometimes convenient to use an explicit
+lambda expression---an @dfn{anonymous function}.  Anonymous functions
+are valid wherever function names are.  They are often assigned as
+variable values, or as arguments to functions; for instance, you might
+pass one as the @var{function} argument to @code{mapcar}, which
+applies that function to each element of a list (@pxref{Mapping
+Functions}).  @xref{describe-symbols example}, for a realistic example
+of this.
+
+  When defining a lambda expression that is to be used as an anonymous
+function, you can in principle use any method to construct the list.
+But typically you should use the @code{lambda} macro, or the
+@code{function} special form, or the @code{#'} read syntax:
+
+@defmac lambda args body...
+This macro returns an anonymous function with argument list @var{args}
+and body forms given by @var{body}.  In effect, this macro makes
+@code{lambda} forms ``self-quoting'': evaluating a form whose @sc{car}
+is @code{lambda} yields the form itself:
+
+@example
+(lambda (x) (* x x))
+     @result{} (lambda (x) (* x x))
+@end example
+
+The @code{lambda} form has one other effect: it tells the Emacs
+evaluator and byte-compiler that its argument is a function, by using
+@code{function} as a subroutine (see below).
+@end defmac
 
-  Any method of creating such a list makes a valid function.  Even this:
+@defspec function function-object
+@cindex function quoting
+This special form returns @var{function-object} without evaluating it.
+In this, it is similar to @code{quote} (@pxref{Quoting}).  But unlike
+@code{quote}, it also serves as a note to the Emacs evaluator and
+byte-compiler that @var{function-object} is intended to be used as a
+function.  Assuming @var{function-object} is a valid lambda
+expression, this has two effects:
 
-@smallexample
-@group
-(setq silly (append '(lambda (x)) (list (list '+ (* 3 4) 'x))))
-@result{} (lambda (x) (+ 12 x))
-@end group
-@end smallexample
+@itemize
+@item
+When the code is byte-compiled, @var{function-object} is compiled into
+a byte-code function object (@pxref{Byte Compilation}).
 
-@noindent
-This computes a list that looks like @code{(lambda (x) (+ 12 x))} and
-makes it the value (@emph{not} the function definition!) of
-@code{silly}.
+@item
+When lexical binding is enabled, @var{function-object} is converted
+into a closure.  @xref{Closures}.
+@end itemize
+@end defspec
 
-  Here is how we might call this function:
+@cindex @samp{#'} syntax
+The read syntax @code{#'} is a short-hand for using @code{function}.
+The following forms are all equivalent:
 
 @example
-@group
-(funcall silly 1)
-@result{} 13
-@end group
+(lambda (x) (* x x))
+(function (lambda (x) (* x x)))
+#'(lambda (x) (* x x))
 @end example
 
-@noindent
-It does @emph{not} work to write @code{(silly 1)}, because this
-function is not the @emph{function definition} of @code{silly}.  We
-have not given @code{silly} any function definition, just a value as a
-variable.
-
-  Most of the time, anonymous functions are constants that appear in
-your program.  For instance, you might want to pass one as an argument
-to the function @code{mapcar}, which applies any given function to
-each element of a list (@pxref{Mapping Functions}).
-@xref{describe-symbols example}, for a realistic example of this.
-
   In the following example, we define a @code{change-property}
 function that takes a function as its third argument, followed by a
 @code{double-property} function that makes use of
@@ -959,15 +976,11 @@ function that takes a function as its third argument, followed by a
 @end example
 
 @noindent
-In the @code{double-property} function, we did not quote the
-@code{lambda} form.  This is permissible, because a @code{lambda} form
-is @dfn{self-quoting}: evaluating the form yields the form itself.
+Note that we do not quote the @code{lambda} form.
 
-Whether or not you quote a @code{lambda} form makes a difference if
-you compile the code (@pxref{Byte Compilation}).  If the @code{lambda}
-form is unquoted, as in the above example, the anonymous function is
-also compiled.  Suppose, however, that we quoted the @code{lambda}
-form:
+  If you compile the above code, the anonymous function is also
+compiled.  This would not happen if, say, you had constructed the
+anonymous function by quoting it as a list:
 
 @example
 @group
@@ -977,52 +990,10 @@ form:
 @end example
 
 @noindent
-If you compile this, the argument passed to @code{change-property} is
-the precise list shown:
-
-@example
-(lambda (x) (* x 2))
-@end example
-
-@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 it will check whether the @sc{car} of
-the third element is the symbol @code{*}!
-
-@findex function
-The @code{function} special form explicitly tells the byte-compiler
-that its argument is a function:
-
-@defspec function function-object
-@cindex function quoting
-This special form returns @var{function-object} without evaluating it.
-In this, it is equivalent to @code{quote}.  However, it serves as a
-note to the Emacs Lisp compiler that @var{function-object} is intended
-to be used only as a function, and therefore can safely be compiled.
-Contrast this with @code{quote}, in @ref{Quoting}.
-@end defspec
-
-@cindex @samp{#'} syntax
-The read syntax @code{#'} is a short-hand for using @code{function}.
-Generally, it is not necessary to use either @code{#'} or
-@code{function}; just use an unquoted @code{lambda} form instead.
-(Actually, @code{lambda} is a macro defined using @code{function}.)
-The following forms are all equivalent:
-
-@example
-#'(lambda (x) (* x x))
-(function (lambda (x) (* x x)))
-(lambda (x) (* x x))
-@end example
-
-  We sometimes write @code{function} instead of @code{quote} when
-quoting the name of a function, but this usage is just a sort of
-comment:
-
-@example
-(function @var{symbol}) @equiv{} (quote @var{symbol}) @equiv{} '@var{symbol}
-@end example
+In that case, the anonymous function is kept as a lambda expression in
+the compiled code.  The byte-compiler cannot assume this list is a
+function, even though it looks like one, since it does not know that
+@code{change-property} intends to use it as a function.
 
 @node Function Cells
 @section Accessing Function Cell Contents
@@ -1118,77 +1089,60 @@ This function stores @var{definition} in the function cell of
 this is not checked.  The argument @var{symbol} is an ordinary evaluated
 argument.
 
-There are three normal uses of this function:
+The primary use of this function is as a subroutine by constructs that
+define or alter functions, like @code{defadvice} (@pxref{Advising
+Functions}).  (If @code{defun} were not a primitive, it could be
+written as a Lisp macro using @code{fset}.)  You can also use it to
+give a symbol a function definition that is not a list, e.g.@: a
+keyboard macro (@pxref{Keyboard Macros}):
 
-@itemize @bullet
-@item
-Copying one symbol's function definition to another---in other words,
-making an alternate name for a function.  (If you think of this as the
-definition of the new name, you should use @code{defalias} instead of
-@code{fset}; see @ref{Definition of defalias}.)
+@example
+;; @r{Define a named keyboard macro.}
+(fset 'kill-two-lines "\^u2\^k")
+     @result{} "\^u2\^k"
+@end example
 
-@item
-Giving a symbol a function definition that is not a list and therefore
-cannot be made with @code{defun}.  For example, you can use @code{fset}
-to give a symbol @code{s1} a function definition which is another symbol
-@code{s2}; then @code{s1} serves as an alias for whatever definition
-@code{s2} presently has.  (Once again use @code{defalias} instead of
-@code{fset} if you think of this as the definition of @code{s1}.)
+It you wish to use @code{fset} to make an alternate name for a
+function, consider using @code{defalias} instead.  @xref{Definition of
+defalias}.
+@end defun
 
-@item
-In constructs for defining or altering functions.  If @code{defun}
-were not a primitive, it could be written in Lisp (as a macro) using
-@code{fset}.
-@end itemize
+@node Closures
+@section Closures
 
-Here are examples of these uses:
+  As explained in @ref{Variable Scoping}, Emacs can optionally enable
+lexical binding of variables.  When lexical binding is enabled, any
+named function that you create (e.g.@: with @code{defun}), as well as
+any anonymous function that you create using the @code{lambda} macro
+or the @code{function} special form or the @code{#'} syntax
+(@pxref{Anonymous Functions}), is automatically converted into a
+closure.
 
-@example
-@group
-;; @r{Save @code{foo}'s definition in @code{old-foo}.}
-(fset 'old-foo (symbol-function 'foo))
-@end group
+  A closure is a function that also carries a record of the lexical
+environment that existed when the function was defined.  When it is
+invoked, any lexical variable references within its definition use the
+retained lexical environment.  In all other respects, closures behave
+much like ordinary functions; in particular, they can be called in the
+same way as ordinary functions.
 
-@group
-;; @r{Make the symbol @code{car} the function definition of @code{xfirst}.}
-;; @r{(Most likely, @code{defalias} would be better than @code{fset} here.)}
-(fset 'xfirst 'car)
-     @result{} car
-@end group
-@group
-(xfirst '(1 2 3))
-     @result{} 1
-@end group
-@group
-(symbol-function 'xfirst)
-     @result{} car
-@end group
-@group
-(symbol-function (symbol-function 'xfirst))
-     @result{} #<subr car>
-@end group
+  @xref{Lexical Binding}, for an example of using a closure.
 
-@group
-;; @r{Define a named keyboard macro.}
-(fset 'kill-two-lines "\^u2\^k")
-     @result{} "\^u2\^k"
-@end group
+  Currently, an Emacs Lisp closure object is represented by a list
+with the symbol @code{closure} as the first element, a list
+representing the lexical environment as the second element, and the
+argument list and body forms as the remaining elements:
 
-@group
-;; @r{Here is a function that alters other functions.}
-(defun copy-function-definition (new old)
-  "Define NEW with the same function definition as OLD."
-  (fset new (symbol-function old)))
-@end group
+@example
+;; @r{lexical binding is enabled.}
+(lambda (x) (* x x))
+     @result{} (closure (t) (x) (* x x))
 @end example
-@end defun
 
-  @code{fset} is sometimes used to save the old definition of a
-function before redefining it.  That permits the new definition to
-invoke the old definition.  But it is unmodular and unclean for a Lisp
-file to redefine a function defined elsewhere.  If you want to modify
-a function defined by another package, it is cleaner to use
-@code{defadvice} (@pxref{Advising Functions}).
+@noindent
+However, the fact that the internal structure of a closure is
+``exposed'' to the rest of the Lisp world is considered an internal
+implementation detail.  For this reason, we recommend against directly
+examining or altering the structure of closure objects.
 
 @node Obsolete Functions
 @section Declaring Functions Obsolete
@@ -1254,41 +1208,46 @@ this:
 @section Inline Functions
 @cindex inline functions
 
-@findex defsubst
-You can define an @dfn{inline function} by using @code{defsubst} instead
-of @code{defun}.  An inline function works just like an ordinary
-function except for one thing: when you compile a call to the function,
-the function's definition is open-coded into the caller.
+@defmac defsubst name argument-list body-forms...
+Define an inline function.  The syntax is exactly the same as
+@code{defun} (@pxref{Defining Functions}).
+@end defmac
+
+  You can define an @dfn{inline function} by using @code{defsubst}
+instead of @code{defun}.  An inline function works just like an
+ordinary function except for one thing: when you byte-compile a call
+to the function (@pxref{Byte Compilation}), the function's definition
+is expanded into the caller.
 
-Making a function inline makes explicit calls run faster.  But it also
-has disadvantages.  For one thing, it reduces flexibility; if you
-change the definition of the function, calls already inlined still use
-the old definition until you recompile them.
+  Making a function inline often makes its function calls run faster.
+But it also has disadvantages.  For one thing, it reduces flexibility;
+if you change the definition of the function, calls already inlined
+still use the old definition until you recompile them.
 
-Another disadvantage is that making a large function inline can increase
-the size of compiled code both in files and in memory.  Since the speed
-advantage of inline functions is greatest for small functions, you
-generally should not make large functions inline.
+  Another disadvantage is that making a large function inline can
+increase the size of compiled code both in files and in memory.  Since
+the speed advantage of inline functions is greatest for small
+functions, you generally should not make large functions inline.
 
-Also, inline functions do not behave well with respect to debugging,
+  Also, inline functions do not behave well with respect to debugging,
 tracing, and advising (@pxref{Advising Functions}).  Since ease of
 debugging and the flexibility of redefining functions are important
 features of Emacs, you should not make a function inline, even if it's
 small, unless its speed is really crucial, and you've timed the code
 to verify that using @code{defun} actually has performance problems.
 
-It's possible to define a macro to expand into the same code that an
-inline function would execute.  (@xref{Macros}.)  But the macro would be
-limited to direct use in expressions---a macro cannot be called with
-@code{apply}, @code{mapcar} and so on.  Also, it takes some work to
-convert an ordinary function into a macro.  To convert it into an inline
-function is very easy; simply replace @code{defun} with @code{defsubst}.
-Since each argument of an inline function is evaluated exactly once, you
-needn't worry about how many times the body uses the arguments, as you
-do for macros.  (@xref{Argument Evaluation}.)
+  It's possible to define a macro to expand into the same code that an
+inline function would execute (@pxref{Macros}).  But the macro would
+be limited to direct use in expressions---a macro cannot be called
+with @code{apply}, @code{mapcar} and so on.  Also, it takes some work
+to convert an ordinary function into a macro.  To convert it into an
+inline function is easy; just replace @code{defun} with
+@code{defsubst}.  Since each argument of an inline function is
+evaluated exactly once, you needn't worry about how many times the
+body uses the arguments, as you do for macros.
 
-Inline functions can be used and open-coded later on in the same file,
-following the definition, just like macros.
+  After an inline function is defined, its inline expansion can be
+performed later on in the same file, just like macros.
 
 @node Declaring Functions
 @section Telling the Compiler that a Function is Defined
@@ -1352,12 +1311,10 @@ definition using @code{locate-library}; if that finds no file, they
 expand the definition file name relative to the directory of the file
 that contains the @code{declare-function} call.
 
-  You can also say that a function is defined by C code by specifying a
-file name ending in @samp{.c} or @samp{.m}.  @code{check-declare-file}
-looks for these files in the C source code directory.  This is useful
-only when you call a function that is defined only on certain systems.
-Most of the primitive functions of Emacs are always defined so they will
-never give you a warning.
+  You can also say that a function is a primitive by specifying a file
+name ending in @samp{.c} or @samp{.m}.  This is useful only when you
+call a primitive that is defined only on certain systems.  Most
+primitives are always defined, so they will never give you a warning.
 
   Sometimes a file will optionally use functions from an external package.
 If you prefix the filename in the @code{declare-function} statement with
diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi
index 678ea83465f..f6556639e98 100644
--- a/doc/lispref/help.texi
+++ b/doc/lispref/help.texi
@@ -582,11 +582,12 @@ If this variable is non-@code{nil}, its value is a form to evaluate
 whenever the character @code{help-char} is read.  If evaluating the form
 produces a string, that string is displayed.
 
-A command that calls @code{read-event} or @code{read-char} probably
-should bind @code{help-form} to a non-@code{nil} expression while it
-does input.  (The time when you should not do this is when @kbd{C-h} has
-some other meaning.)  Evaluating this expression should result in a
-string that explains what the input is for and how to enter it properly.
+A command that calls @code{read-event}, @code{read-char-choice}, or
+@code{read-char} probably should bind @code{help-form} to a
+non-@code{nil} expression while it does input.  (The time when you
+should not do this is when @kbd{C-h} has some other meaning.)
+Evaluating this expression should result in a string that explains
+what the input is for and how to enter it properly.
 
 Entry to the minibuffer binds this variable to the value of
 @code{minibuffer-help-form} (@pxref{Definition of minibuffer-help-form}).
diff --git a/doc/lispref/hooks.texi b/doc/lispref/hooks.texi
index 95655324ab4..ef3ebc4be35 100644
--- a/doc/lispref/hooks.texi
+++ b/doc/lispref/hooks.texi
@@ -127,6 +127,9 @@ not exactly a hook, but does a similar job.
 @xref{Calendar Customizing,,, emacs}.
 @end ifnottex
 
+@item change-major-mode-after-body-hook
+@xref{Mode Hooks}.
+
 @item change-major-mode-hook
 @xref{Creating Buffer-Local}.
 
@@ -292,9 +295,15 @@ Manual}.
 @item post-command-hook
 @xref{Command Overview}.
 
+@item post-self-insert-hook
+@xref{Keymaps and Minor Modes}.
+
 @item pre-command-hook
 @xref{Command Overview}.
 
+@item prog-mode-hook
+@xref{Basic Major Modes}.
+
 @item resume-tty-functions
 @xref{Suspending Emacs}.
 
diff --git a/doc/lispref/macros.texi b/doc/lispref/macros.texi
index 3804d963108..dca88d2b7c7 100644
--- a/doc/lispref/macros.texi
+++ b/doc/lispref/macros.texi
@@ -27,7 +27,6 @@ instead.  @xref{Inline Functions}.
 * Expansion::               How, when and why macros are expanded.
 * Compiling Macros::        How macros are expanded by the compiler.
 * Defining Macros::         How to write a macro definition.
-* Backquote::               Easier construction of list structure.
 * Problems with Macros::    Don't evaluate the macro arguments too many times.
                               Don't hide the user's variables.
 * Indenting Macros::        Specifying how to indent macro calls.
@@ -78,10 +77,9 @@ to the argument values from the macro call, or to a list of them in the
 case of a @code{&rest} argument.  And the macro body executes and
 returns its value just as a function body does.
 
-  The second crucial difference between macros and functions is that the
-value returned by the macro body is not the value of the macro call.
-Instead, it is an alternate expression for computing that value, also
-known as the @dfn{expansion} of the macro.  The Lisp interpreter
+  The second crucial difference between macros and functions is that
+the value returned by the macro body is an alternate Lisp expression,
+also known as the @dfn{expansion} of the macro.  The Lisp interpreter
 proceeds to evaluate the expansion as soon as it comes back from the
 macro.
 
@@ -221,7 +219,26 @@ any @code{interactive} declaration is ignored since macros cannot be
 called interactively.
 @end defspec
 
-  The body of the macro definition can include a @code{declare} form,
+  Macros often need to construct large list structures from a mixture
+of constants and nonconstant parts.  To make this easier, use the
+@samp{`} syntax (@pxref{Backquote}).  For example:
+
+@example
+@example
+@group
+(defmacro t-becomes-nil (variable)
+  `(if (eq ,variable t)
+       (setq ,variable nil)))
+@end group
+
+@group
+(t-becomes-nil foo)
+     @equiv{} (if (eq foo t) (setq foo nil))
+@end group
+@end example
+@end example
+
+  The body of a macro definition can include a @code{declare} form,
 which can specify how @key{TAB} should indent macro calls, and how to
 step through them for Edebug.
 
@@ -259,107 +276,11 @@ without evaluating any @var{specs}.
 has no effect on how the macro expands, on what the macro means in the
 program.  It only affects the secondary features listed above.
 
-@node Backquote
-@section Backquote
-@cindex backquote (list substitution)
-@cindex ` (list substitution)
-@findex `
-
-  Macros often need to construct large list structures from a mixture of
-constants and nonconstant parts.  To make this easier, use the @samp{`}
-syntax (usually called @dfn{backquote}).
-
-  Backquote allows you to quote a list, but selectively evaluate
-elements of that list.  In the simplest case, it is identical to the
-special form @code{quote} (@pxref{Quoting}).  For example, these
-two forms yield identical results:
-
-@example
-@group
-`(a list of (+ 2 3) elements)
-     @result{} (a list of (+ 2 3) elements)
-@end group
-@group
-'(a list of (+ 2 3) elements)
-     @result{} (a list of (+ 2 3) elements)
-@end group
-@end example
-
-@findex , @r{(with backquote)}
-The special marker @samp{,} inside of the argument to backquote
-indicates a value that isn't constant.  Backquote evaluates the
-argument of @samp{,} and puts the value in the list structure:
-
-@example
-@group
-(list 'a 'list 'of (+ 2 3) 'elements)
-     @result{} (a list of 5 elements)
-@end group
-@group
-`(a list of ,(+ 2 3) elements)
-     @result{} (a list of 5 elements)
-@end group
-@end example
-
-  Substitution with @samp{,} is allowed at deeper levels of the list
-structure also.  For example:
-
-@example
-@group
-(defmacro t-becomes-nil (variable)
-  `(if (eq ,variable t)
-       (setq ,variable nil)))
-@end group
-
-@group
-(t-becomes-nil foo)
-     @equiv{} (if (eq foo t) (setq foo nil))
-@end group
-@end example
-
-@findex ,@@ @r{(with backquote)}
-@cindex splicing (with backquote)
-  You can also @dfn{splice} an evaluated value into the resulting list,
-using the special marker @samp{,@@}.  The elements of the spliced list
-become elements at the same level as the other elements of the resulting
-list.  The equivalent code without using @samp{`} is often unreadable.
-Here are some examples:
-
-@example
-@group
-(setq some-list '(2 3))
-     @result{} (2 3)
-@end group
-@group
-(cons 1 (append some-list '(4) some-list))
-     @result{} (1 2 3 4 2 3)
-@end group
-@group
-`(1 ,@@some-list 4 ,@@some-list)
-     @result{} (1 2 3 4 2 3)
-@end group
-
-@group
-(setq list '(hack foo bar))
-     @result{} (hack foo bar)
-@end group
-@group
-(cons 'use
-  (cons 'the
-    (cons 'words (append (cdr list) '(as elements)))))
-     @result{} (use the words foo bar as elements)
-@end group
-@group
-`(use the words ,@@(cdr list) as elements)
-     @result{} (use the words foo bar as elements)
-@end group
-@end example
-
 @node Problems with Macros
 @section Common Problems Using Macros
 
-  The basic facts of macro expansion have counterintuitive consequences.
-This section describes some important consequences that can lead to
+  Macro expansion can have counterintuitive consequences.  This
+section describes some important consequences that can lead to
 trouble, and rules to follow to avoid trouble.
 
 @menu
@@ -407,9 +328,8 @@ program is actually run.
 
   When defining a macro you must pay attention to the number of times
 the arguments will be evaluated when the expansion is executed.  The
-following macro (used to facilitate iteration) illustrates the problem.
-This macro allows us to write a simple ``for'' loop such as one might
-find in Pascal.
+following macro (used to facilitate iteration) illustrates the
+problem.  This macro allows us to write a ``for'' loop construct.
 
 @findex for
 @smallexample
@@ -683,9 +603,9 @@ either.
 @node Indenting Macros
 @section Indenting Macros
 
-  You can use the @code{declare} form in the macro definition to
-specify how to @key{TAB} should indent calls to the macro.  You
-write it like this:
+  Within a macro definition, you can use the @code{declare} form
+(@pxref{Defining Macros}) to specify how to @key{TAB} should indent
+calls to the macro.  An indentation specifiction is written like this:
 
 @example
 (declare (indent @var{indent-spec}))
@@ -715,6 +635,7 @@ the line uses the standard pattern.
 @var{symbol} should be a function name; that function is called to
 calculate the indentation of a line within this expression.  The
 function receives two arguments:
+
 @table @asis
 @item @var{state}
 The value returned by @code{parse-partial-sexp} (a Lisp primitive for
@@ -723,6 +644,7 @@ beginning of this line.
 @item @var{pos}
 The position at which the line being indented begins.
 @end table
+
 @noindent
 It should return either a number, which is the number of columns of
 indentation for that line, or a list whose car is such a number.  The
diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi
index e3008470233..a71138f5268 100644
--- a/doc/lispref/minibuf.texi
+++ b/doc/lispref/minibuf.texi
@@ -1335,19 +1335,19 @@ but uses the predicate @code{user-variable-p} instead of
 @deffn Command read-color &optional prompt convert allow-empty display
 This function reads a string that is a color specification, either the
 color's name or an RGB hex value such as @code{#RRRGGGBBB}.  It
-prompts with @var{prompt} (default: @code{"Color (name or #R+G+B+):"})
+prompts with @var{prompt} (default: @code{"Color (name or #RGB triplet):"})
 and provides completion for color names, but not for hex RGB values.
 In addition to names of standard colors, completion candidates include
 the foreground and background colors at point.
 
 Valid RGB values are described in @ref{Color Names}.
 
-The function's return value is the color name typed by the user in the
+The function's return value is the string typed by the user in the
 minibuffer.  However, when called interactively or if the optional
-argument @var{convert} is non-@code{nil}, it converts the name into
-the color's RGB value and returns that value as a string.  If an
-invalid color name was specified, this function signals an error,
-except that empty color names are allowed when @code{allow-empty} is
+argument @var{convert} is non-@code{nil}, it converts any input color
+name into the corresponding RGB value string and instead returns that.
+This function requires a valid color specification to be input.
+Empty color names are allowed when @code{allow-empty} is
 non-@code{nil} and the user enters null input.
 
 Interactively, or when @var{display} is non-@code{nil}, the return
diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index 53120d72bd1..638ab89e37f 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -135,21 +135,32 @@ This macro runs the abnormal hook @code{hook} as a series of nested
 ``wrapper functions'' around the @var{body} forms.  The effect is
 similar to nested @code{around} advices (@pxref{Around-Advice}).
 
-Each hook function must accept an argument list consisting of a function
+Each hook function should accept an argument list consisting of a function
 @var{fun}, followed by the additional arguments listed in @var{args}.
-The function @var{fun} passed to the very first hook function in
-@var{hook} does the same as @var{body}, if it is called with arguments
-@var{args}.  The @var{fun} passed to each successive hook function is
+The first hook function is passed a function @var{fun} that, if it is
+called with arguments @var{args}, performs @var{body} (i.e., the default
+operation).  The @var{fun} passed to each successive hook function is
 constructed from all the preceding hook functions (and @var{body}); if
 this @var{fun} is called with arguments @var{args}, it does what the
 @code{with-wrapper-hook} call would if the preceding hook functions were
 the only ones in @var{hook}.
 
-In the function definition of the hook function, @var{fun} can be called
-any number of times (including not calling it at all).  This function
-definition is then used to construct the @var{fun} passed to the next
-hook function in @var{hook}, if any.  The last or ``outermost''
-@var{fun} is called once to produce the effect.
+Each hook function may call its @var{fun} argument as many times as it
+wishes, including never.  In that case, such a hook function acts to
+replace the default definition altogether, and any preceding hook
+functions.  Of course, a subsequent hook function may do the same thing.
+
+Each hook function definition is used to construct the @var{fun} passed
+to the next hook function in @var{hook}, if any.  The last or
+``outermost'' @var{fun} is called once to produce the overall effect.
+
+When might you want to use a wrapper hook?  The function
+@code{filter-buffer-substring} illustrates a common case.  There is a
+basic functionality, performed by @var{body}---in this case, to extract
+a buffer-substring.  Then any number of hook functions can act in
+sequence to modify that string, before returning the final result.
+A wrapper-hook also allows for a hook function to completely replace the
+default definition (by not calling @var{fun}).
 @end defmac
 
 @node Setting Hooks
@@ -468,8 +479,9 @@ other packages would interfere with them.
 @cindex major mode hook
 Each major mode should have a normal @dfn{mode hook} named
 @code{@var{modename}-mode-hook}.  The very last thing the major mode command
-should do is to call @code{run-mode-hooks}.  This runs the mode hook,
-and then runs the normal hook @code{after-change-major-mode-hook}.
+should do is to call @code{run-mode-hooks}.  This runs the normal
+hook @code{change-major-mode-after-body-hook}, the mode hook,
+and then the normal hook @code{after-change-major-mode-hook}.
 @xref{Mode Hooks}.
 
 @item
@@ -939,8 +951,9 @@ before it runs the mode hook variable @code{@var{mode}-hook}.
 @node Mode Hooks
 @subsection Mode Hooks
 
-  Every major mode command should finish by running its mode hook and
-the mode-independent normal hook @code{after-change-major-mode-hook}.
+  Every major mode command should finish by running the mode-independent
+normal hook @code{change-major-mode-after-body-hook}, its mode hook,
+and the normal hook @code{after-change-major-mode-hook}.
 It does this by calling @code{run-mode-hooks}.  If the major mode is a
 derived mode, that is if it calls another major mode (the parent mode)
 in its body, it should do this inside @code{delay-mode-hooks} so that
@@ -949,11 +962,12 @@ call to @code{run-mode-hooks} runs the parent's mode hook too.
 @xref{Major Mode Conventions}.
 
   Emacs versions before Emacs 22 did not have @code{delay-mode-hooks}.
-When user-implemented major modes have not been updated to use it,
-they won't entirely follow these conventions: they may run the
-parent's mode hook too early, or fail to run
-@code{after-change-major-mode-hook}.  If you encounter such a major
-mode, please correct it to follow these conventions.
+Versions before 24 did not have @code{change-major-mode-after-body-hook}.
+When user-implemented major modes do not use @code{run-mode-hooks} and
+have not been updated to use these newer features, they won't entirely
+follow these conventions: they may run the parent's mode hook too early,
+or fail to run @code{after-change-major-mode-hook}.  If you encounter
+such a major mode, please correct it to follow these conventions.
 
   When you defined a major mode using @code{define-derived-mode}, it
 automatically makes sure these conventions are followed.  If you
@@ -963,6 +977,7 @@ use the following functions to handle these conventions automatically.
 @defun run-mode-hooks &rest hookvars
 Major modes should run their mode hook using this function.  It is
 similar to @code{run-hooks} (@pxref{Hooks}), but it also runs
+@code{change-major-mode-after-body-hook} and
 @code{after-change-major-mode-hook}.
 
 When this function is called during the execution of a
@@ -982,6 +997,11 @@ The hooks will actually run during the next call to
 construct.
 @end defmac
 
+@defvar change-major-mode-after-body-hook
+This is a normal hook run by @code{run-mode-hooks}.  It is run before
+the mode hooks.
+@end defvar
+
 @defvar after-change-major-mode-hook
 This is a normal hook run by @code{run-mode-hooks}.  It is run at the
 very end of every properly-written major mode command.
@@ -1332,11 +1352,12 @@ alist @code{minor-mode-map-alist}.  @xref{Definition of minor-mode-map-alist}.
 @cindex @code{self-insert-command}, minor modes
   One use of minor mode keymaps is to modify the behavior of certain
 self-inserting characters so that they do something else as well as
-self-insert.  In general, this is the only way to do that, since the
-facilities for customizing @code{self-insert-command} are limited to
-special cases (designed for abbrevs and Auto Fill mode).  (Do not try
-substituting your own definition of @code{self-insert-command} for the
-standard one.  The editor command loop handles this function specially.)
+self-insert.  (Another way to customize @code{self-insert-command} is
+through @code{post-self-insert-hook}.  Apart from this, the facilities
+for customizing @code{self-insert-command} are limited to special cases,
+designed for abbrevs and Auto Fill mode.  Do not try substituting your
+own definition of @code{self-insert-command} for the standard one.  The
+editor command loop handles this function specially.)
 
 The key sequences bound in a minor mode should consist of @kbd{C-c}
 followed by one of @kbd{.,/?`'"[]\|~!#$%^&*()-_+=}.  (The other
@@ -1351,11 +1372,11 @@ implementing a mode in one self-contained definition.
 @defmac define-minor-mode mode doc [init-value [lighter [keymap]]] keyword-args@dots{} body@dots{}
 This macro defines a new minor mode whose name is @var{mode} (a
 symbol).  It defines a command named @var{mode} to toggle the minor
-mode, with @var{doc} as its documentation string.  It also defines a
-variable named @var{mode}, which is set to @code{t} or @code{nil} by
-enabling or disabling the mode.  The variable is initialized to
-@var{init-value}.  Except in unusual circumstances (see below), this
-value must be @code{nil}.
+mode, with @var{doc} as its documentation string.  By default, it also
+defines a variable named @var{mode}, which is set to @code{t} or
+@code{nil} by enabling or disabling the mode.  The variable is
+initialized to @var{init-value}.  Except in unusual circumstances (see
+below), this value must be @code{nil}.
 
 The string @var{lighter} says what to display in the mode line
 when the mode is enabled; if it is @code{nil}, the mode is not displayed
@@ -1410,6 +1431,17 @@ This is equivalent to specifying @var{lighter} positionally.
 
 @item :keymap @var{keymap}
 This is equivalent to specifying @var{keymap} positionally.
+
+@item :variable @var{place}
+This replaces the default variable @var{mode}, used to store the state
+of the mode.  If you specify this, the @var{mode} variable is not
+defined, and any @var{init-value} argument is unused.  @var{place}
+can be a different named variable (which you must define yourself), or
+anything that can be used with the @code{setf} function
+(@pxref{Generalized Variables,,, cl, Common Lisp Extensions}).
+@var{place} can also be a cons @code{(@var{get} . @var{set})},
+where @var{get} is an expression that returns the current state,
+and @var{set} is a function of one argument (a state) that sets it.
 @end table
 
 Any other keyword arguments are passed directly to the
@@ -1510,8 +1542,15 @@ starts, for example by providing a @code{:require} keyword.
 
 Use @code{:group @var{group}} in @var{keyword-args} to specify the
 custom group for the mode variable of the global minor mode.
+
+Generally speaking, when you define a globalized minor mode, you should
+also define a non-globalized version, so that people can use (or
+disable) it in individual buffers.  This also allows them to disable a
+globally enabled minor mode in a specific major mode, by using that
+mode's hook.
 @end defmac
 
+
 @node Mode Line Format
 @section Mode-Line Format
 @cindex mode line
diff --git a/doc/lispref/numbers.texi b/doc/lispref/numbers.texi
index bec9f295227..82336aa537f 100644
--- a/doc/lispref/numbers.texi
+++ b/doc/lispref/numbers.texi
@@ -284,7 +284,7 @@ floating point), and returns @code{t} if so, @code{nil} otherwise.
 
 @defun natnump object
 @cindex natural numbers
-This predicate (whose name comes from the phrase ``natual number'')
+This predicate (whose name comes from the phrase ``natural number'')
 tests to see whether its argument is a nonnegative integer, and
 returns @code{t} if so, @code{nil} otherwise.  0 is considered
 non-negative.
diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi
index 38eb5a86471..4cfc954cd1f 100644
--- a/doc/lispref/processes.texi
+++ b/doc/lispref/processes.texi
@@ -300,7 +300,8 @@ MS-DOS doesn't support asynchronous subprocesses, so this option doesn't
 work there.
 
 @item @code{(:file @var{file-name})}
-Send the output to the file name specified.
+Send the output to the file name specified, overwriting it if it
+already exists.
 
 @item @code{(@var{real-destination} @var{error-destination})}
 Keep the standard output stream separate from the standard error stream;
diff --git a/doc/lispref/syntax.texi b/doc/lispref/syntax.texi
index 71742e37a51..3d153e43b2d 100644
--- a/doc/lispref/syntax.texi
+++ b/doc/lispref/syntax.texi
@@ -606,11 +606,13 @@ expression prefix syntax class, and characters with the @samp{p} flag.
 @section Parsing Expressions
 
   This section describes functions for parsing and scanning balanced
-expressions, also known as @dfn{sexps}.  Basically, a sexp is either a
-balanced parenthetical grouping, a string, or a symbol name (a
-sequence of characters whose syntax is either word constituent or
-symbol constituent).  However, characters whose syntax is expression
-prefix are treated as part of the sexp if they appear next to it.
+expressions.  We will refer to such expressions as @dfn{sexps},
+following the terminology of Lisp, even though these functions can act
+on languages other than Lisp.  Basically, a sexp is either a balanced
+parenthetical grouping, a string, or a ``symbol'' (i.e.@: a sequence
+of characters whose syntax is either word constituent or symbol
+constituent).  However, characters whose syntax is expression prefix
+are treated as part of the sexp if they appear next to it.
 
   The syntax table controls the interpretation of characters, so these
 functions can be used for Lisp expressions when in Lisp mode and for C
@@ -830,10 +832,6 @@ The value is @code{nil} if @var{state} represents a parse which has
 arrived at a top level position.
 @end defun
 
-  We have provided this access function rather than document how the
-data is represented in the state, because we plan to change the
-representation in the future.
-
 @node Low-Level Parsing
 @subsection Low-Level Parsing
 
diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index 55b0c0a4be8..8e7434de2ed 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -218,44 +218,46 @@ This is like @code{buffer-substring}, except that it does not copy text
 properties, just the characters themselves.  @xref{Text Properties}.
 @end defun
 
-@defun filter-buffer-substring start end &optional delete noprops
+@defun filter-buffer-substring start end &optional delete
 This function passes the buffer text between @var{start} and @var{end}
-through the filter functions specified by the variable
-@code{buffer-substring-filters}, and returns the value from the last
-filter function.  If @code{buffer-substring-filters} is @code{nil},
-the value is the unaltered text from the buffer, what
-@code{buffer-substring} would return.
+through the filter functions specified by the wrapper hook
+@code{filter-buffer-substring-functions}, and returns the final
+result of applying all filters.  The obsolete variable
+@code{buffer-substring-filters} is also consulted.  If both of these
+variables are @code{nil}, the value is the unaltered text from the
+buffer, as @code{buffer-substring} would return.
 
 If @var{delete} is non-@code{nil}, this function deletes the text
 between @var{start} and @var{end} after copying it, like
 @code{delete-and-extract-region}.
 
-If @var{noprops} is non-@code{nil}, the final string returned does not
-include text properties, while the string passed through the filters
-still includes text properties from the buffer text.
-
 Lisp code should use this function instead of @code{buffer-substring},
 @code{buffer-substring-no-properties},
 or @code{delete-and-extract-region} when copying into user-accessible
 data structures such as the kill-ring, X clipboard, and registers.
 Major and minor modes can add functions to
-@code{buffer-substring-filters} to alter such text as it is copied out
-of the buffer.
+@code{filter-buffer-substring-functions} to alter such text as it is
+copied out of the buffer.
 @end defun
 
-@defvar buffer-substring-filters
-This variable should be a list of functions that accept a single
-argument, a string, and return a string.
-@code{filter-buffer-substring} passes the buffer substring to the
-first function in this list, and the return value of each function is
-passed to the next function.  The return value of the last function is
-used as the return value of @code{filter-buffer-substring}.
-
-As a special convention, point is set to the start of the buffer text
-being operated on (i.e., the @var{start} argument for
-@code{filter-buffer-substring}) before these functions are called.
-
-If this variable is @code{nil}, no filtering is performed.
+@defvar filter-buffer-substring-functions
+This variable is a wrapper hook (@pxref{Running Hooks}), whose members
+should be functions that accept four arguments: @var{fun},
+@var{start}, @var{end}, and @var{delete}.  @var{fun} is a function
+that takes three arguments (@var{start}, @var{end}, and @var{delete}),
+and returns a string.  In both cases, the @var{start}, @var{end}, and
+@var{delete} arguments are the same as those of
+@code{filter-buffer-substring}.
+
+The first hook function is passed a @var{fun} that is equivalent to
+the default operation of @code{filter-buffer-substring}, i.e. it
+returns the buffer-substring between @var{start} and @var{end}
+(processed by any @code{buffer-substring-filters}) and optionally
+deletes the original text from the buffer.  In most cases, the hook
+function will call @var{fun} once, and then do its own processing of
+the result.  The next hook function receives a @var{fun} equivalent to
+this, and so on.  The actual return value is the result of all the
+hook functions acting in sequence.
 @end defvar
 
 @defun buffer-string
@@ -500,6 +502,11 @@ syntax. (@xref{Abbrevs}, and @ref{Syntax Class Table}.)  It is also
 responsible for calling @code{blink-paren-function} when the inserted
 character has close parenthesis syntax (@pxref{Blinking}).
 
+@vindex post-self-insert-hook
+The final thing this command does is to run the hook
+@code{post-self-insert-hook}.  You could use this to automatically
+reindent text as it is typed, for example.
+
 Do not try substituting your own definition of
 @code{self-insert-command} for the standard one.  The editor command
 loop handles this function specially.
diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi
index 9e0c439e57e..bdb16cd10a8 100644
--- a/doc/lispref/variables.texi
+++ b/doc/lispref/variables.texi
@@ -9,16 +9,13 @@
 
   A @dfn{variable} is a name used in a program to stand for a value.
 In Lisp, each variable is represented by a Lisp symbol
-(@pxref{Symbols}).  The symbol's name serves as the variable name, and
-the symbol's value cell holds the variable's value@footnote{Strictly
-speaking, the symbol's value cell always holds the variable's current
-value under the default @dfn{dynamic binding} rules.  Under
-@dfn{lexical binding} rules, the value cell holds the variable's
-@dfn{global value}.  @xref{Variable Scoping}, for details.}.
-@xref{Symbol Components}.
-
-  In Emacs Lisp, the use of a symbol as a variable is independent of
-its use as a function name.
+(@pxref{Symbols}).  The variable name is simply the symbol's name, and
+the variable's value is stored in the symbol's value cell@footnote{To
+be precise, under the default @dfn{dynamic binding} rules the value
+cell always holds the variable's current value, but this is not the
+case under @dfn{lexical binding} rules.  @xref{Variable Scoping}, for
+details.}.  @xref{Symbol Components}.  In Emacs Lisp, the use of a
+symbol as a variable is independent of its use as a function name.
 
   As previously noted in this manual, a Lisp program is represented
 primarily by Lisp objects, and only secondarily as text.  The textual
@@ -151,8 +148,8 @@ does not raise an error if you actually change it.
 with new values.  Sometimes it is useful to give a variable a
 @dfn{local value}---a value that takes effect only within a certain
 part of a Lisp program.  When a variable has a local value, we say
-that it has a @dfn{local binding}, or that it is a @dfn{local
-variable}.
+that it is @dfn{locally bound} to that value, and that it is a
+@dfn{local variable}.
 
   For example, when a function is called, its argument variables
 receive local values, which are the actual arguments supplied to the
@@ -186,10 +183,10 @@ local binding.  To be more precise, a rule called the @dfn{scoping
 rule} determines where in a program a local binding takes effect.  The
 default scoping rule in Emacs Lisp is called @dfn{dynamic scoping},
 which simply states that the current binding at any given point in the
-execution of a program is the most recently-created local binding for
-that variable that still exists.  For details about dynamic scoping,
-and an alternative scoping rule called @dfn{lexical scoping},
-@xref{Variable Scoping}.
+execution of a program is the most recently-created binding for that
+variable that still exists.  For details about dynamic scoping, and an
+alternative scoping rule called @dfn{lexical scoping}, @xref{Variable
+Scoping}.
 
   The special forms @code{let} and @code{let*} exist to create local
 bindings:
@@ -294,27 +291,27 @@ has room to execute.
 @cindex @code{void-variable} error
 @cindex void variable
 
-  If you have never given a symbol any value as a global variable, we
-say that that symbol's global value is @dfn{void}.  Note that this
-does @emph{not} mean the value is @code{nil}.  The symbol @code{nil}
-is a Lisp object and can be the value of a variable, just as any other
-object can be; but it is still a value.
-
-  More precisely, a variable is void if its symbol has an unassigned
-value cell (@pxref{Symbol Components}).  Under Emacs Lisp's default
-dynamic binding rules, the value cell stores the variable's current
-(local or global) value; if a variable is void, trying to evaluate the
-variable signals a @code{void-variable} error rather than a value.
-But when a variable is lexically bound, it can have a local value
-which is determined by the lexical environment, even if the value cell
-is empty and the variable is technically void.  @xref{Variable
-Scoping}.
+  We say that a variable is void if its symbol has an unassigned value
+cell (@pxref{Symbol Components}).  Under Emacs Lisp's default dynamic
+binding rules (@pxref{Variable Scoping}), the value cell stores the
+variable's current (local or global) value.  Note that an unassigned
+value cell is @emph{not} the same as having @code{nil} in the value
+cell.  The symbol @code{nil} is a Lisp object and can be the value of
+a variable, just as any other object can be; but it is still a value.
+If a variable is void, trying to evaluate the variable signals a
+@code{void-variable} error rather than a value.
+
+  Under lexical binding rules, the value cell only holds the
+variable's global value, i.e.@: the value outside of any lexical
+binding contruct.  When a variable is lexically bound, the local value
+is determined by the lexical environment; the variable may have a
+local value if its symbol's value cell is unassigned.
 
 @defun makunbound symbol
 This function empties out the value cell of @var{symbol}, making the
 variable void.  It returns @var{symbol}.
 
-If @var{symbol} has a (dynamic) local binding, @code{makunbound} voids
+If @var{symbol} has a dynamic local binding, @code{makunbound} voids
 the current binding, and this voidness lasts only as long as the local
 binding is in effect.  Afterwards, the previously shadowed local or
 global binding is reexposed; then the variable will no longer be void,
@@ -615,15 +612,15 @@ name in the text of the program.  You can use the @code{symbol-value}
 function to extract the value.
 
 @defun symbol-value symbol
-This function returns the value of @var{symbol}.  This is the value in
-the symbol's value cell, which is where the variable's current
-(dynamic) value is stored.  If the variable has no local binding, this
-is simply its global value.
+This function returns the value stored in @var{symbol}'s value cell.
+This is where the variable's current (dynamic) value is stored.  If
+the variable has no local binding, this is simply its global value.
+If the variable is void, a @code{void-variable} error is signaled.
 
 If the variable is lexically bound, the value reported by
-@code{symbol-value} is the dynamic value, and not the local lexical
-value (which is determined by the lexical environment rather than the
-symbol's value cell).  @xref{Variable Scoping}.
+@code{symbol-value} is not necessarily the same as the variable's
+lexical value, which is determined by the lexical environment rather
+than the symbol's value cell.  @xref{Variable Scoping}.
 
 @example
 @group
@@ -657,9 +654,6 @@ symbol's value cell).  @xref{Variable Scoping}.
      @result{} 5
 @end group
 @end example
-
-A @code{void-variable} error is signaled if @var{symbol} is void as a
-variable.
 @end defun
 
 @node Setting Variables
@@ -945,13 +939,13 @@ construct.
 
 @example
 @group
-(defun getx ()
-  x)            ; @r{@code{x} is used ``free'' in this function.}
-
 (let ((x 1))    ; @r{@code{x} is lexically bound.}
   (+ x 3))
      @result{} 4
 
+(defun getx ()
+  x)            ; @r{@code{x} is used ``free'' in this function.}
+
 (let ((x 1))    ; @r{@code{x} is lexically bound.}
   (getx))
 @error{} Symbol's value as variable is void: x
@@ -972,20 +966,18 @@ itself.
 within the construct and their local values.  When the Lisp evaluator
 wants the current value of a variable, it looks first in the lexical
 environment; if the variable is not specified in there, it looks in
-the symbol's value cell, where the dynamical value is stored.
+the symbol's value cell, where the dynamic value is stored.
 
 @cindex closures
   Lexical bindings have indefinite extent.  Even after a binding
 construct has finished executing, its lexical environment can be
 ``kept around'' in Lisp objects called @dfn{closures}.  A closure is
-created whenever you evaluate a lambda expression (@pxref{Lambda
-Expressions}) with lexical binding enabled.  It is represented by a
-list whose @sc{car} is the symbol @code{closure}.  It is a function,
-in the sense that it can be passed as an argument to @code{funcall};
-when called as a function, any lexical variable references within its
-definition will use the retained lexical environment.
+created when you create a named or anonymous function with lexical
+binding enabled.  @xref{Closures}, for details.
 
-  Here is an example which illustrates the use of a closure:
+  When a closure is called as a function, any lexical variable
+references within its definition use the retained lexical environment.
+Here is an example:
 
 @example
 (defvar my-ticker nil)   ; @r{We will use this dynamically bound}
@@ -1199,7 +1191,8 @@ foo @result{} 'a
 @end group
 @end example
 
-  Note that references to @code{foo} in @var{body} access the
+@noindent
+Note that references to @code{foo} in @var{body} access the
 buffer-local binding of buffer @samp{b}.
 
   When a file specifies local variable values, these become buffer-local
@@ -1642,6 +1635,11 @@ For boolean-valued variables that are safe, use @code{booleanp} as the
 property value.  Lambda expressions should be quoted so that
 @code{describe-variable} can display the predicate.
 
+  When defining a user option using @code{defcustom}, you can set its
+@code{safe-local-variable} property by adding the arguments
+@code{:safe @var{function}} to @code{defcustom} (@pxref{Variable
+Definitions}).
+
 @defopt safe-local-variable-values
 This variable provides another way to mark some variable values as
 safe.  It is a list of cons cells @code{(@var{var} . @var{val})},
@@ -1661,28 +1659,31 @@ the value @var{val}, based on the above criteria.
 @end defun
 
 @c @cindex risky local variable   Duplicates risky-local-variable
-  Some variables are considered @dfn{risky}.  A variable whose name
-ends in any of @samp{-command}, @samp{-frame-alist}, @samp{-function},
+  Some variables are considered @dfn{risky}.  If a variable is risky,
+it is never entered automatically into
+@code{safe-local-variable-values}; Emacs always queries before setting
+a risky variable, unless the user explicitly allows a value by
+customizing @code{safe-local-variable-values} directly.
+
+  Any variable whose name has a non-@code{nil}
+@code{risky-local-variable} property is considered risky.  When you
+define a user option using @code{defcustom}, you can set its
+@code{risky-local-variable} property by adding the arguments
+@code{:risky @var{value}} to @code{defcustom} (@pxref{Variable
+Definitions}).  In addition, any variable whose name ends in any of
+@samp{-command}, @samp{-frame-alist}, @samp{-function},
 @samp{-functions}, @samp{-hook}, @samp{-hooks}, @samp{-form},
 @samp{-forms}, @samp{-map}, @samp{-map-alist}, @samp{-mode-alist},
-@samp{-program}, or @samp{-predicate} is considered risky.  The
-variables @samp{font-lock-keywords}, @samp{font-lock-keywords}
-followed by a digit, and @samp{font-lock-syntactic-keywords} are also
-considered risky.  Finally, any variable whose name has a
-non-@code{nil} @code{risky-local-variable} property is considered
-risky.
+@samp{-program}, or @samp{-predicate} is automatically considered
+risky.  The variables @samp{font-lock-keywords},
+@samp{font-lock-keywords} followed by a digit, and
+@samp{font-lock-syntactic-keywords} are also considered risky.
 
 @defun risky-local-variable-p sym
 This function returns non-@code{nil} if @var{sym} is a risky variable,
 based on the above criteria.
 @end defun
 
-  If a variable is risky, it will not be entered automatically into
-@code{safe-local-variable-values} as described above.  Therefore,
-Emacs will always query before setting a risky variable, unless the
-user explicitly allows the setting by customizing
-@code{safe-local-variable-values} directly.
-
 @defvar ignored-local-variables
 This variable holds a list of variables that should not be given local
 values by files.  Any value specified for one of these variables is
diff --git a/doc/lispref/vol1.texi b/doc/lispref/vol1.texi
index 95f9f7f4d29..0f4a4447ed3 100644
--- a/doc/lispref/vol1.texi
+++ b/doc/lispref/vol1.texi
@@ -390,6 +390,7 @@ Evaluation
 * Forms::                   How various sorts of objects are evaluated.
 * Quoting::                 Avoiding evaluation (to put constants in
                               the program).
+* Backquote::               Easier construction of list structure.
 * Eval::                    How to invoke the Lisp interpreter explicitly.
 
 Kinds of Forms
@@ -478,6 +479,7 @@ Functions
 * Anonymous Functions::     Lambda expressions are functions with no names.
 * Function Cells::          Accessing or setting the function definition
                               of a symbol.
+* Closures::                Functions that enclose a lexical environment.
 * Obsolete Functions::      Declaring functions obsolete.
 * Inline Functions::        Defining functions that the compiler
                               will open code.
@@ -500,7 +502,6 @@ Macros
 * Expansion::               How, when and why macros are expanded.
 * Compiling Macros::        How macros are expanded by the compiler.
 * Defining Macros::         How to write a macro definition.
-* Backquote::               Easier construction of list structure.
 * Problems with Macros::    Don't evaluate the macro arguments too many times.
                               Don't hide the user's variables.
 * Indenting Macros::        Specifying how to indent macro calls.
@@ -1372,6 +1373,7 @@ Images
 * Defining Images::         Convenient ways to define an image for later use.
 * Showing Images::          Convenient ways to display an image once
                               it is defined.
+* Animated Images::         Some image formats can be animated.
 * Image Cache::             Internal mechanisms of image display.
 
 Buttons
diff --git a/doc/lispref/vol2.texi b/doc/lispref/vol2.texi
index 08ea022f6a7..241728fd1d2 100644
--- a/doc/lispref/vol2.texi
+++ b/doc/lispref/vol2.texi
@@ -389,6 +389,7 @@ Evaluation
 * Forms::                   How various sorts of objects are evaluated.
 * Quoting::                 Avoiding evaluation (to put constants in
                               the program).
+* Backquote::               Easier construction of list structure.
 * Eval::                    How to invoke the Lisp interpreter explicitly.
 
 Kinds of Forms
@@ -477,6 +478,7 @@ Functions
 * Anonymous Functions::     Lambda expressions are functions with no names.
 * Function Cells::          Accessing or setting the function definition
                               of a symbol.
+* Closures::                Functions that enclose a lexical environment.
 * Obsolete Functions::      Declaring functions obsolete.
 * Inline Functions::        Defining functions that the compiler
                               will open code.
@@ -499,7 +501,6 @@ Macros
 * Expansion::               How, when and why macros are expanded.
 * Compiling Macros::        How macros are expanded by the compiler.
 * Defining Macros::         How to write a macro definition.
-* Backquote::               Easier construction of list structure.
 * Problems with Macros::    Don't evaluate the macro arguments too many times.
                               Don't hide the user's variables.
 * Indenting Macros::        Specifying how to indent macro calls.
@@ -1371,6 +1372,7 @@ Images
 * Defining Images::         Convenient ways to define an image for later use.
 * Showing Images::          Convenient ways to display an image once
                               it is defined.
+* Animated Images::         Some image formats can be animated.
 * Image Cache::             Internal mechanisms of image display.
 
 Buttons
diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog
index d1a045a730a..6bb1e065d37 100644
--- a/doc/misc/ChangeLog
+++ b/doc/misc/ChangeLog
@@ -1,3 +1,8 @@
+2012-01-30  Philipp Haselwarter  <philipp.haselwarter@gmx.de>  (tiny change)
+
+        * gnus.texi (Agent Basics): Fix outdated description of
+        `gnus-agent-auto-agentize-methods'.
+
 2012-01-28  Andreas Schwab  <schwab@linux-m68k.org>
 
         * cc-mode.texi: Always @defindex ss.
diff --git a/doc/misc/gnus.texi b/doc/misc/gnus.texi
index 7728041c83b..1883975b7f6 100644
--- a/doc/misc/gnus.texi
+++ b/doc/misc/gnus.texi
@@ -18236,8 +18236,7 @@ Agent.  Go to the server buffer (@kbd{^} in the group buffer) and press
 @kbd{J a} on the server (or servers) that you wish to have covered by the
 Agent (@pxref{Server Agent Commands}), or @kbd{J r} on automatically
 added servers you do not wish to have covered by the Agent.  By default,
-all @code{nntp} and @code{nnimap} servers in @code{gnus-select-method} and
-@code{gnus-secondary-select-methods} are agentized.
+no servers are agentized.
 
 @item
 Decide on download policy.  It's fairly simple once you decide whether
@@ -19263,7 +19262,7 @@ to agentize remote back ends.  The auto-agentizing has the same effect
 as running @kbd{J a} on the servers (@pxref{Server Agent Commands}).
 If the file exist, you must manage the servers manually by adding or
 removing them, this variable is only applicable the first time you
-start Gnus.  The default is @samp{(nntp nnimap)}.
+start Gnus.  The default is @samp{nil}.
 
 @end table