Merge changes from emacs-24 branch

32 files changed, 419 insertions, 301 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 5333e3af3df..9c323d7937f 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,54 @@
+2012-04-27  Glenn Morris  <rgm@gnu.org>
+
+	* elisp.texi, vol1.texi, vol2.texi: Some fixes for detailed menu.
+	* modes.texi (Major Modes, Auto-Indentation):
+	* buffers.texi (Buffers): Some fixes for menu descriptions.
+
+2012-04-27  Stefan Monnier  <monnier@iro.umontreal.ca>
+	* functions.texi (Simple Lambda, Argument List):
+	* eval.texi (Function Indirection): Avoid deprecated form.
+
+2012-04-27  Glenn Morris  <rgm@gnu.org>
+
+	* book-spine.texi, elisp.texi, vol1.texi, vol2.texi:
+	Add "et al." to authors.
+
+	* buffers.texi, commands.texi, compile.texi, control.texi:
+	* customize.texi, display.texi, eval.texi, files.texi, frames.texi:
+	* hash.texi, help.texi, intro.texi, keymaps.texi, lists.texi:
+	* modes.texi, numbers.texi, objects.texi, streams.texi:
+	* symbols.texi, syntax.texi, text.texi, tips.texi, variables.texi:
+	Use Texinfo recommended convention for quotes+punctuation.
+
+2012-04-27  Chong Yidong  <cyd@gnu.org>
+
+	* keymaps.texi (Scanning Keymaps): Fix description of NO-REMAP arg
+	to where-is-internal (Bug#10872).
+
+2012-04-27  Glenn Morris  <rgm@gnu.org>
+
+	* macros.texi (Indenting Macros): Fix typo.
+
+	* windows.texi (Basic Windows, Windows and Frames, Window Sizes)
+	(Resizing Windows, Deleting Windows, Selecting Windows)
+	(Choosing Window Options, Horizontal Scrolling)
+	(Cyclic Window Ordering, Window History, Dedicated Windows)
+	(Quitting Windows, Window Configurations, Textual Scrolling):
+	(Coordinates and Windows, Window Configurations)
+	(Window Parameters, Window Hooks): Copyedits.
+	(Splitting Windows, Deleting Windows):
+	Fix ignore-window-parameters logic.
+	(Selecting Windows, Choosing Window Options): Markup fixes.
+	(Window Start and End): Remove pointless example.
+	Remove cross-reference to deleted count-lines content.
+	(Textual Scrolling): Mention recenter-redisplay, recenter-top-bottom,
+	and recenter-positions.  Remove recenter example.
+
+	* elisp.texi, vol1.texi, vol2.texi: Bump VERSION and DATE.
+
+	* minibuf.texi (Intro to Minibuffers):
+	Tweak discussion of resizing minibuffer window.
+
 2012-04-26  Glenn Morris  <rgm@gnu.org>
 
 	* elisp-covers.texi, front-cover-1.texi: Remove files.
diff --git a/doc/lispref/book-spine.texi b/doc/lispref/book-spine.texi
index 270def6d8b3..721416316d2 100644
--- a/doc/lispref/book-spine.texi
+++ b/doc/lispref/book-spine.texi
@@ -20,8 +20,8 @@
 @center by
 @center Bil Lewis,
 @center Dan LaLiberte,
-@center and the
-@center GNU Manual Group
+@center the GNU Manual Group,
+@center et al.
 @sp 5
 @center Free Software Foundation
 @bye
diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi
index 844b6423a52..165faf32b09 100644
--- a/doc/lispref/buffers.texi
+++ b/doc/lispref/buffers.texi
@@ -23,7 +23,7 @@ not be displayed in any windows.
 * Buffer File Name::    The buffer file name indicates which file is visited.
 * Buffer Modification:: A buffer is @dfn{modified} if it needs to be saved.
 * Modification Time::   Determining whether the visited file was changed
-                         ``behind Emacs's back''.
+                         "behind Emacs's back".
 * Read Only Buffers::   Modifying text is not allowed in a read-only buffer.
 * The Buffer List::     How to look at all the existing buffers.
 * Creating Buffers::    Functions that create buffers.
@@ -481,7 +481,7 @@ correspond to the new file name, unless the new name is already in
 use.
 
 If @var{filename} is @code{nil} or the empty string, that stands for
-``no visited file.''  In this case, @code{set-visited-file-name} marks
+``no visited file''.  In this case, @code{set-visited-file-name} marks
 the buffer as having no visited file, without changing the buffer's
 modified flag.
 
diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi
index bf26d83b7bf..dea838462bb 100644
--- a/doc/lispref/commands.texi
+++ b/doc/lispref/commands.texi
@@ -718,7 +718,7 @@ We use @code{"p"} because the numeric prefix argument is never
 message when called from a keyboard macro.
 
   The above method with the additional argument is usually best,
-because it allows callers to say ``treat this call as interactive.''
+because it allows callers to say ``treat this call as interactive''.
 But you can also do the job by testing @code{called-interactively-p}.
 
 @defun called-interactively-p kind
@@ -2325,7 +2325,7 @@ same symbol that would normally represent that combination of mouse
 button and modifier keys.  The information about the window part is kept
 elsewhere in the event---in the coordinates.  But
 @code{read-key-sequence} translates this information into imaginary
-``prefix keys,'' all of which are symbols: @code{header-line},
+``prefix keys'', all of which are symbols: @code{header-line},
 @code{horizontal-scroll-bar}, @code{menu-bar}, @code{mode-line},
 @code{vertical-line}, and @code{vertical-scroll-bar}.  You can define
 meanings for mouse clicks in special window parts by defining key
@@ -2705,7 +2705,7 @@ individual events, which you can put in @code{unread-command-events}.
 
 @defvar unread-command-char
 This variable holds a character to be read as command input.
-A value of -1 means ``empty.''
+A value of -1 means ``empty''.
 
 This variable is mostly obsolete now that you can use
 @code{unread-command-events} instead; it exists only to support programs
@@ -3195,7 +3195,7 @@ using the minibuffer.  Usually it is more convenient for the user if you
 change the major mode of the current buffer temporarily to a special
 major mode, which should have a command to go back to the previous mode.
 (The @kbd{e} command in Rmail uses this technique.)  Or, if you wish to
-give the user different text to edit ``recursively,'' create and select
+give the user different text to edit ``recursively'', create and select
 a new buffer in a special mode.  In this mode, define a command to
 complete the processing and go back to the previous buffer.  (The
 @kbd{m} command in Rmail does this.)
diff --git a/doc/lispref/compile.texi b/doc/lispref/compile.texi
index ead75942b24..8cebd9fade6 100644
--- a/doc/lispref/compile.texi
+++ b/doc/lispref/compile.texi
@@ -274,7 +274,7 @@ reloading each file after recompiling it.
 use a special Lisp reader construct, @samp{#@@@var{count}}.  This
 construct skips the next @var{count} characters.  It also uses the
 @samp{#$} construct, which stands for ``the name of this file, as a
-string.''  It is usually best not to use these constructs in Lisp source
+string''.  It is usually best not to use these constructs in Lisp source
 files, since they are not designed to be clear to humans reading the
 file.
 
diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi
index aa24291d892..d6dee7ecf91 100644
--- a/doc/lispref/control.texi
+++ b/doc/lispref/control.texi
@@ -220,7 +220,7 @@ non-@code{nil}, the clause ``succeeds''; then @code{cond} evaluates its
 @var{body-forms}, and the value of the last of @var{body-forms} becomes
 the value of the @code{cond}.  The remaining clauses are ignored.
 
-If the value of @var{condition} is @code{nil}, the clause ``fails,'' so
+If the value of @var{condition} is @code{nil}, the clause ``fails'', so
 the @code{cond} moves on to the following clause, trying its
 @var{condition}.
 
@@ -622,7 +622,7 @@ error is signaled with data @code{(@var{tag} @var{value})}.
 @subsection Examples of @code{catch} and @code{throw}
 
   One way to use @code{catch} and @code{throw} is to exit from a doubly
-nested loop.  (In most languages, this would be done with a ``goto.'')
+nested loop.  (In most languages, this would be done with a ``goto''.)
 Here we compute @code{(foo @var{i} @var{j})} for @var{i} and @var{j}
 varying from 0 to 9:
 
diff --git a/doc/lispref/customize.texi b/doc/lispref/customize.texi
index 04b3cdd11f0..c8e60fd84f4 100644
--- a/doc/lispref/customize.texi
+++ b/doc/lispref/customize.texi
@@ -817,7 +817,7 @@ For example,
 
 @noindent
 describes a variable for which @code{t} means yes, @code{nil} means no,
-and @code{foo} means ``ask.''
+and @code{foo} means ``ask''.
 
 @item (other @var{value})
 This alternative can match any Lisp value, but if the user chooses this
@@ -834,7 +834,7 @@ For example,
 
 @noindent
 describes a variable for which @code{t} means yes, @code{nil} means no,
-and anything else means ``ask.''  If the user chooses @samp{Ask} from
+and anything else means ``ask''.  If the user chooses @samp{Ask} from
 the menu of alternatives, that specifies the value @code{foo}; but any
 other value (not @code{t}, @code{nil} or @code{foo}) displays as
 @samp{Ask}, just like @code{foo}.
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 0113ae86358..4ec3b8bf08a 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -155,7 +155,7 @@ boundary.  @xref{Filling}.
 indicate truncated and continued lines (@pxref{Fringes}).  On a text
 terminal, a @samp{$} in the rightmost column of the window indicates
 truncation; a @samp{\} on the rightmost column indicates a line that
-``wraps.''  (The display table can specify alternate characters to use
+``wraps''.  (The display table can specify alternate characters to use
 for this; @pxref{Display Tables}).
 
 @defopt truncate-lines
@@ -451,7 +451,7 @@ prints the message of @var{reporter} followed by word ``done'' in the
 echo area.
 
 You should always call this function and not hope for
-@code{progress-reporter-update} to print ``100%.''  Firstly, it may
+@code{progress-reporter-update} to print ``100%''.  Firstly, it may
 never print it, there are many good reasons for this not to happen.
 Secondly, ``done'' is more explicit.
 @end defun
@@ -1308,7 +1308,7 @@ The return value is @var{overlay}.
 This is the only valid way to change the endpoints of an overlay.  Do
 not try modifying the markers in the overlay by hand, as that fails to
 update other vital data structures and can cause some overlays to be
-``lost.''
+``lost''.
 @end defun
 
 @defun remove-overlays &optional start end name value
@@ -1385,7 +1385,7 @@ foo
 @end example
 
   Emacs stores the overlays of each buffer in two lists, divided
-around an arbitrary ``center position.''  One list extends backwards
+around an arbitrary ``center position''.  One list extends backwards
 through the buffer from that center position, and the other extends
 forwards from that center position.  The center position can be anywhere
 in the buffer.
@@ -4359,7 +4359,7 @@ $$\pmatrix{ 2 & -1 &  0 \cr
 @end ifnottex
 
 @item disabled
-Specifies transforming the image so that it looks ``disabled.''
+Specifies transforming the image so that it looks ``disabled''.
 @end table
 
 @item :mask @var{mask}
@@ -5531,7 +5531,7 @@ Any @var{args} are passed to @var{map-function}.
 @subsection Abstract Display Example
 
   Here is a simple example using functions of the ewoc package to
-implement a ``color components display,'' an area in a buffer that
+implement a ``color components display'', an area in a buffer that
 represents a vector of three integers (itself representing a 24-bit RGB
 value) in various ways.
 
@@ -5842,7 +5842,7 @@ display the character @var{c} as those glyphs; @pxref{Glyphs}).
 
   @strong{Warning:} if you use the display table to change the display
 of newline characters, the whole buffer will be displayed as one long
-``line.''
+``line''.
 
   The display table also has six ``extra slots'' which serve special
 purposes.  Here is a table of their meanings; @code{nil} in any slot
@@ -6153,7 +6153,7 @@ capability (@samp{vb}).
 
 @defvar ring-bell-function
 If this is non-@code{nil}, it specifies how Emacs should ``ring the
-bell.''  Its value should be a function of no arguments.  If this is
+bell''.  Its value should be a function of no arguments.  If this is
 non-@code{nil}, it takes precedence over the @code{visible-bell}
 variable.
 @end defvar
@@ -6162,7 +6162,7 @@ variable.
 @section Window Systems
 
   Emacs works with several window systems, most notably the X Window
-System.  Both Emacs and X use the term ``window,'' but use it
+System.  Both Emacs and X use the term ``window'', but use it
 differently.  An Emacs frame is a single window as far as X is
 concerned; the individual Emacs windows are not known to X at all.
 
diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index 4319d5eddda..9c5ae73f718 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -5,11 +5,10 @@
 @c %**end of header
 
 @c Version of the manual and of Emacs.
-@c Please remember to update the edition number in README as well.
-@c And also the copies in vol1.texi and vol2.texi.
-@set VERSION  3.0
+@c Please remember to update these in vol1.texi and vol2.texi as well.
+@set VERSION  3.1
 @include emacsver.texi
-@set DATE July 2009
+@set DATE July 2012
 
 @c in general, keep the following line commented out, unless doing a
 @c copy of this manual that will be published.  The manual should go
@@ -73,8 +72,8 @@ developing GNU and promoting software freedom.''
 @subtitle For Emacs Version @value{EMACSVER}
 @subtitle Revision @value{VERSION}, @value{DATE}
 
-@author by Bil Lewis, Dan LaLiberte, Richard Stallman
-@author and the GNU Manual Group
+@author by Bil Lewis, Dan LaLiberte, Richard Stallman,
+@author the GNU Manual Group, et al.
 @page
 @vskip 0pt plus 1filll
 @insertcopying
@@ -460,7 +459,7 @@ Functions
 * Closures::                Functions that enclose a lexical environment.
 * Obsolete Functions::      Declaring functions obsolete.
 * Inline Functions::        Defining functions that the compiler
-                              will open code.
+                              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
@@ -493,7 +492,7 @@ Common Problems Using Macros
 * Eval During Expansion::  Don't evaluate them; put them in the expansion.
 * Repeated Expansion::     Avoid depending on how many times expansion is done.
 
-Writing Customization Definitions
+Customization Settings
 
 * Common Keywords::         Common keyword arguments for all kinds of
                               customization declarations.
@@ -754,6 +753,7 @@ Defining Menus
                               various features.
 * Menu Separators::         Drawing a horizontal line through a menu.
 * Alias Menu Items::        Using command aliases in menu items.
+* Toolkit Differences::     Not all toolkits provide the same features.
 
 Major and Minor Modes
 
@@ -824,6 +824,21 @@ Multiline Font Lock Constructs
 * Region to Refontify::     Controlling which region gets refontified
                               after a buffer change.
 
+Automatic Indentation of code
+
+* SMIE::                    A simple minded indentation engine.
+
+Simple Minded Indentation Engine
+
+* SMIE setup::              SMIE setup and features.
+* Operator Precedence Grammars:: A very simple parsing technique.
+* SMIE Grammar::            Defining the grammar of a language.
+* SMIE Lexer::              Defining tokens.
+* SMIE Tricks::             Working around the parser's limitations.
+* SMIE Indentation::        Specifying indentation rules.
+* SMIE Indentation Helpers:: Helper functions for indentation rules.
+* SMIE Indentation Example:: Sample indentation rules.
+
 Documentation
 
 * Documentation Basics::    Where doc strings are defined and stored.
@@ -1220,8 +1235,7 @@ Processes
 * Datagrams::               UDP network connections.
 * Low-Level Network::       Lower-level but more general function
                               to create connections and servers.
-* Misc Network::            Additional relevant functions for
-                              network connections.
+* Misc Network::            Additional relevant functions for net connections.
 * Serial Ports::            Communicating with serial ports.
 * Byte Packing::            Using bindat to pack and unpack binary data.
 
@@ -1341,6 +1355,7 @@ Images
 * GIF Images::              Special features for GIF format.
 * TIFF Images::             Special features for TIFF format.
 * PostScript Images::       Special features for PostScript format.
+* ImageMagick Images::      Special features available through ImageMagick.
 * 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
@@ -1396,13 +1411,6 @@ Operating System Interface
 * Notifications::           Desktop notifications.
 * Dynamic Libraries::       On-demand loading of support libraries.
 
-Preparing Lisp code for distribution
-
-* Packaging Basics::        The basic concepts of Emacs Lisp packages.
-* Simple Packages::         How to package a single .el file.
-* Multi-file Packages::     How to package multiple files.
-* Package Archives::        Maintaining package archives.
-
 Starting Up Emacs
 
 * Startup Summary::         Sequence of actions Emacs performs at startup.
@@ -1421,6 +1429,13 @@ Terminal Input
 * Input Modes::             Options for how input is processed.
 * Recording Input::         Saving histories of recent or all input events.
 
+Preparing Lisp code for distribution
+
+* Packaging Basics::        The basic concepts of Emacs Lisp packages.
+* Simple Packages::         How to package a single .el file.
+* Multi-file Packages::     How to package multiple files.
+* Package Archives::        Maintaining package archives.
+
 Tips and Conventions
 
 * Coding Conventions::      Conventions for clean and robust programs.
diff --git a/doc/lispref/eval.texi b/doc/lispref/eval.texi
index 4c1150d1a51..76059079ca1 100644
--- a/doc/lispref/eval.texi
+++ b/doc/lispref/eval.texi
@@ -103,7 +103,7 @@ interpretation.  @xref{Command Loop}.
 @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
+types''.  This section describes all three kinds, one by one, starting
 with the ``all other types'' which are self-evaluating forms.
 
 @menu
@@ -304,6 +304,22 @@ function, not a symbol.
 Executing the function itself evaluates its body; this does involve
 symbol function indirection when calling @code{erste}.
 
+  This form is rarely used and is now deprecated.  Instead, you should write it
+as:
+
+@smallexample
+@group
+(funcall (lambda (arg) (erste arg))
+         '(1 2 3))
+@end group
+@end smallexample
+or just
+@smallexample
+@group
+(let ((arg '(1 2 3))) (erste arg))
+@end group
+@end smallexample
+
   The built-in function @code{indirect-function} provides an easy way to
 perform symbol function indirection explicitly.
 
diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index 3597d9f80c4..1af904aff41 100644
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -71,8 +71,8 @@ back into the file.
 
   In spite of the distinction between files and buffers, people often
 refer to a file when they mean a buffer and vice-versa.  Indeed, we say,
-``I am editing a file,'' rather than, ``I am editing a buffer that I
-will soon save as a file of the same name.''  Humans do not usually need
+``I am editing a file'', rather than, ``I am editing a buffer that I
+will soon save as a file of the same name''.  Humans do not usually need
 to make the distinction explicit.  When dealing with a computer program,
 however, it is good to keep the distinction in mind.
 
@@ -688,7 +688,7 @@ The file lock is really a file, a symbolic link with a special name,
 stored in the same directory as the file you are editing.
 
   When you access files using NFS, there may be a small probability that
-you and another user will both lock the same file ``simultaneously.''
+you and another user will both lock the same file ``simultaneously''.
 If this happens, it is possible for the two users to make changes
 simultaneously, but Emacs will still warn the user who saves second.
 Also, the detection of modification of a buffer visiting a file changed
@@ -1806,7 +1806,7 @@ return value, but backup version numbers are kept.
 @end defun
 
 @defun file-name-extension filename &optional period
-This function returns @var{filename}'s final ``extension,'' if any,
+This function returns @var{filename}'s final ``extension'', if any,
 after applying @code{file-name-sans-versions} to remove any
 version/backup part.  The extension, in a file name, is the part that
 follows the last @samp{.} in the last name component (minus any
@@ -2798,7 +2798,7 @@ unlocking the buffer if it is locked.
 possibly others to be added in the future.  It need not implement all
 these operations itself---when it has nothing special to do for a
 certain operation, it can reinvoke the primitive, to handle the
-operation ``in the usual way.''  It should always reinvoke the primitive
+operation ``in the usual way''.  It should always reinvoke the primitive
 for an operation it does not recognize.  Here's one way to do this:
 
 @smallexample
diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index d824f51e47e..869f03e2273 100644
--- a/doc/lispref/frames.texi
+++ b/doc/lispref/frames.texi
@@ -882,7 +882,7 @@ This variable specifies how to blink the cursor.  Each element has the
 form @code{(@var{on-state} . @var{off-state})}.  Whenever the cursor
 type equals @var{on-state} (comparing using @code{equal}), the
 corresponding @var{off-state} specifies what the cursor looks like
-when it blinks ``off.''  Both @var{on-state} and @var{off-state}
+when it blinks ``off''.  Both @var{on-state} and @var{off-state}
 should be suitable values for the @code{cursor-type} frame parameter.
 
 There are various defaults for how to blink each type of cursor, if
@@ -1069,7 +1069,7 @@ characters rather than pixels.
 These values include the internal borders, and windows' scroll bars
 and fringes (which belong to individual windows, not to the frame
 itself).  The exact value of the heights depends on the window-system
-and toolkit in use.  With Gtk+, the height does not include any tool
+and toolkit in use.  With GTK+, the height does not include any tool
 bar or menu bar.  With the Motif or Lucid toolkits, it includes the
 tool bar but not the menu bar.  In a graphical version with no
 toolkit, it includes both the tool bar and menu bar.  For a text
@@ -1532,7 +1532,7 @@ track of such changes.  @xref{Misc Events}.
   Most window systems use a desktop metaphor.  Part of this metaphor is
 the idea that windows are stacked in a notional third dimension
 perpendicular to the screen surface, and thus ordered from ``highest''
-to ``lowest.''  Where two windows overlap, the one higher up covers
+to ``lowest''.  Where two windows overlap, the one higher up covers
 the one underneath.  Even a window at the bottom of the stack can be
 seen if no other window overlaps it.
 
@@ -1540,7 +1540,7 @@ seen if no other window overlaps it.
 @cindex lowering a frame
   A window's place in this ordering is not fixed; in fact, users tend
 to change the order frequently.  @dfn{Raising} a window means moving
-it ``up,'' to the top of the stack.  @dfn{Lowering} a window means
+it ``up'', to the top of the stack.  @dfn{Lowering} a window means
 moving it to the bottom of the stack.  This motion is in the notional
 third dimension only, and does not change the position of the window
 on the screen.
@@ -1814,7 +1814,7 @@ the menu keymap as necessary.
   A dialog box is a variant of a pop-up menu---it looks a little
 different, it always appears in the center of a frame, and it has just
 one level and one or more buttons.  The main use of dialog boxes is
-for asking questions that the user can answer with ``yes,'' ``no,''
+for asking questions that the user can answer with ``yes'', ``no'',
 and a few other alternatives.  With a single button, they can also
 force the user to acknowledge important information.  The functions
 @code{y-or-n-p} and @code{yes-or-no-p} use dialog boxes instead of the
@@ -2028,7 +2028,7 @@ colors.)
   These functions provide a way to determine which color names are
 valid, and what they look like.  In some cases, the value depends on the
 @dfn{selected frame}, as described below; see @ref{Input Focus}, for the
-meaning of the term ``selected frame.''
+meaning of the term ``selected frame''.
 
   To read user input of color names with completion, use
 @code{read-color} (@pxref{High-Level Completion, read-color}).
@@ -2425,7 +2425,7 @@ software (as a string).  Really this means whoever distributes the X
 server.
 
 When the developers of X labeled software distributors as
-``vendors,'' they showed their false assumption that no system could
+``vendors'', they showed their false assumption that no system could
 ever be developed and distributed noncommercially.
 @end defun
 
diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi
index 73bdefe19fc..b5cf38ed6f2 100644
--- a/doc/lispref/functions.texi
+++ b/doc/lispref/functions.texi
@@ -266,13 +266,12 @@ function is the value returned by the last element of the body.
 @end example
 
 @noindent
-We can call this function by writing it as the @sc{car} of an
-expression, like this:
+We can call this function by passing it to @code{funcall}, like this:
 
 @example
 @group
-((lambda (a b c) (+ a b c))
- 1 2 3)
+(funcall (lambda (a b c) (+ a b c))
+         1 2 3)
 @end group
 @end example
 
@@ -287,8 +286,8 @@ this example:
 
 @example
 @group
-((lambda (a b c) (+ a b c))
- 1 (* 2 3) (- 5 4))
+(funcall (lambda (a b c) (+ a b c))
+         1 (* 2 3) (- 5 4))
 @end group
 @end example
 
@@ -399,16 +398,16 @@ after a @code{&rest} argument.
   Here are some examples of argument lists and proper calls:
 
 @smallexample
-((lambda (n) (1+ n))                ; @r{One required:}
- 1)                                 ; @r{requires exactly one argument.}
+(funcall (lambda (n) (1+ n))        ; @r{One required:}
+         1)                         ; @r{requires exactly one argument.}
      @result{} 2
-((lambda (n &optional n1)           ; @r{One required and one optional:}
-         (if n1 (+ n n1) (1+ n)))   ; @r{1 or 2 arguments.}
- 1 2)
+(funcall (lambda (n &optional n1)   ; @r{One required and one optional:}
+           (if n1 (+ n n1) (1+ n))) ; @r{1 or 2 arguments.}
+         1 2)
      @result{} 3
-((lambda (n &rest ns)               ; @r{One required and one rest:}
-         (+ n (apply '+ ns)))       ; @r{1 or more arguments.}
- 1 2 3 4 5)
+(funcall (lambda (n &rest ns)       ; @r{One required and one rest:}
+           (+ n (apply '+ ns)))     ; @r{1 or more arguments.}
+         1 2 3 4 5)
      @result{} 15
 @end smallexample
 
diff --git a/doc/lispref/hash.texi b/doc/lispref/hash.texi
index 0ca4c915a65..1aa6004b3a6 100644
--- a/doc/lispref/hash.texi
+++ b/doc/lispref/hash.texi
@@ -74,13 +74,13 @@ alternatives:
 Keys which are numbers are ``the same'' if they are @code{equal}, that
 is, if they are equal in value and either both are integers or both
 are floating point numbers; otherwise, two distinct objects are never
-``the same.''
+``the same''.
 
 @item eq
 Any two distinct Lisp objects are ``different'' as keys.
 
 @item equal
-Two Lisp objects are ``the same,'' as keys, if they are equal
+Two Lisp objects are ``the same'', as keys, if they are equal
 according to @code{equal}.
 @end table
 
@@ -128,7 +128,7 @@ doing that takes some extra time.
 The default size is 65.
 
 @item :rehash-size @var{rehash-size}
-When you add an association to a hash table and the table is ``full,''
+When you add an association to a hash table and the table is ``full'',
 it grows automatically.  This value specifies how to make the hash table
 larger, at that time.
 
@@ -262,7 +262,7 @@ will use @var{test-fn} to compare key values, and @var{hash-fn} to compute
 a ``hash code'' from a key value.
 
 The function @var{test-fn} should accept two arguments, two keys, and
-return non-@code{nil} if they are considered ``the same.''
+return non-@code{nil} if they are considered ``the same''.
 
 The function @var{hash-fn} should accept one argument, a key, and return
 an integer that is the ``hash code'' of that key.  For good results, the
diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi
index 5dfb2b05ff8..762b42113f2 100644
--- a/doc/lispref/help.texi
+++ b/doc/lispref/help.texi
@@ -599,7 +599,7 @@ subcommands of the prefix key.
 
 @defopt help-event-list
 The value of this variable is a list of event types that serve as
-alternative ``help characters.''  These events are handled just like the
+alternative ``help characters''.  These events are handled just like the
 event specified by @code{help-char}.
 @end defopt
 
diff --git a/doc/lispref/intro.texi b/doc/lispref/intro.texi
index d3a5b253162..37d2cc55a9e 100644
--- a/doc/lispref/intro.texi
+++ b/doc/lispref/intro.texi
@@ -146,7 +146,7 @@ printer'' refer to those routines in Lisp that convert textual
 representations of Lisp objects into actual Lisp objects, and vice
 versa.  @xref{Printed Representation}, for more details.  You, the
 person reading this manual, are thought of as ``the programmer'' and are
-addressed as ``you.''  ``The user'' is the person who uses Lisp
+addressed as ``you''.  ``The user'' is the person who uses Lisp
 programs, including those you write.
 
 @cindex typographic conventions
@@ -219,7 +219,7 @@ the examples in this manual, this is indicated with @samp{@result{}}:
 @end example
 
 @noindent
-You can read this as ``@code{(car '(1 2))} evaluates to 1.''
+You can read this as ``@code{(car '(1 2))} evaluates to 1''.
 
   When a form is a macro call, it expands into a new form for Lisp to
 evaluate.  We show the result of the expansion with
diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi
index b12752fdeea..337364cb2ce 100644
--- a/doc/lispref/keymaps.texi
+++ b/doc/lispref/keymaps.texi
@@ -1032,7 +1032,7 @@ binding of @var{othertype} in @var{othermap} and uses that.
 This feature permits you to define one key as an alias for another key.
 For example, an entry whose @sc{car} is the keymap called @code{esc-map}
 and whose @sc{cdr} is 32 (the code for @key{SPC}) means, ``Use the global
-binding of @kbd{Meta-@key{SPC}}, whatever that may be.''
+binding of @kbd{Meta-@key{SPC}}, whatever that may be''.
 @end itemize
 
 @item @var{symbol}
@@ -1887,9 +1887,9 @@ maps searched are @var{keymap} and the global keymap.  If @var{keymap}
 is a list of keymaps, only those keymaps are searched.
 
 Usually it's best to use @code{overriding-local-map} as the expression
-for @var{keymap}.  Then @code{where-is-internal} searches precisely the
-keymaps that are active.  To search only the global map, pass
-@code{(keymap)} (an empty keymap) as @var{keymap}.
+for @var{keymap}.  Then @code{where-is-internal} searches precisely
+the keymaps that are active.  To search only the global map, pass the
+value @code{(keymap)} (an empty keymap) as @var{keymap}.
 
 If @var{firstonly} is @code{non-ascii}, then the value is a single
 vector representing the first key sequence found, rather than a list of
@@ -1903,20 +1903,24 @@ If @var{noindirect} is non-@code{nil}, @code{where-is-internal} doesn't
 follow indirect keymap bindings.  This makes it possible to search for
 an indirect definition itself.
 
-When command remapping is in effect (@pxref{Remapping Commands}),
-@code{where-is-internal} figures out when a command will be run due to
-remapping and reports keys accordingly.  It also returns @code{nil} if
-@var{command} won't really be run because it has been remapped to some
-other command.  However, if @var{no-remap} is non-@code{nil}.
-@code{where-is-internal} ignores remappings.
+The fifth argument, @var{no-remap}, determines how this function
+treats command remappings (@pxref{Remapping Commands}).  There are two
+cases of interest:
 
-@smallexample
-@group
-(where-is-internal 'describe-function)
-    @result{} ([8 102] [f1 102] [help 102]
-         [menu-bar help-menu describe describe-function])
-@end group
-@end smallexample
+@table @asis
+@item If a command @var{other-command} is remapped to @var{command}:
+If @var{no-remap} is @code{nil}, find the bindings for
+@var{other-command} and treat them as though they are also bindings
+for @var{command}.  If @var{no-remap} is non-@code{nil}, include the
+vector @code{[remap @var{other-command}]} in the list of possible key
+sequences, instead of finding those bindings.
+
+@item If @var{command} is remapped to @var{other-command}:
+If @var{no-remap} is @code{nil}, return the bindings for
+@var{other-command} rather than @var{command}.  If @var{no-remap} is
+non-@code{nil}, return the bindings for @var{command}, ignoring the
+fact that it is remapped.
+@end table
 @end defun
 
 @deffn Command describe-bindings &optional prefix buffer-or-name
@@ -2147,7 +2151,7 @@ This works because @code{toggle-debug-on-error} is defined as a command
 which toggles the variable @code{debug-on-error}.
 
 @dfn{Radio buttons} are a group of menu items, in which at any time one
-and only one is ``selected.''  There should be a variable whose value
+and only one is ``selected''.  There should be a variable whose value
 says which one is selected at any time.  The @var{selected} form for
 each radio button in the group should check whether the variable has the
 right value for selecting that button.  Clicking on the button should
@@ -2424,7 +2428,7 @@ Next we define the menu items:
 Note the symbols which the bindings are ``made for''; these appear
 inside square brackets, in the key sequence being defined.  In some
 cases, this symbol is the same as the command name; sometimes it is
-different.  These symbols are treated as ``function keys,'' but they are
+different.  These symbols are treated as ``function keys'', but they are
 not real function keys on the keyboard.  They do not affect the
 functioning of the menu itself, but they are ``echoed'' in the echo area
 when the user selects from the menu, and they appear in the output of
diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi
index 2325915d76a..423bc7b6d8a 100644
--- a/doc/lispref/lists.texi
+++ b/doc/lispref/lists.texi
@@ -34,12 +34,12 @@ object that represents an ordered pair.  That is, it has two slots,
 and each slot @dfn{holds}, or @dfn{refers to}, some Lisp object.  One
 slot is known as the @sc{car}, and the other is known as the @sc{cdr}.
 (These names are traditional; see @ref{Cons Cell Type}.)  @sc{cdr} is
-pronounced ``could-er.''
+pronounced ``could-er''.
 
   We say that ``the @sc{car} of this cons cell is'' whatever object
 its @sc{car} slot currently holds, and likewise for the @sc{cdr}.
 
-  A list is a series of cons cells ``chained together,'' so that each
+  A list is a series of cons cells ``chained together'', so that each
 cell refers to the next one.  There is one cons cell for each element
 of the list.  By convention, the @sc{car}s of the cons cells hold the
 elements of the list, and the @sc{cdr}s are used to chain the list
@@ -1632,7 +1632,7 @@ a @sc{cdr} @code{equal} to @var{value}.
 
 @code{rassoc} is like @code{assoc} except that it compares the @sc{cdr} of
 each @var{alist} association instead of the @sc{car}.  You can think of
-this as ``reverse @code{assoc},'' finding the key for a given value.
+this as ``reverse @code{assoc}'', finding the key for a given value.
 @end defun
 
 @defun assq key alist
@@ -1673,7 +1673,7 @@ a @sc{cdr} @code{eq} to @var{value}.
 
 @code{rassq} is like @code{assq} except that it compares the @sc{cdr} of
 each @var{alist} association instead of the @sc{car}.  You can think of
-this as ``reverse @code{assq},'' finding the key for a given value.
+this as ``reverse @code{assq}'', finding the key for a given value.
 
 For example:
 
diff --git a/doc/lispref/macros.texi b/doc/lispref/macros.texi
index bc4cec3307d..3984e5c03aa 100644
--- a/doc/lispref/macros.texi
+++ b/doc/lispref/macros.texi
@@ -604,7 +604,7 @@ either.
 @section Indenting Macros
 
   Within a macro definition, you can use the @code{declare} form
-(@pxref{Defining Macros}) to specify how to @key{TAB} should indent
+(@pxref{Defining Macros}) to specify how @key{TAB} should indent
 calls to the macro.  An indentation specification is written like this:
 
 @example
diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi
index c840eb6ded0..8ce7e0d4686 100644
--- a/doc/lispref/minibuf.texi
+++ b/doc/lispref/minibuf.texi
@@ -57,16 +57,17 @@ including @code{beginning-of-line}, @code{forward-word},
 @code{forward-sentence}, and @code{forward-paragraph}, stop at the
 boundary between the prompt and the actual text.
 
+@c See http://debbugs.gnu.org/11276
   The minibuffer's window is normally a single line; it grows
-automatically if the contents require more space.  You can explicitly
-@c FIXME?  Works in 23.4, not 24.0.95.  (Bug#11276)
-resize it temporarily with the window sizing commands; it reverts to
-its normal size when the minibuffer is exited.  You can resize it
-@c FIXME?  Doesn't work in any version of Emacs?
+automatically if the contents require more space.  Whilst it is
+active, you can explicitly resize it temporarily with the window
+sizing commands; it reverts to its normal size when the minibuffer is
+exited.  When the minibuffer is not active, you can resize it
 permanently by using the window sizing commands in the frame's other
-window, when the minibuffer is not active.  If the frame contains just
-a minibuffer, you can change the minibuffer's size by changing the
-frame's size.
+window, or dragging the mode line with the mouse.  (Due to details of
+the current implementation, for this to work @code{resize-mini-windows}
+must be @code{nil}.)  If the frame contains just a minibuffer, you can
+change the minibuffer's size by changing the frame's size.
 
   Use of the minibuffer reads input events, and that alters the values
 of variables such as @code{this-command} and @code{last-command}
diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index aa089aec36b..00cd43d7b71 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -283,7 +283,7 @@ buffer is put in Fundamental mode (@pxref{Major Mode Conventions}).
 * Derived Modes::           Defining a new major mode based on another major
                               mode.
 * Basic Major Modes::       Modes that other modes are often derived from.
-* Mode Hooks::              Hooks run at the end of major mode commands.
+* Mode Hooks::              Hooks run at the end of major mode functions.
 * Tabulated List Mode::     Parent mode for buffers containing tabulated data.
 * Generic Modes::           Defining a simple major mode that supports
                               comment syntax and Font Lock mode.
@@ -384,7 +384,7 @@ reserved for users.
 
 A major mode can also rebind the keys @kbd{M-n}, @kbd{M-p} and
 @kbd{M-s}.  The bindings for @kbd{M-n} and @kbd{M-p} should normally
-be some kind of ``moving forward and backward,'' but this does not
+be some kind of ``moving forward and backward'', but this does not
 necessarily mean cursor motion.
 
 It is legitimate for a major mode to rebind a standard key sequence if
@@ -938,7 +938,7 @@ 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
-define a major mode ``by hand,'' not using @code{define-derived-mode},
+define a major mode ``by hand'', not using @code{define-derived-mode},
 use the following functions to handle these conventions automatically.
 
 @defun run-mode-hooks &rest hookvars
@@ -1122,8 +1122,8 @@ documentation for the mode command.  If you do not supply it,
 The argument @var{comment-list} is a list in which each element is
 either a character, a string of one or two characters, or a cons cell.
 A character or a string is set up in the mode's syntax table as a
-``comment starter.''  If the entry is a cons cell, the @sc{car} is set
-up as a ``comment starter'' and the @sc{cdr} as a ``comment ender.''
+``comment starter''.  If the entry is a cons cell, the @sc{car} is set
+up as a ``comment starter'' and the @sc{cdr} as a ``comment ender''.
 (Use @code{nil} for the latter if you want comments to end at the end
 of the line.)  Note that the syntax table mechanism has limitations
 about what comment starters and enders are actually possible.
@@ -1648,7 +1648,7 @@ See the command \\[hungry-electric-delete]."
 @end smallexample
 
 @noindent
-This defines a minor mode named ``Hungry mode,'' a command named
+This defines a minor mode named ``Hungry mode'', a command named
 @code{hungry-mode} to toggle it, a variable named @code{hungry-mode}
 which indicates whether the mode is enabled, and a variable named
 @code{hungry-mode-map} which holds the keymap that is active when the
@@ -3374,7 +3374,7 @@ Another one is SMIE which takes an approach in the spirit
 of Lisp sexps and adapts it to non-Lisp languages.
 
 @menu
-* SMIE::                        A simple minded indentation engine
+* SMIE::                        A simple minded indentation engine.
 @end menu
 
 @node SMIE
@@ -3400,14 +3400,14 @@ languages cannot be parsed correctly using SMIE, at least not without
 resorting to some special tricks (@pxref{SMIE Tricks}).
 
 @menu
-* SMIE setup::                  SMIE setup and features
-* Operator Precedence Grammars::  A very simple parsing technique
-* SMIE Grammar::                Defining the grammar of a language
-* SMIE Lexer::                  Defining tokens
-* SMIE Tricks::                 Working around the parser's limitations
-* SMIE Indentation::            Specifying indentation rules
-* SMIE Indentation Helpers::    Helper functions for indentation rules
-* SMIE Indentation Example::    Sample indentation rules
+* SMIE setup::                  SMIE setup and features.
+* Operator Precedence Grammars::  A very simple parsing technique.
+* SMIE Grammar::                Defining the grammar of a language.
+* SMIE Lexer::                  Defining tokens.
+* SMIE Tricks::                 Working around the parser's limitations.
+* SMIE Indentation::            Specifying indentation rules.
+* SMIE Indentation Helpers::    Helper functions for indentation rules.
+* SMIE Indentation Example::    Sample indentation rules.
 @end menu
 
 @node SMIE setup
diff --git a/doc/lispref/numbers.texi b/doc/lispref/numbers.texi
index 66f491b7780..02d306b3f75 100644
--- a/doc/lispref/numbers.texi
+++ b/doc/lispref/numbers.texi
@@ -777,7 +777,7 @@ and returns that value as a floating point number.
 sequence of @dfn{bits} (digits which are either zero or one).  A bitwise
 operation acts on the individual bits of such a sequence.  For example,
 @dfn{shifting} moves the whole sequence left or right one or more places,
-reproducing the same pattern ``moved over.''
+reproducing the same pattern ``moved over''.
 
   The bitwise operations in Emacs Lisp apply only to integers.
 
diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi
index 58ceeb02b76..b49d2bc05fe 100644
--- a/doc/lispref/objects.texi
+++ b/doc/lispref/objects.texi
@@ -675,7 +675,7 @@ not distinguish between a cons cell slot ``holding'' a value versus
 
 @cindex atoms
   Because cons cells are so central to Lisp, we also have a word for
-``an object which is not a cons cell.''  These objects are called
+``an object which is not a cons cell''.  These objects are called
 @dfn{atoms}.
 
 @cindex parenthesis
@@ -1289,7 +1289,7 @@ without qualification, we mean a Lisp macro, not a keyboard macro.
   A @dfn{primitive function} is a function callable from Lisp but
 written in the C programming language.  Primitive functions are also
 called @dfn{subrs} or @dfn{built-in functions}.  (The word ``subr'' is
-derived from ``subroutine.'')  Most primitive functions evaluate all
+derived from ``subroutine''.)  Most primitive functions evaluate all
 their arguments when they are called.  A primitive function that does
 not evaluate all its arguments is called a @dfn{special form}
 (@pxref{Special Forms}).@refill
diff --git a/doc/lispref/streams.texi b/doc/lispref/streams.texi
index 7028b6e4e3f..66df1f34eda 100644
--- a/doc/lispref/streams.texi
+++ b/doc/lispref/streams.texi
@@ -114,7 +114,7 @@ When it is called with one argument (always a character), @var{function}
 should save the argument and arrange to return it on the next call.
 This is called @dfn{unreading} the character; it happens when the Lisp
 reader reads one character too many and wants to ``put it back where it
-came from.''  In this case, it makes no difference what value
+came from''.  In this case, it makes no difference what value
 @var{function} returns.
 @end itemize
 
@@ -618,7 +618,7 @@ spacing between calls.
 @defun terpri &optional stream
 @cindex newline in print
 This function outputs a newline to @var{stream}.  The name stands
-for ``terminate print.''
+for ``terminate print''.
 @end defun
 
 @defun write-char character &optional stream
diff --git a/doc/lispref/symbols.texi b/doc/lispref/symbols.texi
index ac2cea02040..1e749b8c3bb 100644
--- a/doc/lispref/symbols.texi
+++ b/doc/lispref/symbols.texi
@@ -140,7 +140,7 @@ act correctly if it is evaluated with lexical scoping enabled
   @code{defun} defines a symbol as a function, creating a lambda
 expression and storing it in the function cell of the symbol.  This
 lambda expression thus becomes the function definition of the symbol.
-(The term ``function definition,'' meaning the contents of the function
+(The term ``function definition'', meaning the contents of the function
 cell, is derived from the idea that @code{defun} gives the symbol its
 definition as a function.)  @code{defsubst} and @code{defalias} are two
 other ways of defining a function.  @xref{Functions}.
diff --git a/doc/lispref/syntax.texi b/doc/lispref/syntax.texi
index 830ceeedefd..4a860657444 100644
--- a/doc/lispref/syntax.texi
+++ b/doc/lispref/syntax.texi
@@ -56,7 +56,7 @@ Modes}, for an example of how to set up a syntax table.
 A syntax table can inherit the data for some characters from the
 standard syntax table, while specifying other characters itself.  The
 ``inherit'' syntax class means ``inherit this character's syntax from
-the standard syntax table.''  Just changing the standard syntax for a
+the standard syntax table''.  Just changing the standard syntax for a
 character affects all syntax tables that inherit from it.
 
 @defun syntax-table-p object
@@ -617,7 +617,7 @@ higher-level functions for moving over balanced expressions.
   A character's syntax controls how it changes the state of the
 parser, rather than describing the state itself.  For example, a
 string delimiter character toggles the parser state between
-``in-string'' and ``in-code,'' but the syntax of characters does not
+``in-string'' and ``in-code'', but the syntax of characters does not
 directly say whether they are inside a string.  For example (note that
 15 is the syntax code for generic string delimiters),
 
diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index a9c51fead1b..d794ddc385b 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -555,7 +555,7 @@ error; if some of the text in it is read-only, it signals a
 asking for any confirmation.  It returns @code{nil}.
 
 Normally, deleting a large amount of text from a buffer inhibits further
-auto-saving of that buffer ``because it has shrunk.''  However,
+auto-saving of that buffer ``because it has shrunk''.  However,
 @code{erase-buffer} does not do this, the idea being that the future
 text is not really related to the former text, and its size should not
 be compared with that of the former text.
@@ -806,7 +806,7 @@ that treat it as a ring.
 
   Some people think this use of the word ``kill'' is unfortunate, since
 it refers to operations that specifically @emph{do not} destroy the
-entities ``killed.''  This is in sharp contrast to ordinary life, in
+entities ``killed''.  This is in sharp contrast to ordinary life, in
 which death is permanent and ``killed'' entities do not come back to
 life.  Therefore, other metaphors have been proposed.  For example, the
 term ``cut ring'' makes sense to people who, in pre-computer days, used
@@ -845,7 +845,7 @@ the entry made by the first one.
 
   For yanking, one entry in the kill ring is designated the ``front'' of
 the ring.  Some yank commands ``rotate'' the ring by designating a
-different element as the ``front.''  But this virtual rotation doesn't
+different element as the ``front''.  But this virtual rotation doesn't
 change the list itself---the most recent entry always comes first in the
 list.
 
@@ -1093,8 +1093,8 @@ programs, when you are using a window system.  Its value should be
 @code{nil} or a function of no arguments.
 
 If the value is a function, @code{current-kill} calls it to get the
-``most recent kill.''  If the function returns a non-@code{nil} value,
-then that value is used as the ``most recent kill.''  If it returns
+``most recent kill''.  If the function returns a non-@code{nil} value,
+then that value is used as the ``most recent kill''.  If it returns
 @code{nil}, then the front of the kill ring is used.
 
 To facilitate support for window systems that support multiple
@@ -3504,7 +3504,7 @@ once for the same part of the buffer, you can use the variable
 If this variable's value is non-@code{nil}, it is a symbol which is used
 as a text property name.  A non-@code{nil} value for that text property
 means, ``the other text properties for this character have already been
-computed.''
+computed''.
 
 If all the characters in the range specified for @code{buffer-substring}
 have a non-@code{nil} value for this property, @code{buffer-substring}
@@ -3808,7 +3808,7 @@ after @var{old-pos}.)  If @var{escape-from-edge} is non-@code{nil},
 @var{new-pos} can be anywhere in the two adjacent fields.
 Additionally, if two fields are separated by another field with the
 special value @code{boundary}, then any point within this special
-field is also considered to be ``on the boundary.''
+field is also considered to be ``on the boundary''.
 
 Commands like @kbd{C-a} with no argument, that normally move backward
 to a specific kind of location and stay there once there, probably
diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi
index 4ba7dd9dfe9..0e58373119f 100644
--- a/doc/lispref/tips.texi
+++ b/doc/lispref/tips.texi
@@ -640,7 +640,7 @@ have the form (KEY . VALUE).  Here, KEY is ...
 
 @item
 Never change the case of a Lisp symbol when you mention it in a doc
-string.  If the symbol's name is @code{foo}, write ``foo,'' not
+string.  If the symbol's name is @code{foo}, write ``foo'', not
 ``Foo'' (which is a different symbol).
 
 This might appear to contradict the policy of writing function
@@ -772,9 +772,9 @@ is indicative and has a proper subject.
 
 @item
 The documentation string for a function that is a yes-or-no predicate
-should start with words such as ``Return t if,'' to indicate
-explicitly what constitutes ``truth.''  The word ``return'' avoids
-starting the sentence with lower-case ``t,'' which could be somewhat
+should start with words such as ``Return t if'', to indicate
+explicitly what constitutes ``truth''.  The word ``return'' avoids
+starting the sentence with lower-case ``t'', which could be somewhat
 distracting.
 
 @item
@@ -797,8 +797,8 @@ returned.''
 
 @item
 Avoid using the word ``cause'' (or its equivalents) unnecessarily.
-Instead of, ``Cause Emacs to display text in boldface,'' write just
-``Display text in boldface.''
+Instead of, ``Cause Emacs to display text in boldface'', write just
+``Display text in boldface''.
 
 @item
 Avoid using ``iff'' (a mathematics term meaning ``if and only if''),
@@ -821,7 +821,7 @@ to set, use @code{defcustom}.  @xref{Defining Variables}.
 
 @item
 The documentation string for a variable that is a yes-or-no flag should
-start with words such as ``Non-nil means,'' to make it clear that
+start with words such as ``Non-nil means'', to make it clear that
 all non-@code{nil} values are equivalent and indicate explicitly what
 @code{nil} and non-@code{nil} mean.
 @end itemize
diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi
index e0e629ec9d3..4e622231645 100644
--- a/doc/lispref/variables.texi
+++ b/doc/lispref/variables.texi
@@ -670,7 +670,7 @@ symbol is changed.
 
 @code{setq} does not evaluate @var{symbol}; it sets the symbol that you
 write.  We say that this argument is @dfn{automatically quoted}.  The
-@samp{q} in @code{setq} stands for ``quoted.''
+@samp{q} in @code{setq} stands for ``quoted''.
 
 The value of the @code{setq} form is the value of the last @var{form}.
 
diff --git a/doc/lispref/vol1.texi b/doc/lispref/vol1.texi
index 25ea8577467..2687cd57d5a 100644
--- a/doc/lispref/vol1.texi
+++ b/doc/lispref/vol1.texi
@@ -24,10 +24,9 @@
 @end tex
 
 @c Version of the manual and of Emacs.
-@c Please remember to update the edition number in README as well.
-@set VERSION  3.0
+@set VERSION  3.1
 @include emacsver.texi
-@set DATE July 2009
+@set DATE May 2012
 
 @dircategory Emacs
 @direntry
@@ -90,8 +89,8 @@ developing GNU and promoting software freedom.''
 @subtitle For Emacs Version @value{EMACSVER}
 @subtitle Revision @value{VERSION}, @value{DATE}
 
-@author by Bil Lewis, Dan LaLiberte, Richard Stallman
-@author and the GNU Manual Group
+@author by Bil Lewis, Dan LaLiberte, Richard Stallman,
+@author the GNU Manual Group, et al.
 @page
 @vskip 0pt plus 1filll
 @insertcopying
@@ -480,7 +479,7 @@ Functions
 * Closures::                Functions that enclose a lexical environment.
 * Obsolete Functions::      Declaring functions obsolete.
 * Inline Functions::        Defining functions that the compiler
-                              will open code.
+                              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
@@ -513,7 +512,7 @@ Common Problems Using Macros
 * Eval During Expansion::  Don't evaluate them; put them in the expansion.
 * Repeated Expansion::     Avoid depending on how many times expansion is done.
 
-Writing Customization Definitions
+Customization Settings
 
 * Common Keywords::         Common keyword arguments for all kinds of
                               customization declarations.
@@ -776,6 +775,7 @@ Defining Menus
                               various features.
 * Menu Separators::         Drawing a horizontal line through a menu.
 * Alias Menu Items::        Using command aliases in menu items.
+* Toolkit Differences::     Not all toolkits provide the same features.
 
 Major and Minor Modes
 
@@ -802,7 +802,7 @@ Major Modes
 * Derived Modes::           Defining a new major mode based on another major
                               mode.
 * Basic Major Modes::       Modes that other modes are often derived from.
-* Mode Hooks::              Hooks run at the end of major mode commands.
+* Mode Hooks::              Hooks run at the end of major mode functions.
 * Tabulated List Mode::     Parent mode for buffers containing tabulated data.
 * Generic Modes::           Defining a simple major mode that supports
                               comment syntax and Font Lock mode.
@@ -846,6 +846,21 @@ Multiline Font Lock Constructs
 * Region to Refontify::     Controlling which region gets refontified
                               after a buffer change.
 
+Automatic Indentation of code
+
+* SMIE::                    A simple minded indentation engine.
+
+Simple Minded Indentation Engine
+
+* SMIE setup::              SMIE setup and features.
+* Operator Precedence Grammars:: A very simple parsing technique.
+* SMIE Grammar::            Defining the grammar of a language.
+* SMIE Lexer::              Defining tokens.
+* SMIE Tricks::             Working around the parser's limitations.
+* SMIE Indentation::        Specifying indentation rules.
+* SMIE Indentation Helpers:: Helper functions for indentation rules.
+* SMIE Indentation Example::  Sample indentation rules.
+
 Documentation
 
 * Documentation Basics::    Where doc strings are defined and stored.
@@ -1242,8 +1257,7 @@ Processes
 * Datagrams::               UDP network connections.
 * Low-Level Network::       Lower-level but more general function
                               to create connections and servers.
-* Misc Network::            Additional relevant functions for
-                              network connections.
+* Misc Network::            Additional relevant functions for net connections.
 * Serial Ports::            Communicating with serial ports.
 * Byte Packing::            Using bindat to pack and unpack binary data.
 
@@ -1363,6 +1377,7 @@ Images
 * GIF Images::              Special features for GIF format.
 * TIFF Images::             Special features for TIFF format.
 * PostScript Images::       Special features for PostScript format.
+* ImageMagick Images::      Special features available through ImageMagick.
 * 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
@@ -1418,12 +1433,6 @@ Operating System Interface
 * Notifications::           Desktop notifications.
 * Dynamic Libraries::       On-demand loading of support libraries.
 
-Preparing Lisp code for distribution
-
-* Packaging Basics::        The basic concepts of Emacs Lisp packages.
-* Simple Packages::         How to package a single .el file.
-* Multi-file Packages::     How to package multiple files.
-
 Starting Up Emacs
 
 * Startup Summary::         Sequence of actions Emacs performs at startup.
@@ -1442,6 +1451,13 @@ Terminal Input
 * Input Modes::             Options for how input is processed.
 * Recording Input::         Saving histories of recent or all input events.
 
+Preparing Lisp code for distribution
+
+* Packaging Basics::        The basic concepts of Emacs Lisp packages.
+* Simple Packages::         How to package a single .el file.
+* Multi-file Packages::     How to package multiple files.
+* Package Archives::        Maintaining package archives.
+
 Tips and Conventions
 
 * Coding Conventions::      Conventions for clean and robust programs.
diff --git a/doc/lispref/vol2.texi b/doc/lispref/vol2.texi
index 2fd2a8d8224..c74e7c438b4 100644
--- a/doc/lispref/vol2.texi
+++ b/doc/lispref/vol2.texi
@@ -24,10 +24,9 @@
 @end tex
 
 @c Version of the manual and of Emacs.
-@c Please remember to update the edition number in README as well.
-@set VERSION  3.0
+@set VERSION  3.1
 @include emacsver.texi
-@set DATE July 2009
+@set DATE May 2012
 
 @dircategory Emacs
 @direntry
@@ -90,8 +89,8 @@ developing GNU and promoting software freedom.''
 @subtitle For Emacs Version @value{EMACSVER}
 @subtitle Revision @value{VERSION}, @value{DATE}
 
-@author by Bil Lewis, Dan LaLiberte, Richard Stallman
-@author and the GNU Manual Group
+@author by Bil Lewis, Dan LaLiberte, Richard Stallman,
+@author the GNU Manual Group, et al.
 @page
 @vskip 0pt plus 1filll
 @insertcopying
@@ -479,7 +478,7 @@ Functions
 * Closures::                Functions that enclose a lexical environment.
 * Obsolete Functions::      Declaring functions obsolete.
 * Inline Functions::        Defining functions that the compiler
-                              will open code.
+                              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
@@ -512,7 +511,7 @@ Common Problems Using Macros
 * Eval During Expansion::  Don't evaluate them; put them in the expansion.
 * Repeated Expansion::     Avoid depending on how many times expansion is done.
 
-Writing Customization Definitions
+Customization Settings
 
 * Common Keywords::         Common keyword arguments for all kinds of
                               customization declarations.
@@ -775,6 +774,7 @@ Defining Menus
                               various features.
 * Menu Separators::         Drawing a horizontal line through a menu.
 * Alias Menu Items::        Using command aliases in menu items.
+* Toolkit Differences::     Not all toolkits provide the same features.
 
 Major and Minor Modes
 
@@ -801,7 +801,7 @@ Major Modes
 * Derived Modes::           Defining a new major mode based on another major
                               mode.
 * Basic Major Modes::       Modes that other modes are often derived from.
-* Mode Hooks::              Hooks run at the end of major mode commands.
+* Mode Hooks::              Hooks run at the end of major mode functions.
 * Tabulated List Mode::     Parent mode for buffers containing tabulated data.
 * Generic Modes::           Defining a simple major mode that supports
                               comment syntax and Font Lock mode.
@@ -845,6 +845,21 @@ Multiline Font Lock Constructs
 * Region to Refontify::     Controlling which region gets refontified
                               after a buffer change.
 
+Automatic Indentation of code
+
+* SMIE::                    A simple minded indentation engine.
+
+Simple Minded Indentation Engine
+
+* SMIE setup::              SMIE setup and features.
+* Operator Precedence Grammars:: A very simple parsing technique.
+* SMIE Grammar::            Defining the grammar of a language.
+* SMIE Lexer::              Defining tokens.
+* SMIE Tricks::             Working around the parser's limitations.
+* SMIE Indentation::        Specifying indentation rules.
+* SMIE Indentation Helpers:: Helper functions for indentation rules.
+* SMIE Indentation Example::  Sample indentation rules.
+
 Documentation
 
 * Documentation Basics::    Where doc strings are defined and stored.
@@ -1362,6 +1377,7 @@ Images
 * GIF Images::              Special features for GIF format.
 * TIFF Images::             Special features for TIFF format.
 * PostScript Images::       Special features for PostScript format.
+* ImageMagick Images::      Special features available through ImageMagick.
 * 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
@@ -1417,12 +1433,6 @@ Operating System Interface
 * Notifications::           Desktop notifications.
 * Dynamic Libraries::       On-demand loading of support libraries.
 
-Preparing Lisp code for distribution
-
-* Packaging Basics::        The basic concepts of Emacs Lisp packages.
-* Simple Packages::         How to package a single .el file.
-* Multi-file Packages::     How to package multiple files.
-
 Starting Up Emacs
 
 * Startup Summary::         Sequence of actions Emacs performs at startup.
@@ -1441,6 +1451,12 @@ Terminal Input
 * Input Modes::             Options for how input is processed.
 * Recording Input::         Saving histories of recent or all input events.
 
+Preparing Lisp code for distribution
+
+* Packaging Basics::        The basic concepts of Emacs Lisp packages.
+* Simple Packages::         How to package a single .el file.
+* Multi-file Packages::     How to package multiple files.
+
 Tips and Conventions
 
 * Coding Conventions::      Conventions for clean and robust programs.
diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index a9a25d8e867..094729033b1 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -49,7 +49,7 @@ is displayed in windows.
 @section Basic Concepts of Emacs Windows
 @cindex window
 
-A @dfn{window} is a area of the screen which is used to display a
+A @dfn{window} is a area of the screen that is used to display a
 buffer (@pxref{Buffers}).  In Emacs Lisp, windows are represented by a
 special Lisp object type.
 
@@ -297,8 +297,8 @@ child of its parent.
 
 The functions @code{window-next-sibling} and
 @code{window-prev-sibling} should not be confused with the functions
-@code{next-window} and @code{previous-window} which respectively
-return the next and previous window in the cyclic ordering of windows
+@code{next-window} and @code{previous-window}, which return the next
+and previous window, respectively, in the cyclic ordering of windows
 (@pxref{Cyclic Window Ordering}).
 
   You can use the following functions to find the first live window on
@@ -376,7 +376,7 @@ line (@pxref{Mode Line Format}).
 
   Emacs provides several functions for finding the height and width of
 a window.  Except where noted, Emacs reports window heights and widths
-as integer numbers of lines and columns respectively.  On a graphical
+as integer numbers of lines and columns, respectively.  On a graphical
 display, each ``line'' and ``column'' actually corresponds to the
 height and width of a ``default'' character specified by the frame's
 default font.  Thus, if a window is displaying text with a different
@@ -619,7 +619,7 @@ window.
 
 The optional argument @var{max-height}, if non-@code{nil}, specifies
 the maximum total height that this function can give @var{window}.
-The optional argument @var{min-height}, if no-@code{nil}, specifies
+The optional argument @var{min-height}, if non-@code{nil}, specifies
 the minimum total height that it can give, which overrides the
 variable @code{window-min-height}.
 
@@ -723,7 +723,7 @@ properties of the window selected within @var{window}'s frame.
 
 The behavior of this function may be altered by the window parameters
 of @var{window}, so long as the variable
-@code{ignore-window-parameters} is non-@code{nil}.  If the value of
+@code{ignore-window-parameters} is @code{nil}.  If the value of
 the @code{split-window} window parameter is @code{t}, this function
 ignores all other window parameters.  Otherwise, if the value of the
 @code{split-window} window parameter is a function, that function is
@@ -1062,7 +1062,7 @@ combination.  @xref{Splitting Windows}.
 
 The behavior of this function may be altered by the window parameters
 of @var{window}, so long as the variable
-@code{ignore-window-parameters} is non-@code{nil}.  If the value of
+@code{ignore-window-parameters} is @code{nil}.  If the value of
 the @code{delete-window} window parameter is @code{t}, this function
 ignores all other window parameters.  Otherwise, if the value of the
 @code{delete-window} window parameter is a function, that function is
@@ -1079,7 +1079,7 @@ defaults to the selected window.  The return value is @code{nil}.
 
 The behavior of this function may be altered by the window parameters
 of @var{window}, so long as the variable
-@code{ignore-window-parameters} is non-@code{nil}.  If the value of
+@code{ignore-window-parameters} is @code{nil}.  If the value of
 the @code{delete-other-windows} window parameter is @code{t}, this
 function ignores all other window parameters.  Otherwise, if the value
 of the @code{delete-other-windows} window parameter is a function,
@@ -1119,8 +1119,8 @@ means operate on that frame.
 
 Note that this argument does not have the same meaning as in other
 functions which scan all live windows (@pxref{Cyclic Window
-Ordering}).  Specifically, the values @code{t} and @code{nil} have the
-opposite of their meanings in those other functions.
+Ordering}).  Specifically, the meanings of @code{t} and @code{nil} here
+are the opposite of what they are in those other functions.
 @end deffn
 
 @node Selecting Windows
@@ -1171,11 +1171,11 @@ the buffer list.
 This macro selects @var{window}, executes @var{forms} in sequence, then
 restores the previously selected window and current buffer.  The ordering
 of recently selected windows and the buffer list remain unchanged unless
-you deliberately change them within @var{forms}, for example, by calling
+you deliberately change them within @var{forms}; for example, by calling
 @code{select-window} with argument @var{norecord} @code{nil}.
 
-The order of recently selected windows and the buffer list are not
-changed by this macro.
+This macro does not change the order of recently selected windows or
+the buffer list.
 @end defmac
 
 @defun frame-selected-window &optional frame
@@ -1185,7 +1185,7 @@ within that frame.  @var{frame} should be a live frame; if omitted or
 @end defun
 
 @defun set-frame-selected-window frame window &optional norecord
-This function makes @code{window} the window selected within the frame
+This function makes @var{window} the window selected within the frame
 @var{frame}.  @var{frame} should be a live frame; if omitted or
 @code{nil}, it defaults to the selected frame.  @var{window} should be
 a live window; if omitted or @code{nil}, it defaults to the selected
@@ -1223,7 +1223,7 @@ the cyclic ordering of windows.  @var{window} should be a live window;
 if omitted or @code{nil}, it defaults to the selected window.
 
 The optional argument @var{minibuf} specifies whether minibuffer windows
-shall be included in the cyclic ordering.  Normally, when @var{minibuf}
+should be included in the cyclic ordering.  Normally, when @var{minibuf}
 is @code{nil}, a minibuffer window is included only if it is currently
 ``active''; this matches the behavior of @kbd{C-x o}.  (Note that a
 minibuffer window is active as long as its minibuffer is in use; see
@@ -1805,14 +1805,14 @@ desired buffer) or @code{nil} (which means the splitting failed).
 @end defopt
 
 @defun split-window-sensibly window
-This function tries to split @code{window}, and return the newly
-created window.  If @code{window} cannot be split, it returns
+This function tries to split @var{window}, and return the newly
+created window.  If @var{window} cannot be split, it returns
 @code{nil}.
 
 This function obeys the usual rules that determine when a window may
 be split (@pxref{Splitting Windows}).  It first tries to split by
 placing the new window below, subject to the restriction imposed by
-@code{split-height-threshold} (see below) in addition to any other
+@code{split-height-threshold} (see below), in addition to any other
 restrictions.  If that fails, it tries to split by placing the new
 window to the right, subject to @code{split-width-threshold} (see
 below).  If that fails, and the window is the only window on its
@@ -1944,7 +1944,7 @@ to display @var{buffer}.
 
 If @var{args} is an alist, it specifies frame parameters for the new
 frame.  If @var{args} is a list whose @sc{car} is a symbol, then
-@code{(car @var{args})} is called as a function to actually create and
+@code{(car @var{args})} is a function to actually create and
 set up the frame; it is called with @var{buffer} as first argument, and
 @code{(cdr @var{args})} as additional arguments.
 
@@ -1962,7 +1962,7 @@ This variable holds frame parameters for
 
 @defopt same-window-buffer-names
 A list of buffer names for buffers that should be displayed in the
-selected window.  If the buffer's name is in this list,
+selected window.  If a buffer's name is in this list,
 @code{display-buffer} handles the buffer by switching to it in the
 selected window.
 @end defopt
@@ -1997,8 +1997,8 @@ above.
 @section Window History
 @cindex window history
 
-Each window remembers the buffers it has displayed earlier and the order
-in which these buffers have been removed from it.  This history is used,
+Each window remembers the buffers it has previously displayed, and the order
+in which these buffers were removed from it.  This history is used,
 for example, by @code{replace-buffer-in-windows} (@pxref{Buffers and
 Windows}).  This list is automatically maintained by Emacs, but you can
 use the following functions to explicitly inspect or alter it:
@@ -2061,41 +2061,41 @@ This command displays the previous buffer in @var{window}.  The
 argument @var{window} should be a live window or @code{nil} (meaning
 the selected window).  If the optional argument @var{bury-or-kill} is
 non-@code{nil}, this means that the buffer currently shown in
-@var{window} is about to be buried or killed and consequently shall
+@var{window} is about to be buried or killed and consequently should
 not be switched to in future invocations of this command.
 
 The previous buffer is usually the buffer shown before the buffer
 currently shown in @var{window}.  However, a buffer that has been buried
-or killed or has been already shown by a recent invocation of
-@code{switch-to-prev-buffer} does not qualify as previous buffer.
+or killed, or has been already shown by a recent invocation of
+@code{switch-to-prev-buffer}, does not qualify as previous buffer.
 
 If repeated invocations of this command have already shown all buffers
 previously shown in @var{window}, further invocations will show buffers
 from the buffer list of the frame @var{window} appears on (@pxref{The
-Buffer List}) trying to skip buffers that are already shown in another
+Buffer List}), trying to skip buffers that are already shown in another
 window on that frame.
 @end deffn
 
 @deffn Command switch-to-next-buffer &optional window
-This command switches to the next buffer in @var{window} thus undoing
+This command switches to the next buffer in @var{window}, thus undoing
 the effect of the last @code{switch-to-prev-buffer} command in
 @var{window}.  The argument @var{window} must be a live window and
 defaults to the selected one.
 
-If there is no recent invocation of a @code{switch-to-prev-buffer} that
+If there is no recent invocation of @code{switch-to-prev-buffer} that
 can be undone, this function tries to show a buffer from the buffer list
 of the frame @var{window} appears on (@pxref{The Buffer List}).
 @end deffn
 
 By default @code{switch-to-prev-buffer} and @code{switch-to-next-buffer}
 can switch to a buffer that is already shown in another window on the
-same frame.  The following option can be used to override that behavior.
+same frame.  The following option can be used to override this behavior.
 
 @defopt switch-to-visible-buffer
 If this variable is non-@code{nil}, @code{switch-to-prev-buffer} and
 @code{switch-to-next-buffer} may switch to a buffer that is already
-visible on the same frame, provided the buffer was shown in the argument
-window before.  If it's @code{nil}, @code{switch-to-prev-buffer} and
+visible on the same frame, provided the buffer was shown in the relevant
+window before.  If it is @code{nil}, @code{switch-to-prev-buffer} and
 @code{switch-to-next-buffer} always try to avoid switching to a buffer
 that is already visible in another window on the same frame.
 @end defopt
@@ -2137,7 +2137,7 @@ another buffer in it and iconifies the frame.
 This function returns non-@code{nil} if @var{window} is dedicated to its
 buffer and @code{nil} otherwise.  More precisely, the return value is
 the value assigned by the last call of @code{set-window-dedicated-p} for
-@var{window} or @code{nil} if that function was never called with
+@var{window}, or @code{nil} if that function was never called with
 @var{window} as its argument.  The default for @var{window} is the
 selected window.
 @end defun
@@ -2158,20 +2158,20 @@ non-@code{nil} value.
 @node Quitting Windows
 @section Quitting Windows
 
-When you want to get rid of a window used for displaying a buffer you
+When you want to get rid of a window used for displaying a buffer, you
 can call @code{delete-window} or @code{delete-windows-on}
 (@pxref{Deleting Windows}) to remove that window from its frame.  If the
 buffer is shown on a separate frame, you might want to call
 @code{delete-frame} (@pxref{Deleting Frames}) instead.  If, on the other
 hand, a window has been reused for displaying the buffer, you might
-prefer showing the buffer previously shown in that window by calling the
+prefer showing the buffer previously shown in that window, by calling the
 function @code{switch-to-prev-buffer} (@pxref{Window History}).
 Finally, you might want to either bury (@pxref{The Buffer List}) or kill
 (@pxref{Killing Buffers}) the window's buffer.
 
    The following function uses information on how the window for
-displaying the buffer was obtained in the first place thus attempting to
-automatize the above decisions for you.
+displaying the buffer was obtained in the first place, thus attempting to
+automate the above decisions for you.
 
 @deffn Command quit-window &optional kill window
 This command quits @var{window} and buries its buffer.  The argument
@@ -2199,39 +2199,39 @@ restore the original height of @var{window}.
 The three cases described so far require that the buffer shown in
 @var{window} is still the buffer displayed by the last buffer display
 function for this window.  If another buffer has been shown in the
-meantime or the buffer previously shown no longer exists, this command
+meantime, or the buffer previously shown no longer exists, this command
 calls @code{switch-to-prev-buffer} (@pxref{Window History}) to show some
 other buffer instead.
 @end deffn
 
 The function @code{quit-window} bases its decisions on information
 stored in @var{window}'s @code{quit-restore} window parameter
-(@pxref{Window Parameters}) and resets that parameter to @code{nil}
+(@pxref{Window Parameters}), and resets that parameter to @code{nil}
 after it's done.
 
 The following option specifies how to deal with a frame containing just
-one window that shall be either quit or whose buffer shall be buried.
+one window that should be either quit, or whose buffer should be buried.
 
 @defopt frame-auto-hide-function
 The function specified by this option is called to automatically hide
-frames.  This function is called with one argument - a frame.
+frames.  This function is called with one argument---a frame.
 
 The function specified here is called by @code{bury-buffer} (@pxref{The
 Buffer List}) when the selected window is dedicated and shows the buffer
-that shall be buried.  It is also called by @code{quit-window} (see
-above) when the frame of the window that shall be quit has been
+that should be buried.  It is also called by @code{quit-window} (see
+above) when the frame of the window that should be quit has been
 specially created for displaying that window's buffer and the buffer
-shall be buried.
+should be buried.
 
 The default is to call @code{iconify-frame} (@pxref{Visibility of
-Frames}).  Alternatively, you may either specify @code{delete-frame}
+Frames}).  Alternatively, you may specify either @code{delete-frame}
 (@pxref{Deleting Frames}) to remove the frame from its display,
 @code{ignore} to leave the frame unchanged, or any other function that
 can take a frame as its sole argument.
 
 Note that the function specified by this option is called if and only if
-there's at least one other frame on the terminal of the frame it's
-supposed to handle and that frame contains only one live window.
+there is at least one other frame on the terminal of the frame it's
+supposed to handle, and that frame contains only one live window.
 @end defopt
 
 
@@ -2321,14 +2321,7 @@ command to a key.
 @cindex window top line
 This function returns the display-start position of window
 @var{window}.  If @var{window} is @code{nil}, the selected window is
-used.  For example,
-
-@example
-@group
-(window-start)
-     @result{} 7058
-@end group
-@end example
+used.
 
 When you create a window, or display a different buffer in it, the
 display-start position is set to a display-start position recently used
@@ -2340,9 +2333,6 @@ it explicitly since the previous redisplay)---to make sure point appears
 on the screen.  Nothing except redisplay automatically changes the
 window-start position; if you move point, do not expect the window-start
 position to change in response until after the next redisplay.
-
-For a realistic example of using @code{window-start}, see the
-description of @code{count-lines}.  @xref{Definition of count-lines}.
 @end defun
 
 @cindex window end position
@@ -2516,12 +2506,16 @@ commands move the paper up and down.  Thus, if you are looking at the
 middle of a buffer and repeatedly call @code{scroll-down}, you will
 eventually see the beginning of the buffer.
 
-  Some people have urged that the opposite convention be used: they
+  Unfortunately, this sometimes causes confusion, because some people
+tend to think in terms of the opposite convention: they
 imagine the window moving over text that remains in place, so that
 ``down'' commands take you to the end of the buffer.  This convention
 is consistent with fact that such a command is bound to a key named
-@key{PageDown} on modern keyboards.  We have not switched to this
-convention as that is likely to break existing Emacs Lisp code.
+@key{PageDown} on modern keyboards.
+@ignore
+We have not switched to this convention as that is likely to break
+existing Emacs Lisp code.
+@end ignore
 
   Textual scrolling functions (aside from @code{scroll-other-window})
 have unpredictable results if the current buffer is not the one
@@ -2551,13 +2545,8 @@ signals an error.  Otherwise, it returns @code{nil}.
 This function scrolls backward by @var{count} lines in the selected
 window.
 
-If @var{count} is negative, it scrolls forward instead.  If
-@var{count} is omitted or @code{nil}, the distance scrolled is
-@code{next-screen-context-lines} lines less than the height of the
-window's text area.
-
-If the selected window cannot be scrolled any further, this function
-signals an error.  Otherwise, it returns @code{nil}.
+If @var{count} is negative, it scrolls forward instead.  In other
+respects, it behaves the same way as @code{scroll-up} does.
 @end deffn
 
 @deffn Command scroll-up-command &optional count
@@ -2587,8 +2576,8 @@ already displayed, @code{scroll-other-window} displays it in some
 window.
 
 When the selected window is the minibuffer, the next window is normally
-the one at the top left corner.  You can specify a different window to
-scroll, when the minibuffer is selected, by setting the variable
+the leftmost one immediately above it.  You can specify a different
+window to scroll, when the minibuffer is selected, by setting the variable
 @code{minibuffer-scroll-window}.  This variable has no effect when any
 other window is selected.  When it is non-@code{nil} and the
 minibuffer is selected, it takes precedence over
@@ -2600,7 +2589,7 @@ window is the one at the bottom right corner.  In this case,
 @code{scroll-other-window} attempts to scroll the minibuffer.  If the
 minibuffer contains just one line, it has nowhere to scroll to, so the
 line reappears after the echo area momentarily displays the message
-@samp{Beginning of buffer}.
+@samp{End of buffer}.
 @end deffn
 
 @defvar other-window-scroll-buffer
@@ -2699,12 +2688,12 @@ If @var{count} is a non-negative number, that puts the line containing
 point @var{count} lines down from the top of the window.  If
 @var{count} is a negative number, then it counts upward from the
 bottom of the window, so that @minus{}1 stands for the last usable
-line in the window.  If @var{count} is a non-@code{nil} list, then it
-stands for the line in the middle of the window.
+line in the window.
 
-If @var{count} is @code{nil}, @code{recenter} puts the line containing
-point in the middle of the window, then clears and redisplays the entire
-selected frame.
+If @var{count} is @code{nil} (or a non-@code{nil} list),
+@code{recenter} puts the line containing point in the middle of the
+window.  If @var{count} is @code{nil}, this function may redraw the
+frame, according to the value of @code{recenter-redisplay}.
 
 When @code{recenter} is called interactively, @var{count} is the raw
 prefix argument.  Thus, typing @kbd{C-u} as the prefix sets the
@@ -2713,22 +2702,32 @@ prefix argument.  Thus, typing @kbd{C-u} as the prefix sets the
 top.
 
 With an argument of zero, @code{recenter} positions the current line at
-the top of the window.  This action is so handy that some people make a
-separate key binding to do this.  For example,
+the top of the window.  The command @code{recenter-top-bottom} offers
+a more convenient way to achieve this.
+@end deffn
 
-@example
-@group
-(defun line-to-top-of-window ()
-  "Scroll current line to top of window.
-Replaces three keystroke sequence C-u 0 C-l."
-  (interactive)
-  (recenter 0))
+@defopt recenter-redisplay
+If this variable is non-@code{nil}, calling @code{recenter} with a
+@code{nil} argument redraws the frame.  The default value is
+@code{tty}, which means only redraw the frame if it is a tty frame.
+@end defopt
 
-(global-set-key [kp-multiply] 'line-to-top-of-window)
-@end group
-@end example
+@deffn Command recenter-top-bottom &optional count
+This command, which is the default binding for @kbd{C-l}, acts like
+@code{recenter}, except if called with no argument.  In that case,
+successive calls place point according to the cycling order defined
+by the variable @code{recenter-positions}.
 @end deffn
 
+@defopt recenter-positions
+This variable controls how @code{recenter-top-bottom} behaves when
+called with no argument.  The default value is @code{(middle top
+bottom)}, which means that successive calls of
+@code{recenter-top-bottom} with no argument cycle between placing
+point at the middle, top, and bottom of the window.
+@end defopt
+
+
 @node Vertical Scrolling
 @section Vertical Fractional Scrolling
 @cindex vertical fractional scrolling
@@ -2817,8 +2816,8 @@ times the normal character width.  How many characters actually
 disappear off to the left depends on their width, and could vary from
 line to line.
 
-  Because we read from side to side in the ``inner loop,'' and from top
-to bottom in the ``outer loop,'' the effect of horizontal scrolling is
+  Because we read from side to side in the ``inner loop'', and from top
+to bottom in the ``outer loop'', the effect of horizontal scrolling is
 not like that of textual or vertical scrolling.  Textual scrolling
 involves selection of a portion of text to display, and vertical
 scrolling moves the window contents contiguously; but horizontal
@@ -3014,7 +3013,7 @@ frame.
 
 @defun coordinates-in-window-p coordinates window
 This function checks whether a window @var{window} occupies the
-frame-relative coordinates @var{coordinates}, and if so which part of
+frame-relative coordinates @var{coordinates}, and if so, which part of
 the window that is.  @var{window} should be a live window.
 @var{coordinates} should be a cons cell of the form @code{(@var{x}
 . @var{y})}, where @var{x} and @var{y} are frame-relative coordinates.
@@ -3112,14 +3111,14 @@ for the current buffer.
   You can bring back an entire frame layout by restoring a previously
 saved window configuration.  If you want to record the layout of all
 frames instead of just one, use a frame configuration instead of a
-window configuration; see @ref{Frame Configurations}.
+window configuration.  @xref{Frame Configurations}.
 
 @defun current-window-configuration &optional frame
 This function returns a new object representing @var{frame}'s current
 window configuration.  The default for @var{frame} is the selected
 frame.  The variable @code{window-persistent-parameters} specifies
-whether and which window parameters are saved by this function, see
-@ref{Window Parameters} for details.
+which window parameters (if any) are saved by this function.
+@xref{Window Parameters}.
 @end defun
 
 @defun set-window-configuration configuration
@@ -3136,9 +3135,9 @@ change and triggers execution of the @code{window-size-change-functions}
 know how to tell whether the new configuration actually differs from the
 old one.
 
-If the frame which @var{configuration} was saved from is dead, all this
+If the frame from which @var{configuration} was saved is dead, all this
 function does is restore the three variables @code{window-min-height},
-@code{window-min-width} and @code{minibuffer-scroll-window}. In this
+@code{window-min-width} and @code{minibuffer-scroll-window}.  In this
 case, the function returns @code{nil}.  Otherwise, it returns @code{t}.
 
 Here is a way of using this function to get the same effect
@@ -3221,8 +3220,8 @@ configurations.
 
   The objects returned by @code{current-window-configuration} die
 together with the Emacs process.  In order to store a window
-configuration on disk and read it back in another Emacs session, the
-functions described next can be used.  These functions are also useful
+configuration on disk and read it back in another Emacs session, you
+can use the functions described next.  These functions are also useful
 to clone the state of a frame into an arbitrary live window
 (@code{set-window-configuration} effectively clones the windows of a
 frame into the root window of that very frame only).
@@ -3235,17 +3234,17 @@ of the selected frame.
 If the optional argument @var{writable} is non-@code{nil}, this means to
 not use markers for sampling positions like @code{window-point} or
 @code{window-start}.  This argument should be non-@code{nil} when the
-state shall be written to disk and read back in another session.
+state will be written to disk and read back in another session.
 
 Together, the argument @var{writable} and the variable
 @code{window-persistent-parameters} specify which window parameters are
-saved by this function, see @ref{Window Parameters} for details.
+saved by this function.  @xref{Window Parameters}.
 @end defun
 
 The value returned by @code{window-state-get} can be used in the same
 session to make a clone of a window in another window.  It can be also
 written to disk and read back in another session.  In either case, use
-the function described next to restore the state of the window.
+the following function to restore the state of the window.
 
 @defun window-state-put state &optional window ignore
 This function puts the window state @var{state} into @var{window}.  The
@@ -3254,9 +3253,9 @@ earlier invocation of @code{window-state-get}, see above.  The optional
 argument @var{window} must specify a live window and defaults to the
 selected one.
 
-The optional argument @var{ignore} non-@code{nil} means to ignore
-minimum window sizes and fixed size restrictions.  If @var{ignore}
-equals @code{safe}, this means windows can get as small as one line
+If the optional argument @var{ignore} is non-@code{nil}, it means to ignore
+minimum window sizes and fixed-size restrictions.  If @var{ignore}
+is @code{safe}, this means windows can get as small as one line
 and/or two columns.
 @end defun
 
@@ -3276,8 +3275,8 @@ setting for @var{parameter}, this function returns @code{nil}.
 
 @defun window-parameters &optional window
 This function returns all parameters of @var{window} and their values.
-The default for @var{window} is the selected window.  The return value,
-if non-@code{nil} is an association list whose elements have the form
+The default for @var{window} is the selected window.  The return value
+is either @code{nil}, or an association list whose elements have the form
 @code{(@var{parameter} . @var{value})}.
 @end defun
 
@@ -3287,34 +3286,34 @@ This function sets @var{window}'s value of @var{parameter} to
 is the selected window.
 @end defun
 
-By default, functions saving and restoring window configurations or the
+By default, the functions that save and restore window configurations or the
 states of windows (@pxref{Window Configurations}) do not care about
-window parameters.  This means, that when you change the value of a
+window parameters.  This means that when you change the value of a
 parameter within the body of a @code{save-window-excursion}, the
-previous value is not restored upon exit of that macro.  It also means
+previous value is not restored when that macro exits.  It also means
 that when you restore via @code{window-state-put} a window state saved
 earlier by @code{window-state-get}, all cloned windows have their
-parameters reset to @code{nil}.  The following variable allows to
-override the standard behavior.
+parameters reset to @code{nil}.  The following variable allows you to
+override the standard behavior:
 
 @defvar window-persistent-parameters
 This variable is an alist specifying which parameters get saved by
-@code{current-window-configuration} and @code{window-state-get} and
+@code{current-window-configuration} and @code{window-state-get}, and
 subsequently restored by @code{set-window-configuration} and
-@code{window-state-put}, see @ref{Window Configurations}.
+@code{window-state-put}.  @xref{Window Configurations}.
 
-The @sc{car} of each entry of this alist is the symbol specifying the
+The @sc{car} of each entry of this alist is a symbol specifying the
 parameter.  The @sc{cdr} should be one of the following:
 
 @table @asis
 @item @code{nil}
-This value means the parameter is neither saved by
+This value means the parameter is saved neither by
 @code{window-state-get} nor by @code{current-window-configuration}.
 
 @item @code{t}
 This value specifies that the parameter is saved by
-@code{current-window-configuration} and, provided its @var{writable}
-argument is @code{nil}, by @code{window-state-get}.
+@code{current-window-configuration} and (provided its @var{writable}
+argument is @code{nil}) by @code{window-state-get}.
 
 @item @code{writable}
 This means that the parameter is saved unconditionally by both
@@ -3325,8 +3324,8 @@ may fail with an @code{invalid-read-syntax} error.
 @end table
 @end defvar
 
-Some functions, notably @code{delete-window},
-@code{delete-other-windows} and @code{split-window} may behave specially
+Some functions (notably @code{delete-window},
+@code{delete-other-windows} and @code{split-window}), may behave specially
 when their @var{window} argument has a parameter set.  You can override
 such special behavior by binding the following variable to a
 non-@code{nil} value:
@@ -3334,7 +3333,7 @@ non-@code{nil} value:
 @defvar ignore-window-parameters
 If this variable is non-@code{nil}, some standard functions do not
 process window parameters.  The functions currently affected by this are
-@code{split-window}, @code{delete-window}, @code{delete-other-windows}
+@code{split-window}, @code{delete-window}, @code{delete-other-windows},
 and @code{other-window}.
 
 An application can bind this variable to a non-@code{nil} value around
@@ -3368,18 +3367,19 @@ This parameter marks the window as not selectable by @code{other-window}
 (@pxref{Cyclic Window Ordering}).
 
 @item @code{clone-of}
-This parameter specifies the window this one has been cloned from and is
-installed by @code{window-state-get}, see @ref{Window Configurations}.
+This parameter specifies the window that this one has been cloned
+from.  It is installed by @code{window-state-get} (@pxref{Window
+Configurations}).
 
 @item @code{quit-restore}
-This parameter tells how to proceed with a window when the buffer it
-shows is no more needed.  It is installed by the buffer display
-functions (@pxref{Choosing Window}) and consulted by the function
+This parameter specifies what to do with a window when the buffer it
+shows is not needed any more.  It is installed by the buffer display
+functions (@pxref{Choosing Window}), and consulted by the function
 @code{quit-window} (@pxref{Quitting Windows}).
 @end table
 
-In addition, the parameters @code{window-atom} and @code{window-side}
-are reserved and should not be used by applications.
+There are additional parameters @code{window-atom} and @code{window-side};
+these are reserved and should not be used by applications.
 
 
 @node Window Hooks
@@ -3401,7 +3401,7 @@ the window also runs these functions.
 This variable is not a normal hook, because each function is called with
 two arguments: the window, and its new display-start position.
 
-These functions must be careful in using @code{window-end}
+These functions must take care when using @code{window-end}
 (@pxref{Window Start and End}); if you need an up-to-date value, you
 must use the @var{update} argument to ensure you get it.
 
@@ -3439,7 +3439,7 @@ of an existing frame.  This includes splitting or deleting windows,
 changing the sizes of windows, or displaying a different buffer in a
 window.
 
-The buffer-local part of this hook is run once per each window on the
+The buffer-local part of this hook is run once for each window on the
 affected frame, with the relevant window selected and its buffer
 current.  The global part is run once for the modified frame, with that
 frame selected.