31 files changed, 2105 insertions, 1087 deletions

diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog
index c7cbc78f910..fbdb6363b34 100644
--- a/doc/emacs/ChangeLog
+++ b/doc/emacs/ChangeLog
@@ -1,3 +1,55 @@
+2012-11-13  Chong Yidong  <cyd@gnu.org>
+
+        * building.texi (Multithreaded Debugging): gdb-stopped-hooks is
+        actually named gdb-stopped-functions.
+
+2012-11-13  Glenn Morris  <rgm@gnu.org>
+
+        * misc.texi (Single Shell): Mention async-shell-command-buffer.
+
+2012-11-10  Glenn Morris  <rgm@gnu.org>
+
+        * misc.texi (Terminal emulator): Rename `term-face' to `term'.
+
+        * emacs.texi (Acknowledgments): Add profiler author.
+        * ack.texi (Acknowledgments): Add some recent contributions.
+
+2012-11-10  Chong Yidong  <cyd@gnu.org>
+
+        * files.texi (Diff Mode): Doc fixes for
+        diff-delete-trailing-whitespace (Bug#12831).
+
+        * trouble.texi (Crashing): Copyedits.
+
+2012-11-10  Glenn Morris  <rgm@gnu.org>
+
+        * files.texi (Diff Mode): Trailing whitespace updates.
+
+2012-11-10  Chong Yidong  <cyd@gnu.org>
+
+        * misc.texi (Terminal emulator): Document Term mode faces.
+
+        * mini.texi (Basic Minibuffer): New node.  Document
+        minibuffer-electric-default-mode.
+
+        * display.texi (Visual Line Mode): Fix index entry.
+
+        * buffers.texi (Several Buffers): List Buffer Menu command anmes,
+        and index the keybindings.  Document tabulated-list-sort.
+        (Kill Buffer): Capitalize Buffer Menu.
+
+        * trouble.texi (Memory Full): Capitalize Buffer Menu.
+
+2012-11-10  Eli Zaretskii  <eliz@gnu.org>
+
+        * display.texi (Auto Scrolling): Clarify that scroll-step is
+        ignored when scroll-conservatively is set to a non-zero value.
+        (Bug#12801)
+
+2012-11-10  Chong Yidong  <cyd@gnu.org>
+
+        * dired.texi (Dired Updating): Doc fix (Bug#11744).
+
 2012-10-30  Michael Albinus  <michael.albinus@gmx.de>
 
         * trouble.texi (Known Problems): Mention command `debbugs-gnu-usertags'.
diff --git a/doc/emacs/ack.texi b/doc/emacs/ack.texi
index 79710f4992b..9fdead70f8a 100644
--- a/doc/emacs/ack.texi
+++ b/doc/emacs/ack.texi
@@ -244,8 +244,9 @@ files as ``thumbnails''.
 
 @item
 Julien Danjou wrote an implementation of ``Desktop Notifications''
-(@file{notifications.el}); and @file{color.el}, a library for general
-color manipulation.  He also made various contributions to Gnus.
+(@file{notifications.el}, and related packages for ERC and Gnus);
+and @file{color.el}, a library for general color manipulation.
+He also made various contributions to Gnus.
 
 @item
 Vivek Dasmohapatra wrote @file{htmlfontify.el}, to convert a buffer or
@@ -790,6 +791,9 @@ mode-sensitive insertion of text into new files.
 Yukihiro Matsumoto and Nobuyoshi Nakada wrote Ruby-mode.
 
 @item
+Tomohiro Matsuyama wrote the native Elisp profiler.
+
+@item
 Thomas May wrote @file{blackbox.el}, a version of the traditional
 blackbox game.
 
diff --git a/doc/emacs/buffers.texi b/doc/emacs/buffers.texi
index dfd8f792300..8c6705cc0c9 100644
--- a/doc/emacs/buffers.texi
+++ b/doc/emacs/buffers.texi
@@ -309,7 +309,7 @@ whose names begin with a space, which are used internally by Emacs.
 To kill internal buffers as well, call @code{kill-matching-buffers}
 with a prefix argument.
 
-  The buffer menu feature is also convenient for killing various
+  The Buffer Menu feature is also convenient for killing various
 buffers.  @xref{Several Buffers}.
 
 @vindex kill-buffer-hook
@@ -339,7 +339,7 @@ the Customization buffer to set the variable @code{midnight-mode} to
 
 @node Several Buffers
 @section Operating on Several Buffers
-@cindex buffer menu
+@cindex Buffer Menu
 
 @table @kbd
 @item M-x buffer-menu
@@ -348,7 +348,7 @@ Begin editing a buffer listing all Emacs buffers.
 Similar, but do it in another window.
 @end table
 
-  The @dfn{buffer menu} opened by @kbd{C-x C-b} (@pxref{List Buffers})
+  The @dfn{Buffer Menu} opened by @kbd{C-x C-b} (@pxref{List Buffers})
 does not merely list buffers.  It also allows you to perform various
 operations on buffers, through an interface similar to Dired
 (@pxref{Dired}).  You can save buffers, kill them (here called
@@ -356,106 +356,169 @@ operations on buffers, through an interface similar to Dired
 
 @findex buffer-menu
 @findex buffer-menu-other-window
-  To use the buffer menu, type @kbd{C-x C-b} and switch to the window
+  To use the Buffer Menu, type @kbd{C-x C-b} and switch to the window
 displaying the @file{*Buffer List*} buffer.  You can also type
-@kbd{M-x buffer-menu} to open the buffer menu in the selected window.
+@kbd{M-x buffer-menu} to open the Buffer Menu in the selected window.
 Alternatively, the command @kbd{M-x buffer-menu-other-window} opens
-the buffer menu in another window, and selects that window.
+the Buffer Menu in another window, and selects that window.
 
-  The buffer menu is a read-only buffer, and can be changed only
+  The Buffer Menu is a read-only buffer, and can be changed only
 through the special commands described in this section.  The usual
-cursor motion commands can be used in this buffer.  The
-following commands apply to the buffer described on the current line:
+cursor motion commands can be used in this buffer.  The following
+commands apply to the buffer described on the current line:
 
 @table @kbd
 @item d
-Request to delete (kill) the buffer, then move down.  The request
-shows as a @samp{D} on the line, before the buffer name.  Requested
-deletions take place when you type the @kbd{x} command.
+@findex Buffer-menu-delete
+@kindex d @r{(Buffer Menu)}
+Flag the buffer for deletion (killing), then move point to the next
+line (@code{Buffer-menu-delete}).  The deletion flag is indicated by
+the character @samp{D} on the line, before the buffer name.  The
+deletion occurs only when you type the @kbd{x} command (see below).
+
 @item C-d
-Like @kbd{d} but move up afterwards instead of down.
+@findex Buffer-menu-delete-backwards
+@kindex C-d @r{(Buffer Menu)}
+Like @kbd{d}, but move point up instead of down
+(@code{Buffer-menu-delete-backwards}).
+
 @item s
-Request to save the buffer.  The request shows as an @samp{S} on the
-line.  Requested saves take place when you type the @kbd{x} command.
-You may request both saving and deletion for the same buffer.
+@findex Buffer-menu-save
+@kindex s @r{(Buffer Menu)}
+Flag the buffer for saving (@code{Buffer-menu-save}).  The save flag
+is indicated by the character @samp{S} on the line, before the buffer
+name.  The saving occurs only when you type @kbd{x}.  You may request
+both saving and deletion for the same buffer.
+
 @item x
-Perform previously requested deletions and saves.
+@findex Buffer-menu-execute
+@kindex x @r{(Buffer Menu)}
+Perform all flagged deletions and saves (@code{Buffer-menu-execute}).
+
 @item u
-Remove any request made for the current line, and move down.
+@findex Buffer-menu-unmark
+@kindex u @r{(Buffer Menu)}
+Remove all flags from the current line, and move down
+(@code{Buffer-menu-unmark}).
+
 @item @key{DEL}
-Move to previous line and remove any request made for that line.
+@findex Buffer-menu-backup-unmark
+@kindex DEL @r{(Buffer Menu)}
+Move to the previous line and remove all flags on that line
+(@code{Buffer-menu-backup-unmark}).
 @end table
 
-  The @kbd{d}, @kbd{C-d}, @kbd{s} and @kbd{u} commands to add or remove
-flags also move down (or up) one line.  They accept a numeric argument
-as a repeat count.
+@noindent
+The commands for adding or removing flags, @kbd{d}, @kbd{C-d}, @kbd{s}
+and @kbd{u}, all accept a numeric argument as a repeat count.
 
-  These commands operate immediately on the buffer listed on the current
-line:
+  The following commands operate immediately on the buffer listed on
+the current line.  They also accept a numeric argument as a repeat
+count.
 
 @table @kbd
 @item ~
-Mark the buffer ``unmodified''.  The command @kbd{~} does this
-immediately when you type it.
+@findex Buffer-menu-not-modified
+@kindex ~ @r{(Buffer Menu)}
+Mark the buffer as unmodified (@code{Buffer-menu-not-modified}).
+@xref{Save Commands}.
+
 @item %
-Toggle the buffer's read-only flag.  The command @kbd{%} does
-this immediately when you type it.
+@findex Buffer-menu-toggle-read-only
+@kindex % @r{(Buffer Menu)}
+Toggle the buffer's read-only status
+(@code{Buffer-menu-toggle-read-only}).  @xref{Misc Buffer}.
+
 @item t
-Visit the buffer as a tags table.  @xref{Select Tags Table}.
+@findex Buffer-menu-visit-tags-table
+@kindex % @r{(Buffer Menu)}
+Visit the buffer as a tags table
+(@code{Buffer-menu-visit-tags-table}).  @xref{Select Tags Table}.
 @end table
 
-  There are also commands to select another buffer or buffers:
+  The following commands are used to select another buffer or buffers:
 
 @table @kbd
 @item q
-Quit the buffer menu---immediately display the most recent formerly
-visible buffer in its place.
+@findex quit-window
+@kindex q @r{(Buffer Menu)}
+Quit the Buffer Menu (@code{quit-window}).  The most recent formerly
+visible buffer is displayed in its place.
+
 @item @key{RET}
 @itemx f
-Immediately select this line's buffer in place of the @file{*Buffer
-List*} buffer.
+@findex Buffer-menu-this-window
+@kindex f @r{(Buffer Menu)}
+@kindex RET @r{(Buffer Menu)}
+Select this line's buffer, replacing the @file{*Buffer List*} buffer
+in its window (@code{Buffer-menu-this-window}).
+
 @item o
-Immediately select this line's buffer in another window as if by
-@kbd{C-x 4 b}, leaving @file{*Buffer List*} visible.
+@findex Buffer-menu-other-window
+@kindex o @r{(Buffer Menu)}
+Select this line's buffer in another window, as if by @kbd{C-x 4 b},
+leaving @file{*Buffer List*} visible
+(@code{Buffer-menu-other-window}).
+
 @item C-o
-Immediately display this line's buffer in another window, but don't
-select the window.
+@findex Buffer-menu-switch-other-window
+@kindex C-o @r{(Buffer Menu)}
+Display this line's buffer in another window, without selecting it
+(@code{Buffer-menu-switch-other-window}).
+
 @item 1
-Immediately select this line's buffer in a full-screen window.
+@findex Buffer-menu-1-window
+@kindex 1 @r{(Buffer Menu)}
+Select this line's buffer in a full-frame window
+(@code{Buffer-menu-1-window}).
+
 @item 2
-Immediately set up two windows, with this line's buffer selected in
-one, and the previously current buffer (aside from the buffer
-@file{*Buffer List*}) displayed in the other.
+@findex Buffer-menu-2-window
+@kindex 2 @r{(Buffer Menu)}
+Set up two windows on the current frame, with this line's buffer
+selected in one, and a previously current buffer (aside from
+@file{*Buffer List*}) in the other (@code{Buffer-menu-2-window}).
+
 @item b
-Bury the buffer listed on this line.
+@findex Buffer-menu-bury
+@kindex b @r{(Buffer Menu)}
+Bury this line's buffer (@code{Buffer-menu-bury}).
+
 @item m
+@findex Buffer-menu-mark
+@kindex m @r{(Buffer Menu)}
 Mark this line's buffer to be displayed in another window if you exit
-with the @kbd{v} command.  The request shows as a @samp{>} at the
-beginning of the line.  (A single buffer may not have both a delete
-request and a display request.)
+with the @kbd{v} command (@code{Buffer-menu-mark}).  The display flag
+is indicated by the character @samp{>} at the beginning of the line.
+(A single buffer may not have both deletion and display flags.)
+
 @item v
-Immediately select this line's buffer, and also display in other windows
-any buffers previously marked with the @kbd{m} command.  If you have not
-marked any buffers, this command is equivalent to @kbd{1}.
+@findex Buffer-menu-select
+@kindex v @r{(Buffer Menu)}
+Select this line's buffer, and also display in other windows any
+buffers flagged with the @kbd{m} command (@code{Buffer-menu-select}).
+If you have not flagged any buffers, this command is equivalent to
+@kbd{1}.
 @end table
 
-  There is also a command that affects the entire buffer list:
+  The following commands affect the entire buffer list:
 
 @table @kbd
+@item S
+@findex tabulated-list-sort
+@kindex S @r{(Buffer Menu)}
+Sort the Buffer Menu entries according to their values in the column
+at point.  With a numeric prefix argument @var{n}, sort according to
+the @var{n}-th column (@code{tabulated-list-sort}).
+
 @item T
-Delete, or reinsert, lines for non-file buffers.  This command toggles
-the inclusion of such buffers in the buffer list.
+@findex Buffer-menu-toggle-files-only
+@kindex T @r{(Buffer Menu)}
+Delete, or reinsert, lines for non-file buffers
+@code{Buffer-menu-toggle-files-only}).  This command toggles the
+inclusion of such buffers in the buffer list.
 @end table
 
-  What @code{buffer-menu} actually does is create and switch to a
-suitable buffer, and turn on Buffer Menu mode in it.  Everything else
-described above is implemented by the special commands provided in
-Buffer Menu mode.  One consequence of this is that you can switch from
-the @file{*Buffer List*} buffer to another Emacs buffer, and edit
-there.  You can reselect the @file{*Buffer List*} buffer later, to
-perform the operations already requested, or you can kill it, or pay
-no further attention to it.
-
   Normally, the buffer @file{*Buffer List*} is not updated
 automatically when buffers are created and killed; its contents are
 just text.  If you have created, deleted or renamed buffers, the way
@@ -633,7 +696,6 @@ C-b}.  To customize this buffer list, use the @code{bs} Custom group
 @findex msb-mode
 @cindex mode, MSB
 @cindex MSB mode
-@cindex buffer menu
 @findex mouse-buffer-menu
 @kindex C-Down-Mouse-1
   MSB global minor mode (``MSB'' stands for ``mouse select buffer'')
diff --git a/doc/emacs/building.texi b/doc/emacs/building.texi
index 3a3630138de..e0ea72902fb 100644
--- a/doc/emacs/building.texi
+++ b/doc/emacs/building.texi
@@ -1244,8 +1244,8 @@ depending on the reason which caused the stop.  Customize the variable
 @code{gdb-switch-reasons} to select the stop reasons which will cause
 a thread switch.
 
-@vindex gdb-stopped-hooks
-  The variable @code{gdb-stopped-hooks} allows you to execute your
+@vindex gdb-stopped-functions
+  The variable @code{gdb-stopped-functions} allows you to execute your
 functions whenever some thread stops.
 
   In non-stop mode, you can switch between different modes for GUD
diff --git a/doc/emacs/dired.texi b/doc/emacs/dired.texi
index c08dc02b04b..69b72b2c73a 100644
--- a/doc/emacs/dired.texi
+++ b/doc/emacs/dired.texi
@@ -1170,17 +1170,17 @@ automatically when you revisit it, by setting the variable
 
 @kindex k @r{(Dired)}
 @findex dired-do-kill-lines
-  To delete the specified @emph{file lines} from the buffer---not
-delete the files---type @kbd{k} (@code{dired-do-kill-lines}).  Like
+  To delete @emph{file lines} from the buffer---without actually
+deleting the files---type @kbd{k} (@code{dired-do-kill-lines}).  Like
 the file-operating commands, this command operates on the next @var{n}
-files, or on the marked files if any; but it does not operate on the
-current file as a last resort.
-
-  If you use @kbd{k} with a numeric prefix argument to kill the line
-for a file that is a directory, which you have inserted in the Dired
-buffer as a subdirectory, it removed that subdirectory line from the
-buffer as well.  Typing @kbd{C-u k} on the header line for a
-subdirectory also removes the subdirectory line from the Dired buffer.
+files, or on the marked files if any.  However, it does not operate on
+the current file, since otherwise mistyping @kbd{k} could be annoying.
+
+  If you use @kbd{k} to kill the line for a directory file which you
+had inserted in the Dired buffer as a subdirectory
+(@pxref{Subdirectories in Dired}), it removes the subdirectory listing
+as well.  Typing @kbd{C-u k} on the header line for a subdirectory
+also removes the subdirectory line from the Dired buffer.
 
   The @kbd{g} command brings back any individual lines that you have
 killed in this way, but not subdirectories---you must use @kbd{i} to
diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi
index 90bfcf147c5..b6ab4913f9c 100644
--- a/doc/emacs/display.texi
+++ b/doc/emacs/display.texi
@@ -221,20 +221,27 @@ visible portion of the text.
 if you set @code{scroll-conservatively} to a small number @var{n},
 then if you move point just a little off the screen (less than @var{n}
 lines), Emacs scrolls the text just far enough to bring point back on
-screen.  By default, @code{scroll-conservatively} is@tie{}0.  If you
-set @code{scroll-conservatively} to a large number (larger than 100),
-Emacs will never center point as result of scrolling, even if point
-moves far away from the text previously displayed in the window.  With
-such a large value, Emacs will always scroll text just enough for
+screen.  If doing so fails to make point visible, Emacs centers point
+in the window.  By default, @code{scroll-conservatively} is@tie{}0.
+If you set @code{scroll-conservatively} to a large number (larger than
+100), Emacs will never center point as result of scrolling, even if
+point moves far away from the text previously displayed in the window.
+With such a large value, Emacs will always scroll text just enough for
 bringing point into view, so point will end up at the top or bottom of
 the window, depending on the scroll direction.
 
 @vindex scroll-step
-  The variable @code{scroll-step} determines how many lines to scroll
-the window when point moves off the screen.  If moving by that number
-of lines fails to bring point back into view, point is centered
-instead.  The default value is zero, which causes point to always be
-centered after scrolling.
+  An alternative way of controlling how Emacs scrolls text is by
+customizing the variable @code{scroll-step}.  Its value determines how
+many lines to scroll the window when point moves off the screen.  If
+moving by that number of lines fails to bring point back into view,
+point is centered instead.  The default value is zero, which causes
+point to always be centered after scrolling.
+
+  Since both @code{scroll-conservatively} and @code{scroll-step}
+control automatic scrolling in contradicting ways, you should set only
+one of them.  If you customize both, the value of
+@code{scroll-conservatively} takes precedence.
 
 @cindex aggressive scrolling
 @vindex scroll-up-aggressively
@@ -1493,6 +1500,7 @@ attempts to wrap the line at word boundaries near the right window
 edge.  This makes the text easier to read, as wrapping does not occur
 in the middle of words.
 
+@cindex mode, Visual Line
 @cindex Visual Line mode
 @findex visual-line-mode
 @findex global-visual-line-mode
diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi
index e7e0feb9e88..005215de645 100644
--- a/doc/emacs/emacs.texi
+++ b/doc/emacs/emacs.texi
@@ -261,6 +261,7 @@ Basic Editing Commands
 
 The Minibuffer
 
+* Basic Minibuffer::      Basic usage of the minibuffer.
 * Minibuffer File::     Entering file names with the minibuffer.
 * Minibuffer Edit::     How to edit in the minibuffer.
 * Completion::          An abbreviation facility for minibuffer input.
@@ -1402,7 +1403,7 @@ Martin Lorentzon, Dave Love, Eric Ludlam, Károly L@H{o}rentey, Sascha
 Lüdecke, Greg McGary, Roland McGrath, Michael McNamara, Alan Mackenzie,
 Christopher J.@: Madsen, Neil M.@: Mager, Ken Manheimer, Bill Mann,
 Brian Marick, Simon Marshall, Bengt Martensson, Charlie Martin,
-Yukihiro Matsumoto, David Maus, Thomas May, Will Mengarini, David
+Yukihiro Matsumoto, Tomohiro Matsuyama, David Maus, Thomas May, Will Mengarini, David
 Megginson, Stefan Merten, Ben A.@: Mesander, Wayne Mesard, Brad
 Miller, Lawrence Mitchell, Richard Mlynarik, Gerd Moellmann, Stefan
 Monnier, Keith Moore, Jan Moringen, Morioka Tomohiko, Glenn Morris,
diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi
index 36cd3658e2d..8b609891caf 100644
--- a/doc/emacs/files.texi
+++ b/doc/emacs/files.texi
@@ -1341,7 +1341,7 @@ contents of the hunk.
   You can edit a Diff mode buffer like any other buffer.  (If it is
 read-only, you need to make it writable first.  @xref{Misc Buffer}.)
 Whenever you change a hunk, Diff mode attempts to automatically
-correct the line numbers in the hunk headers, to ensure that the diff
+correct the line numbers in the hunk headers, to ensure that the patch
 remains ``correct''.  To disable automatic line number correction,
 change the variable @code{diff-update-on-the-fly} to @code{nil}.
 
@@ -1470,11 +1470,22 @@ name from the patch itself.  This is useful for making log entries for
 functions that are deleted by the patch.
 @end table
 
-  By default, Diff mode highlights trailing whitespace on modified
-lines, so that they are more obvious.  This is done by enabling
-Whitespace mode in the Diff buffer (@pxref{Useless Whitespace}).  Diff
-mode buffers are set up so that Whitespace mode avoids highlighting
-trailing whitespace occurring in the diff context.
+@c Trailing whitespace is NOT shown by default.
+@c Emacs's dir-locals file enables this (for some reason).
+@cindex trailing whitespace, in patches
+@findex diff-delete-trailing-whitespace
+  Patches sometimes include trailing whitespace on modified lines, as
+an unintentional and undesired change.  There are two ways to deal
+with this problem.  Firstly, if you enable Whitespace mode in a Diff
+buffer (@pxref{Useless Whitespace}), it automatically highlights
+trailing whitespace in modified lines.  Secondly, you can use the
+command @kbd{M-x diff-delete-trailing-whitespace}, which searches for
+trailing whitespace in the lines modified by the patch, and removes
+that whitespace in both the patch and the patched source file(s).
+This command does not save the modifications that it makes, so you can
+decide whether to save the changes (the list of modified files is
+displayed in the echo area).  With a prefix argument, it tries to
+modify the original source files rather than the patched source files.
 
 @node Misc File Ops
 @section Miscellaneous File Operations
diff --git a/doc/emacs/mini.texi b/doc/emacs/mini.texi
index e5a84bda56d..ebccedacc05 100644
--- a/doc/emacs/mini.texi
+++ b/doc/emacs/mini.texi
@@ -13,24 +13,54 @@ special-purpose buffer with a small amount of screen space.  You can
 use the usual Emacs editing commands in the minibuffer to edit the
 argument text.
 
+@menu
+* Basic Minibuffer::      Basic usage of the minibuffer.
+* Minibuffer File::       Entering file names with the minibuffer.
+* Minibuffer Edit::       How to edit in the minibuffer.
+* Completion::            An abbreviation facility for minibuffer input.
+* Minibuffer History::    Reusing recent minibuffer arguments.
+* Repetition::            Re-executing commands that used the minibuffer.
+* Passwords::             Entering passwords in the echo area.
+* Yes or No Prompts::     Replying yes or no in the echo area.
+@end menu
+
+@node Basic Minibuffer
+@section Using the Minibuffer
+
 @cindex prompt
   When the minibuffer is in use, it appears in the echo area, with a
-cursor.  The minibuffer starts with a @dfn{prompt} in a distinct
-color, usually ending with a colon.  The prompt states what kind of
-input is expected, and how it will be used.
+cursor.  The minibuffer starts with a @dfn{prompt}, usually ending
+with a colon.  The prompt states what kind of input is expected, and
+how it will be used.  The prompt is highlighted using the
+@code{minibuffer-prompt} face (@pxref{Faces}).
 
   The simplest way to enter a minibuffer argument is to type the text,
-then @key{RET} to submit the argument and exit the minibuffer.  You
-can cancel the minibuffer, and the command that wants the argument, by
-typing @kbd{C-g}.
+then @key{RET} to submit the argument and exit the minibuffer.
+Alternatively, you can type @kbd{C-g} to exit the minibuffer by
+cancelling the command asking for the argument (@pxref{Quitting}).
 
 @cindex default argument
-  Sometimes, a @dfn{default argument} appears in the prompt, inside
+  Sometimes, the prompt shows a @dfn{default argument}, inside
 parentheses before the colon.  This default will be used as the
 argument if you just type @key{RET}.  For example, commands that read
 buffer names usually show a buffer name as the default; you can type
 @key{RET} to operate on that default buffer.
 
+@cindex Minibuffer Electric Default mode
+@cindex mode, Minibuffer Electric Default
+@findex minibuffer-electric-default-mode
+@vindex minibuffer-eldef-shorten-default
+  If you enable Minibuffer Electric Default mode, a global minor mode,
+Emacs hides the default argument as soon as you modify the contents of
+the minibuffer (since typing @key{RET} would no longer submit that
+default).  If you ever bring back the original minibuffer text, the
+prompt again shows the default.  Furthermore, if you change the
+variable @code{minibuffer-eldef-shorten-default} to a non-@code{nil}
+value, the default argument is displayed as @samp{[@var{default}]}
+instead of @samp{(default @var{default})}, saving some screen space.
+To enable this minor mode, type @kbd{M-x
+minibuffer-electric-default-mode}.
+
   Since the minibuffer appears in the echo area, it can conflict with
 other uses of the echo area.  If an error message or an informative
 message is emitted while the minibuffer is active, the message hides
@@ -38,16 +68,6 @@ the minibuffer for a few seconds, or until you type something; then
 the minibuffer comes back.  While the minibuffer is in use, keystrokes
 do not echo.
 
-@menu
-* Minibuffer File::       Entering file names with the minibuffer.
-* Minibuffer Edit::       How to edit in the minibuffer.
-* Completion::            An abbreviation facility for minibuffer input.
-* Minibuffer History::    Reusing recent minibuffer arguments.
-* Repetition::            Re-executing commands that used the minibuffer.
-* Passwords::             Entering passwords in the echo area.
-* Yes or No Prompts::     Replying yes or no in the echo area.
-@end menu
-
 @node Minibuffer File
 @section Minibuffers for File Names
 
diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi
index 4f0a1009e30..1836c1982e6 100644
--- a/doc/emacs/misc.texi
+++ b/doc/emacs/misc.texi
@@ -542,11 +542,19 @@ which is impossible to ignore.
 You can also type @kbd{M-&} (@code{async-shell-command}) to execute a
 shell command asynchronously; this is exactly like calling @kbd{M-!}
 with a trailing @samp{&}, except that you do not need the @samp{&}.
-The output buffer for asynchronous shell commands is named
+The default output buffer for asynchronous shell commands is named
 @samp{*Async Shell Command*}.  Emacs inserts the output into this
 buffer as it comes in, whether or not the buffer is visible in a
 window.
 
+@vindex async-shell-command-buffer
+  If you want to run more than one asynchronous shell command at the
+same time, they could end up competing for the output buffer.  The
+option @code{async-shell-command-buffer} specifies what to do about
+this; e.g., whether to rename the pre-existing output buffer, or to
+use a different buffer for the new command.  Consult the variable's
+documentation for more possibilities.
+
 @kindex M-|
 @findex shell-command-on-region
   @kbd{M-|} (@code{shell-command-on-region}) is like @kbd{M-!}, but
@@ -1186,30 +1194,39 @@ underlying shell, of course.
 @subsection Emacs Terminal Emulator
 @findex term
 
-  To run a subshell in a terminal emulator, use @kbd{M-x term}.  This
-creates (or reuses) a buffer named @file{*terminal*}, and runs a
+  To run a subshell in a text terminal emulator, use @kbd{M-x term}.
+This creates (or reuses) a buffer named @file{*terminal*}, and runs a
 subshell with input coming from your keyboard, and output going to
 that buffer.
 
+@cindex line mode @r{(terminal emulator)}
+@cindex char mode @r{(terminal emulator)}
   The terminal emulator uses Term mode, which has two input modes.  In
-line mode, Term basically acts like Shell mode (@pxref{Shell Mode}).
-
-  In char mode, each character is sent directly to the subshell, as
-``terminal input''.  Any ``echoing'' of your input is the
-responsibility of the subshell.  The sole exception is the terminal
-escape character, which by default is @kbd{C-c} (@pxref{Term Mode}).
-Any ``terminal output'' from the subshell goes into the buffer,
-advancing point.
+@dfn{line mode}, Term basically acts like Shell mode (@pxref{Shell
+Mode}).  In @dfn{char mode}, each character is sent directly to the
+subshell, as terminal input; the sole exception is the terminal escape
+character, which by default is @kbd{C-c} (@pxref{Term Mode}).  Any
+echoing of your input is the responsibility of the subshell; any
+terminal output from the subshell goes into the buffer, advancing
+point.
 
   Some programs (such as Emacs itself) need to control the appearance
-on the terminal screen in detail.  They do this by sending special
-control codes.  The exact control codes needed vary from terminal to
-terminal, but nowadays most terminals and terminal emulators
-(including @code{xterm}) understand the ANSI-standard (VT100-style)
-escape sequences.  Term mode recognizes these escape sequences, and
-handles each one appropriately, changing the buffer so that the
-appearance of the window matches what it would be on a real terminal.
-You can actually run Emacs inside an Emacs Term window.
+of the terminal screen in detail.  They do this by emitting special
+control codes.  Term mode recognizes and handles ANSI-standard
+VT100-style escape sequences, which are accepted by most modern
+terminals, including @command{xterm}.  (Hence, you can actually run
+Emacs inside an Emacs Term window.)
+
+  The @code{term} face specifies the default appearance of text
+in the terminal emulator (the default is the same appearance as the
+@code{default} face).  When terminal control codes are used to change
+the appearance of text, these are represented in the terminal emulator
+by the faces @code{term-color-black}, @code{term-color-red},
+@code{term-color-green}, @code{term-color-yellow}
+@code{term-color-blue}, @code{term-color-magenta},
+@code{term-color-cyan}, @code{term-color-white},
+@code{term-color-underline}, and @code{term-color-bold}.
+@xref{Faces}.
 
   You can also Term mode to communicate with a device connected to a
 serial port.  @xref{Serial Terminal}.
@@ -1224,6 +1241,9 @@ examining your input.  But some shells can tell Term what the current
 directory is.  This is done automatically by @code{bash} version 1.15
 and later.
 
+
+
+
 @node Term Mode
 @subsection Term Mode
 @cindex Term mode
diff --git a/doc/emacs/trouble.texi b/doc/emacs/trouble.texi
index fc99ff3d7bf..1a891a62b33 100644
--- a/doc/emacs/trouble.texi
+++ b/doc/emacs/trouble.texi
@@ -275,24 +275,25 @@ will disappear from the mode line.  That means you can safely go on
 editing in the same Emacs session.
 
   Do not use @kbd{M-x buffer-menu} to save or kill buffers when you run
-out of memory, because the buffer menu needs a fair amount of memory
+out of memory, because the Buffer Menu needs a fair amount of memory
 itself, and the reserve supply may not be enough.
 
 @node Crashing
 @subsection When Emacs Crashes
 
-  Emacs is not supposed to crash, but if it does, before it exits it
-reports a brief summary  of the crash to the standard error stream
-@code{stderr}.  If enabled, a crashed Emacs also generates a core dump
-containing voluminous data about the crash.  On many platforms you can
-enable core dumps by putting the shell command @samp{ulimit -c unlimited}
-into your shell startup script.  The crash report and core dump can be
-used when debugging the same version of Emacs on the same platform.
+@cindex crash report
+  Emacs is not supposed to crash, but if it does, it produces a
+@dfn{crash report} prior to exiting.  The crash report is printed to
+the standard error stream.  If Emacs was started from a graphical
+desktop, the standard error stream is commonly redirected to a file
+such as @file{~/.xsession-errors}, so you can look for the crash
+report there.
 
-The format of the crash report depends on the platform, and some
-platforms support backtraces.
-Here is an example, generated on x86-64 GNU/Linux with version 2.15 of
-the GNU C Library:
+  The format of the crash report depends on the platform.  On some
+platforms, such as those using the GNU C Library, the crash report
+includes a @dfn{backtrace} describing the execution state prior to
+crashing, which can be used to help debug the crash.  Here is an
+example:
 
 @example
 Fatal error 11: Segmentation fault
@@ -304,25 +305,18 @@ emacs[0x4ed504]
 /lib64/libpthread.so.0(read+0xe)[0x375220e08e]
 emacs[0x509af6]
 emacs[0x5acc26]
-emacs[0x5adbfb]
-emacs[0x56566b]
-emacs[0x59bac3]
-emacs[0x565151]
-...
+@dots{}
 @end example
 
 @noindent
-The number @samp{11} is the system signal number that corresponds to
-the problem, a segmentation fault here.  The three dots at the end
-indicate that Emacs suppressed further backtrace entries, in the
-interest of brevity.
-
-The hexadecimal program addresses can be useful in debugging sessions.
-For example, the GDB command @samp{list *0x509af6} prints the
-source-code lines corresponding to the @samp{emacs[0x509af6]} entry in
-the backtrace.  Or, if your system has @command{addr2line}, the
-following shell command outputs a backtrace with source-code line
-numbers:
+The number @samp{11} is the system signal number corresponding to the
+crash---in this case a segmentation fault.  The hexadecimal numbers
+are program addresses, which can be associated with source code lines
+using a debugging tool.  For example, the GDB command
+@samp{list *0x509af6} prints the source-code lines corresponding to
+the @samp{emacs[0x509af6]} entry.  If your system has the
+@command{addr2line} utility, the following shell command outputs a
+backtrace with source-code line numbers:
 
 @example
 sed -n 's/.*\[\(.*\)]$/\1/p' @var{backtrace} |
@@ -334,6 +328,15 @@ Here, @var{backtrace} is the name of a text file containing a copy of
 the backtrace, and @var{bindir} is the name of the directory that
 contains the Emacs executable.
 
+@cindex core dump
+  Optionally, Emacs can generate a @dfn{core dump} when it crashes.  A
+core dump is a file containing voluminous data about the state of the
+program prior to the crash, usually examined by loading it into a
+debugger such as GDB.  On many platforms, core dumps are disabled by
+default, and you must explicitly enable them by running the shell
+command @samp{ulimit -c unlimited} (e.g.@: in your shell startup
+script).
+
 @node After a Crash
 @subsection Recovery After a Crash
 
diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index da3cc91a675..6d6ddf4da9a 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,85 @@
+2012-11-13  Glenn Morris  <rgm@gnu.org>
+
+        * variables.texi (Adding Generalized Variables):
+        At least mention gv-define-expander and gv-letplace.
+
+        * debugging.texi (Error Debugging): Mention debug-on-message.
+        (Using Debugger): Mention debugger-bury-or-kill.
+
+        * control.texi (Signaling Errors):
+        * debugging.texi (Error Debugging):
+        * errors.texi (Standard Errors): Add user-error.
+
+        * variables.texi (Adding Generalized Variables):
+        Use standard formatting for common lisp note about setf functions.
+
+2012-11-10  Martin Rudalics  <rudalics@gmx.at>
+
+        * elisp.texi (Top): Add Recombining Windows to menu.
+        * windows.texi (Recombining Windows): New subsection.
+        (Splitting Windows): Rewrite text on handling of window
+        combinations and move it to new subsection.
+
+2012-11-10  Chong Yidong  <cyd@gnu.org>
+
+        * searching.texi (Replacing Match): Document \? in replace-match.
+
+        * variables.texi (Creating Buffer-Local): Document setq-local and
+        defvar-local.
+        (Setting Generalized Variables): Arrange table alphabetically.
+
+        * lists.texi (List Elements, List Variables): Clarify descriptions
+        of push and pop for generalized variables.
+
+        * edebug.texi (Specification List): setf is no longer CL-only.
+
+2012-11-10  Glenn Morris  <rgm@gnu.org>
+
+        * variables.texi (Adding Generalized Variables):
+        Update description of FIX-RETURN expansion.
+
+        * variables.texi (Setting Generalized Variables):
+        Split most of previous contents into this subsection.
+        (Adding Generalized Variables): New subsection.
+        Move note on lack of setf functions here from misc/cl.texi.
+
+        * elisp.texi: Add Generalized Variables subsections to detailed menu.
+
+2012-11-10  Chong Yidong  <cyd@gnu.org>
+
+        * frames.texi (Initial Parameters): Doc fix (Bug#12144).
+
+2012-11-08  Michael Albinus  <michael.albinus@gmx.de>
+
+        * os.texi (Notifications): Update descriptions of
+        notifications-notify, notifications-close-notification and
+        notifications-get-capabilities according to latest code changes.
+        Add notifications-get-server-information.
+
+2012-11-03  Chong Yidong  <cyd@gnu.org>
+
+        * objects.texi (General Escape Syntax): Clarify the explanation of
+        escape sequences.
+        (Non-ASCII in Strings): Clarify when a string is unibyte vs
+        multibyte.  Hex escapes do not automatically make a string
+        multibyte.
+
+2012-11-03  Martin Rudalics  <rudalics@gmx.at>
+
+        * windows.texi (Switching Buffers): Document option
+        switch-to-buffer-preserve-window-point.
+        (Display Action Functions): Document window-height and
+        window-width alist entries.
+        (Display Action Functions): Document
+        display-buffer-below-selected and
+        display-buffer-in-previous-window.
+        (Quitting Windows): Document quit-restore-window.  Rewrite
+        section.
+        (Window Configurations): In window-state-get mention that
+        argument window must be valid.
+        (Window Parameters): Document quit-restore window parameter
+        (Bug#12158).
+
 2012-10-31  Glenn Morris  <rgm@gnu.org>
 
         * control.texi (Catch and Throw): Add xref to cl.texi.
diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi
index cf393b59c49..489e5cc5b22 100644
--- a/doc/lispref/control.texi
+++ b/doc/lispref/control.texi
@@ -824,6 +824,19 @@ The function @code{signal} never returns.
 @end example
 @end defun
 
+@cindex user errors, signaling
+@defun user-error format-string &rest args
+This function behaves exactly like @code{error}, except that it uses
+the error symbol @code{user-error} rather than @code{error}.  As the
+name suggests, this is intended to report errors on the part of the
+user, rather than errors in the code itself.  For example,
+if you try to use the command @code{Info-history-back} (@kbd{l}) to
+move back beyond the start of your Info browsing history, Emacs
+signals a @code{user-error}.  Such errors do not cause entry to the
+debugger, even when @code{debug-on-error} is non-@code{nil}.
+@xref{Error Debugging}.
+@end defun
+
 @cindex CL note---no continuable errors
 @quotation
 @b{Common Lisp note:} Emacs Lisp has nothing like the Common Lisp
diff --git a/doc/lispref/debugging.texi b/doc/lispref/debugging.texi
index 2226db942d1..11532b19781 100644
--- a/doc/lispref/debugging.texi
+++ b/doc/lispref/debugging.texi
@@ -117,12 +117,12 @@ has any of those condition symbols, or if the error message matches
 any of the regular expressions, then that error does not enter the
 debugger.
 
-The normal value of this variable lists several errors that happen
-often during editing but rarely result from bugs in Lisp programs.
-However, ``rarely'' is not ``never''; if your program fails with an
-error that matches this list, you may try changing this list to debug
-the error.  The easiest way is usually to set
-@code{debug-ignored-errors} to @code{nil}.
+The normal value of this variable includes @code{user-error}, as well
+as several errors that happen often during editing but rarely result
+from bugs in Lisp programs.  However, ``rarely'' is not ``never''; if
+your program fails with an error that matches this list, you may try
+changing this list to debug the error.  The easiest way is usually to
+set @code{debug-ignored-errors} to @code{nil}.
 @end defopt
 
 @defopt eval-expression-debug-on-error
@@ -163,6 +163,14 @@ supported values correspond to the signals @code{SIGUSR1} and
 @code{inhibit-quit} is set and Emacs is not otherwise responding.
 @end defopt
 
+@cindex message, finding what causes a particular message
+@defvar debug-on-message
+If you set @code{debug-on-message} to a regular expression,
+Emacs will enter the debugger if it displays a matching message in the
+echo area.  For example, this can be useful when trying to find the
+cause of a particular message.
+@end defvar
+
   To debug an error that happens during loading of the init
 file, use the option @samp{--debug-init}.  This binds
 @code{debug-on-error} to @code{t} while loading the init file, and
@@ -314,6 +322,7 @@ is a message describing the reason that the debugger was invoked (such
 as the error message and associated data, if it was invoked due to an
 error).
 
+@vindex debugger-bury-or-kill
   The backtrace buffer is read-only and uses a special major mode,
 Debugger mode, in which letters are defined as debugger commands.  The
 usual Emacs editing commands are available; thus, you can switch windows
@@ -322,8 +331,12 @@ switch buffers, visit files, or do any other sort of editing.  However,
 the debugger is a recursive editing level (@pxref{Recursive Editing})
 and it is wise to go back to the backtrace buffer and exit the debugger
 (with the @kbd{q} command) when you are finished with it.  Exiting
-the debugger gets out of the recursive edit and kills the backtrace
-buffer.
+the debugger gets out of the recursive edit and buries the backtrace
+buffer.  (You can customize what the @kbd{q} command does with the
+backtrace buffer by setting the variable @code{debugger-bury-or-kill}.
+For example, set it to @code{kill} if you prefer to kill the buffer
+rather than bury it.  Consult the variable's documentation for more
+possibilities.)
 
   When the debugger has been entered, the @code{debug-on-error}
 variable is temporarily set according to
diff --git a/doc/lispref/edebug.texi b/doc/lispref/edebug.texi
index 0211f9e1b9c..b5edda06bad 100644
--- a/doc/lispref/edebug.texi
+++ b/doc/lispref/edebug.texi
@@ -1211,9 +1211,7 @@ A single unevaluated Lisp object, which is not instrumented.
 A single evaluated expression, which is instrumented.
 
 @item place
-@c I can't see that this index entry is useful without any explanation.
-@c @findex edebug-unwrap
-A place to store a value, as in the Common Lisp @code{setf} construct.
+A generalized variable.  @xref{Generalized Variables}.
 
 @item body
 Short for @code{&rest form}.  See @code{&rest} below.
diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index 06a2ebfcaf8..a70558bf09f 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -502,6 +502,11 @@ Buffer-Local Variables
 * Default Value::           The default value is seen in buffers
                               that don't have their own buffer-local values.
 
+Generalized Variables
+
+* Setting Generalized Variables::   The @code{setf} macro.
+* Adding Generalized Variables::    Defining new @code{setf} forms.
+
 Functions
 
 * What Is a Function::      Lisp functions vs. primitives; terminology.
@@ -996,6 +1001,8 @@ Windows
 * Resizing Windows::        Changing the sizes of windows.
 * Splitting Windows::       Splitting one window into two windows.
 * Deleting Windows::        Deleting a window gives its space to other windows.
+* Recombining Windows::     Preserving the frame layout when splitting and
+                              deleting windows.
 * Selecting Windows::       The selected window is the one that you edit in.
 * Cyclic Window Ordering::  Moving around the existing windows.
 * Buffers and Windows::     Each window displays the contents of a buffer.
diff --git a/doc/lispref/errors.texi b/doc/lispref/errors.texi
index a57f74d6c86..b92fd9ed665 100644
--- a/doc/lispref/errors.texi
+++ b/doc/lispref/errors.texi
@@ -172,6 +172,9 @@ The message is @samp{Text is read-only}.  This is a subcategory of
 @item undefined-color
 The message is @samp{Undefined color}.  @xref{Color Names}.
 
+@item user-error
+The message is the empty string.  @xref{Signaling Errors}.
+
 @item void-function
 The message is @samp{Symbol's function definition is void}.
 @xref{Function Cells}.
diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index f58d62675e5..27d55c4fdb9 100644
--- a/doc/lispref/frames.texi
+++ b/doc/lispref/frames.texi
@@ -419,16 +419,16 @@ the initial frame, specify the same parameters in
 @code{initial-frame-alist} with values that match the X resources.
 @end defopt
 
-If these parameters specify a separate @dfn{minibuffer-only frame} with
-@code{(minibuffer . nil)}, and you have not created one, Emacs creates
-one for you.
-
 @cindex minibuffer-only frame
+If these parameters include @code{(minibuffer . nil)}, that indicates
+that the initial frame should have no minibuffer.  In this case, Emacs
+creates a separate @dfn{minibuffer-only frame} as well.
+
 @defopt minibuffer-frame-alist
 This variable's value is an alist of parameter values used when
-creating an initial minibuffer-only frame.  This is the
-minibuffer-only frame that Emacs creates if @code{initial-frame-alist}
-specifies a frame with no minibuffer.
+creating an initial minibuffer-only frame (i.e.@: the minibuffer-only
+frame that Emacs creates if @code{initial-frame-alist} specifies a
+frame with no minibuffer).
 @end defopt
 
 @defopt default-frame-alist
diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi
index 458db838177..40e8d08f72c 100644
--- a/doc/lispref/lists.texi
+++ b/doc/lispref/lists.texi
@@ -234,17 +234,15 @@ This is in contrast to @code{cdr}, which signals an error if
 @end defun
 
 @defmac pop listname
-This macro is a way of examining the @sc{car} of a list,
-and taking it off the list, all at once.
-@c FIXME I don't think is a particularly good way to do it,
-@c but generalized variables have not been introduced yet.
-(In fact, this macro can act on generalized variables, not just lists.
-@xref{Generalized Variables}.)
-
-It operates on the list which is stored in the symbol @var{listname}.
-It removes this element from the list by setting @var{listname}
-to the @sc{cdr} of its old value---but it also returns the @sc{car}
-of that list, which is the element being removed.
+This macro provides a convenient way to examine the @sc{car} of a
+list, and take it off the list, all at once.  It operates on the list
+stored in @var{listname}.  It removes the first element from the list,
+saves the @sc{cdr} into @var{listname}, then returns the removed
+element.
+
+In the simplest case, @var{listname} is an unquoted symbol naming a
+list; in that case, this macro is equivalent to @w{@code{(prog1
+(car listname) (setq listname (cdr listname)))}}.
 
 @example
 x
@@ -255,7 +253,10 @@ x
      @result{} (b c)
 @end example
 
-@noindent
+More generally, @var{listname} can be a generalized variable.  In that
+case, this macro saves into @var{listname} using @code{setf}.
+@xref{Generalized Variables}.
+
 For the @code{push} macro, which adds an element to a list,
 @xref{List Variables}.
 @end defmac
@@ -683,13 +684,12 @@ Some examples:
   These functions, and one macro, provide convenient ways
 to modify a list which is stored in a variable.
 
-@defmac push newelt listname
-This macro provides an alternative way to write
-@code{(setq @var{listname} (cons @var{newelt} @var{listname}))}.
-@c FIXME I don't think is a particularly good way to do it,
-@c but generalized variables have not been introduced yet.
-(In fact, this macro can act on generalized variables, not just lists.
-@xref{Generalized Variables}.)
+@defmac push element listname
+This macro creates a new list whose @sc{car} is @var{element} and
+whose @sc{cdr} is the list specified by @var{listname}, and saves that
+list in @var{listname}.  In the simplest case, @var{listname} is an
+unquoted symbol naming a list, and this macro is equivalent
+to @w{@code{(setq @var{listname} (cons @var{element} @var{listname}))}}.
 
 @example
 (setq l '(a b))
@@ -700,7 +700,11 @@ l
      @result{} (c a b)
 @end example
 
-@noindent
+More generally, @code{listname} can be a generalized variable.  In
+that case, this macro does the equivalent of @w{@code{(setf
+@var{listname} (cons @var{element} @var{listname}))}}.
+@xref{Generalized Variables}.
+
 For the @code{pop} macro, which removes the first element from a list,
 @xref{List Elements}.
 @end defmac
diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi
index 7d40f0ff934..6933ffe492a 100644
--- a/doc/lispref/objects.texi
+++ b/doc/lispref/objects.texi
@@ -351,51 +351,48 @@ following text.)
 control characters, Emacs provides several types of escape syntax that
 you can use to specify non-@acronym{ASCII} text characters.
 
-@cindex unicode character escape
-  You can specify characters by their Unicode values.
-@code{?\u@var{nnnn}} represents a character that maps to the Unicode
-code point @samp{U+@var{nnnn}} (by convention, Unicode code points are
-given in hexadecimal).  There is a slightly different syntax for
-specifying characters with code points higher than
-@code{U+@var{ffff}}: @code{\U00@var{nnnnnn}} represents the character
-whose code point is @samp{U+@var{nnnnnn}}.  The Unicode Standard only
-defines code points up to @samp{U+@var{10ffff}}, so if you specify a
-code point higher than that, Emacs signals an error.
-
-  This peculiar and inconvenient syntax was adopted for compatibility
-with other programming languages.  Unlike some other languages, Emacs
-Lisp supports this syntax only in character literals and strings.
-
 @cindex @samp{\} in character constant
 @cindex backslash in character constants
-@cindex octal character code
-  The most general read syntax for a character represents the
-character code in either octal or hex.  To use octal, write a question
-mark followed by a backslash and the octal character code (up to three
-octal digits); thus, @samp{?\101} for the character @kbd{A},
-@samp{?\001} for the character @kbd{C-a}, and @code{?\002} for the
-character @kbd{C-b}.  Although this syntax can represent any
-@acronym{ASCII} character, it is preferred only when the precise octal
-value is more important than the @acronym{ASCII} representation.
-
-@example
-@group
-?\012 @result{} 10         ?\n @result{} 10         ?\C-j @result{} 10
-?\101 @result{} 65         ?A @result{} 65
-@end group
-@end example
-
-  To use hex, write a question mark followed by a backslash, @samp{x},
-and the hexadecimal character code.  You can use any number of hex
-digits, so you can represent any character code in this way.
-Thus, @samp{?\x41} for the character @kbd{A}, @samp{?\x1} for the
-character @kbd{C-a}, and @code{?\xe0} for the Latin-1 character
+@cindex unicode character escape
+  Firstly, you can specify characters by their Unicode values.
+@code{?\u@var{nnnn}} represents a character with Unicode code point
+@samp{U+@var{nnnn}}, where @var{nnnn} is (by convention) a hexadecimal
+number with exactly four digits.  The backslash indicates that the
+subsequent characters form an escape sequence, and the @samp{u}
+specifies a Unicode escape sequence.
+
+  There is a slightly different syntax for specifying Unicode
+characters with code points higher than @code{U+@var{ffff}}:
+@code{?\U00@var{nnnnnn}} represents the character with code point
+@samp{U+@var{nnnnnn}}, where @var{nnnnnn} is a six-digit hexadecimal
+number.  The Unicode Standard only defines code points up to
+@samp{U+@var{10ffff}}, so if you specify a code point higher than
+that, Emacs signals an error.
+
+  Secondly, you can specify characters by their hexadecimal character
+codes.  A hexadecimal escape sequence consists of a backslash,
+@samp{x}, and the hexadecimal character code.  Thus, @samp{?\x41} is
+the character @kbd{A}, @samp{?\x1} is the character @kbd{C-a}, and
+@code{?\xe0} is the character
 @iftex
 @samp{@`a}.
 @end iftex
 @ifnottex
 @samp{a} with grave accent.
 @end ifnottex
+You can use any number of hex digits, so you can represent any
+character code in this way.
+
+@cindex octal character code
+  Thirdly, you can specify characters by their character code in
+octal.  An octal escape sequence consists of a backslash followed by
+up to three octal digits; thus, @samp{?\101} for the character
+@kbd{A}, @samp{?\001} for the character @kbd{C-a}, and @code{?\002}
+for the character @kbd{C-b}.  Only characters up to octal code 777 can
+be specified this way.
+
+  These escape sequences may also be used in strings.  @xref{Non-ASCII
+in Strings}.
 
 @node Ctl-Char Syntax
 @subsubsection Control-Character Syntax
@@ -1026,40 +1023,53 @@ but the newline is ignored if escaped."
 @node Non-ASCII in Strings
 @subsubsection Non-@acronym{ASCII} Characters in Strings
 
-  You can include a non-@acronym{ASCII} international character in a
-string constant by writing it literally.  There are two text
-representations for non-@acronym{ASCII} characters in Emacs strings
-(and in buffers): unibyte and multibyte (@pxref{Text
-Representations}).  If the string constant is read from a multibyte
-source, such as a multibyte buffer or string, or a file that would be
-visited as multibyte, then Emacs reads the non-@acronym{ASCII}
-character as a multibyte character and automatically makes the string
-a multibyte string.  If the string constant is read from a unibyte
-source, then Emacs reads the non-@acronym{ASCII} character as unibyte,
-and makes the string unibyte.
-
-  Instead of writing a non-@acronym{ASCII} character literally into a
-multibyte string, you can write it as its character code using a hex
-escape, @samp{\x@var{nnnnnnn}}, with as many digits as necessary.
-(Multibyte non-@acronym{ASCII} character codes are all greater than
-256.)  You can also specify a character in a multibyte string using
-the @samp{\u} or @samp{\U} Unicode escape syntax (@pxref{General
-Escape Syntax}).  In either case, any character which is not a valid
-hex digit terminates the construct.  If the next character in the
-string could be interpreted as a hex digit, write @w{@samp{\ }}
-(backslash and space) to terminate the hex escape---for example,
+  There are two text representations for non-@acronym{ASCII}
+characters in Emacs strings: multibyte and unibyte (@pxref{Text
+Representations}).  Roughly speaking, unibyte strings store raw bytes,
+while multibyte strings store human-readable text.  Each character in
+a unibyte string is a byte, i.e.@: its value is between 0 and 255.  By
+contrast, each character in a multibyte string may have a value
+between 0 to 4194303 (@pxref{Character Type}).  In both cases,
+characters above 127 are non-@acronym{ASCII}.
+
+  You can include a non-@acronym{ASCII} character in a string constant
+by writing it literally.  If the string constant is read from a
+multibyte source, such as a multibyte buffer or string, or a file that
+would be visited as multibyte, then Emacs reads each
+non-@acronym{ASCII} character as a multibyte character and
+automatically makes the string a multibyte string.  If the string
+constant is read from a unibyte source, then Emacs reads the
+non-@acronym{ASCII} character as unibyte, and makes the string
+unibyte.
+
+  Instead of writing a character literally into a multibyte string,
+you can write it as its character code using an escape sequence.
+@xref{General Escape Syntax}, for details about escape sequences.
+
+  If you use any Unicode-style escape sequence @samp{\uNNNN} or
+@samp{\U00NNNNNN} in a string constant (even for an @acronym{ASCII}
+character), Emacs automatically assumes that it is multibyte.
+
+  You can also use hexadecimal escape sequences (@samp{\x@var{n}}) and
+octal escape sequences (@samp{\@var{n}}) in string constants.
+@strong{But beware:} If a string constant contains hexadecimal or
+octal escape sequences, and these escape sequences all specify unibyte
+characters (i.e.@: less than 256), and there are no other literal
+non-@acronym{ASCII} characters or Unicode-style escape sequences in
+the string, then Emacs automatically assumes that it is a unibyte
+string.  That is to say, it assumes that all non-@acronym{ASCII}
+characters occurring in the string are 8-bit raw bytes.
+
+  In hexadecimal and octal escape sequences, the escaped character
+code may contain a variable number of digits, so the first subsequent
+character which is not a valid hexadecimal or octal digit terminates
+the escape sequence.  If the next character in a string could be
+interpreted as a hexadecimal or octal digit, write @w{@samp{\ }}
+(backslash and space) to terminate the escape sequence.  For example,
 @w{@samp{\xe0\ }} represents one character, @samp{a} with grave
 accent.  @w{@samp{\ }} in a string constant is just like
 backslash-newline; it does not contribute any character to the string,
-but it does terminate the preceding hex escape.  Using any hex escape
-in a string (even for an @acronym{ASCII} character) automatically
-forces the string to be multibyte.
-
-  You can represent a unibyte non-@acronym{ASCII} character with its
-character code, which must be in the range from 128 (0200 octal) to
-255 (0377 octal).  If you write all such character codes in octal and
-the string contains no other characters forcing it to be multibyte,
-this produces a unibyte string.
+but it does terminate any preceding hex escape.
 
 @node Nonprinting Characters
 @subsubsection Nonprinting Characters in Strings
diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index 6c5f6e85683..2f06e207fc4 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -2276,13 +2276,19 @@ These arguments should consist of alternating keyword and value pairs.
 The supported keywords and values are as follows:
 
 @table @code
+@item :bus @var{bus}
+The D-Bus bus.  This argument is needed only if a bus other than
+@code{:session} shall be used.
+
 @item :title @var{title}
 The notification title.
 
 @item :body @var{text}
 The notification body text.  Depending on the implementation of the
 notification server, the text could contain HTML markups, like
-@samp{"<b>bold text</b>"}, hyperlinks, or images.
+@samp{"<b>bold text</b>"}, hyperlinks, or images.  Special HTML
+characters must be encoded, as @samp{"Contact
+&lt;postmaster@@localhost&gt;!"}.
 
 @item :app-name @var{name}
 The name of the application sending the notification.  The default is
@@ -2317,7 +2323,10 @@ When this keyword is given, the @var{title} string of the actions is
 interpreted as icon name.
 
 @item :category @var{category}
-The type of notification this is, a string.
+The type of notification this is, a string.  See the
+@uref{http://developer.gnome.org/notification-spec/#categories,
+Desktop Notifications Specification} for a list of standard
+categories.
 
 @item :desktop-entry @var{filename}
 This specifies the name of the desktop filename representing the
@@ -2420,13 +2429,17 @@ A message window opens on the desktop.  Press "I agree"
 @end example
 @end defun
 
-@defun notifications-close-notification id
+@defun notifications-close-notification id &optional bus
 This function closes a notification with identifier @var{id}.
+@var{bus} can be a string denoting a D-Bus connection, the default is
+@code{:session}.
 @end defun
 
-@defun notifications-get-capabilities
-Returns the capabilities of the notification server, a list of strings.
-The following capabilities can be expected:
+@defun notifications-get-capabilities &optional bus
+Returns the capabilities of the notification server, a list of
+symbols.  @var{bus} can be a string denoting a D-Bus connection, the
+default is @code{:session}.  The following capabilities can be
+expected:
 
 @table @code
 @item :actions
@@ -2463,6 +2476,30 @@ Further vendor-specific caps start with @code{:x-vendor}, like
 @code{:x-gnome-foo-cap}.
 @end defun
 
+@defun notifications-get-server-information &optional bus
+Return information on the notification server, a list of strings.
+@var{bus} can be a string denoting a D-Bus connection, the default is
+@code{:session}.  The returned list is @code{(@var{name} @var{vendor}
+@var{version} @var{spec-version})}.
+
+@table @var
+@item name
+The product name of the server.
+
+@item vendor
+The vendor name.  For example, @samp{"KDE"}, @samp{"GNOME"}.
+
+@item version
+The server's version number.
+
+@item spec-version
+The specification version the server is compliant with.
+@end table
+
+If @var{SPEC_VERSION} is @code{nil}, the server supports a
+specification prior to @samp{"1.0"}.
+@end defun
+
 
 @node Dynamic Libraries
 @section Dynamically Loaded Libraries
diff --git a/doc/lispref/searching.texi b/doc/lispref/searching.texi
index 56c96363e81..f165381a0f8 100644
--- a/doc/lispref/searching.texi
+++ b/doc/lispref/searching.texi
@@ -1310,22 +1310,31 @@ part of one of the following sequences:
 @table @asis
 @item @samp{\&}
 @cindex @samp{&} in replacement
-@samp{\&} stands for the entire text being replaced.
+This stands for the entire text being replaced.
 
-@item @samp{\@var{n}}
+@item @samp{\@var{n}}, where @var{n} is a digit
 @cindex @samp{\@var{n}} in replacement
-@samp{\@var{n}}, where @var{n} is a digit, stands for the text that
-matched the @var{n}th subexpression in the original regexp.
-Subexpressions are those expressions grouped inside @samp{\(@dots{}\)}.
-If the @var{n}th subexpression never matched, an empty string is substituted.
+This stands for the text that matched the @var{n}th subexpression in
+the original regexp.  Subexpressions are those expressions grouped
+inside @samp{\(@dots{}\)}.  If the @var{n}th subexpression never
+matched, an empty string is substituted.
 
 @item @samp{\\}
 @cindex @samp{\} in replacement
-@samp{\\} stands for a single @samp{\} in the replacement text.
+This stands for a single @samp{\} in the replacement text.
+
+@item @samp{\?}
+This stands for itself (for compatibility with @code{replace-regexp}
+and related commands; @pxref{Regexp Replacement,,, emacs, The GNU
+Emacs Manual}).
 @end table
 
-These substitutions occur after case conversion, if any,
-so the strings they substitute are never case-converted.
+@noindent
+Any other character following @samp{\} signals an error.
+
+The substitutions performed by @samp{\&} and @samp{\@var{n}} occur
+after case conversion, if any.  Therefore, the strings they substitute
+are never case-converted.
 
 If @var{subexp} is non-@code{nil}, that says to replace just
 subexpression number @var{subexp} of the regexp that was matched, not
diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi
index 88b7909126e..dfde3c45c04 100644
--- a/doc/lispref/variables.texi
+++ b/doc/lispref/variables.texi
@@ -1262,6 +1262,13 @@ needed if you use the @var{local} argument to @code{add-hook} or
 @code{remove-hook}.
 @end deffn
 
+@defmac setq-local variable value
+This macro creates a buffer-local binding in the current buffer for
+@var{variable}, and gives it the buffer-local value @var{value}.  It
+is equivalent to calling @code{make-local-variable} followed by
+@code{setq}.  @var{variable} should be an unquoted symbol.
+@end defmac
+
 @deffn Command make-variable-buffer-local variable
 This function marks @var{variable} (a symbol) automatically
 buffer-local, so that any subsequent attempt to set it will make it
@@ -1297,6 +1304,14 @@ on having separate values in separate buffers, then using
 @code{make-variable-buffer-local} can be the best solution.
 @end deffn
 
+@defmac defvar-local variable value &optional docstring
+This macro defines @var{variable} as a variable with initial value
+@var{value} and @var{docstring}, and marks it as automatically
+buffer-local.  It is equivalent to calling @code{defvar} followed by
+@code{make-variable-buffer-local}.  @var{variable} should be an
+unquoted symbol.
+@end defmac
+
 @defun local-variable-p variable &optional buffer
 This returns @code{t} if @var{variable} is buffer-local in buffer
 @var{buffer} (which defaults to the current buffer); otherwise,
@@ -1948,7 +1963,6 @@ Attempting to assign them any other value will result in an error:
 @error{} Wrong type argument: integerp, 1000.0
 @end example
 
-@c FIXME?  Not sure this is the right place for this section.
 @node Generalized Variables
 @section Generalized Variables
 
@@ -1958,13 +1972,20 @@ a regular Lisp variable.  But the @sc{car}s and @sc{cdr}s of lists, elements
 of arrays, properties of symbols, and many other locations are also
 places where Lisp values are stored.
 
-@c FIXME?  Not sure this is a useful analogy...
 Generalized variables are analogous to ``lvalues'' in the C
 language, where @samp{x = a[i]} gets an element from an array
 and @samp{a[i] = x} stores an element using the same notation.
 Just as certain forms like @code{a[i]} can be lvalues in C, there
 is a set of forms that can be generalized variables in Lisp.
 
+@menu
+* Setting Generalized Variables::   The @code{setf} macro.
+* Adding Generalized Variables::    Defining new @code{setf} forms.
+@end menu
+
+@node Setting Generalized Variables
+@subsection The @code{setf} Macro
+
 The @code{setf} macro is the most basic way to operate on generalized
 variables.  The @code{setf} form is like @code{setq}, except that it
 accepts arbitrary place forms on the left side rather than just
@@ -1998,14 +2019,16 @@ so there is no performance penalty for using it in compiled code.
 A call to any of the following standard Lisp functions:
 
 @smallexample
-car            cdr            nth            nthcdr
-caar           cadr           cdar           cddr
-aref           elt            get            gethash
-symbol-function        symbol-value          symbol-plist
+aref      cddr      symbol-function
+car       elt       symbol-plist
+caar      get       symbol-value
+cadr      gethash
+cdr       nth
+cdar      nthcdr  
 @end smallexample
 
 @item
-The following Emacs-specific functions are also @code{setf}-able:
+A call to any of the following Emacs-specific functions:
 
 @smallexample
 default-value                 process-get
@@ -2022,8 +2045,8 @@ process-filter
 @end itemize
 
 @noindent
-Using any forms other than these in the @var{place} argument to
-@code{setf} will signal an error.
+@code{setf} signals an error if you pass a @var{place} form that it
+does not know how to handle.
 
 @c And for cl-lib's cl-getf.
 Note that for @code{nthcdr}, the list argument of the function must
@@ -2049,3 +2072,85 @@ place can be used to insert or delete at any position in a list.
 The @file{cl-lib} library defines various extensions for generalized
 variables, including additional @code{setf} places.
 @xref{Generalized Variables,,, cl, Common Lisp Extensions}.
+
+
+@node Adding Generalized Variables
+@subsection Defining new @code{setf} forms
+
+This section describes how to define new forms that @code{setf} can
+operate on.
+
+@defmac gv-define-simple-setter name setter &optional fix-return
+This macro enables you to easily define @code{setf} methods for simple
+cases.  @var{name} is the name of a function, macro, or special form.
+You can use this macro whenever @var{name} has a directly
+corresponding @var{setter} function that updates it, e.g.,
+@code{(gv-define-simple-setter car setcar)}.
+
+This macro translates a call of the form
+
+@example
+(setf (@var{name} @var{args}@dots{}) @var{value})
+@end example
+
+into
+@example
+(@var{setter} @var{args}@dots{} @var{value})
+@end example
+
+@noindent
+Such a @code{setf} call is documented to return @var{value}.  This is
+no problem with, e.g., @code{car} and @code{setcar}, because
+@code{setcar} returns the value that it set.  If your @var{setter}
+function does not return @var{value}, use a non-@code{nil} value for
+the @var{fix-return} argument of @code{gv-define-simple-setter}.  This
+expands into something equivalent to
+@example
+(let ((temp @var{value}))
+  (@var{setter} @var{args}@dots{} temp)
+  temp)
+@end example
+so ensuring that it returns the correct result.
+@end defmac
+
+
+@defmac gv-define-setter name arglist &rest body
+This macro allows for more complex @code{setf} expansions than the
+previous form.  You may need to use this form, for example, if there
+is no simple setter function to call, or if there is one but it
+requires different arguments to the place form.
+
+This macro expands the form
+@code{(setf (@var{name} @var{args}@dots{}) @var{value})} by
+first binding the @code{setf} argument forms
+@code{(@var{value} @var{args}@dots{})} according to @var{arglist},
+and then executing @var{body}.  @var{body} should return a Lisp
+form that does the assignment, and finally returns the value that was
+set.  An example of using this macro is:
+
+@example
+(gv-define-setter caar (val x) `(setcar (car ,x) ,val))
+@end example
+@end defmac
+
+@findex gv-define-expander
+@findex gv-letplace
+@c FIXME?  Not sure what or how much to say about these.
+@c See cl.texi for an example of using gv-letplace.
+For more control over the expansion, see the macro @code{gv-define-expander}.
+The macro @code{gv-letplace} can be useful in defining macros that
+perform similarly to @code{setf}; for example, the @code{incf} macro
+of Common Lisp.  Consult the source file @file{gv.el} for more details.
+
+@cindex CL note---no @code{setf} functions
+@quotation
+@b{Common Lisp note:} Common Lisp defines another way to specify the
+@code{setf} behavior of a function, namely ``@code{setf} functions'',
+whose names are lists @code{(setf @var{name})} rather than symbols.
+For example, @code{(defun (setf foo) @dots{})} defines the function
+that is used when @code{setf} is applied to @code{foo}.  Emacs does
+not support this.  It is a compile-time error to use @code{setf} on a
+form that has not already had an appropriate expansion defined.  In
+Common Lisp, this is not an error since the function @code{(setf
+@var{func})} might be defined later.
+@end quotation
diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index d0e149eb165..bb02b1d54fd 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -16,8 +16,10 @@ is displayed in windows.
 * Windows and Frames::      Relating windows to the frame they appear on.
 * Window Sizes::            Accessing a window's size.
 * Resizing Windows::        Changing the sizes of windows.
-* Splitting Windows::       Splitting one window into two windows.
-* Deleting Windows::        Deleting a window gives its space to other windows.
+* Splitting Windows::       Creating a new window.
+* Deleting Windows::        Removing a window from its frame.
+* Recombining Windows::     Preserving the frame layout when splitting and
+                              deleting windows.
 * Selecting Windows::       The selected window is the one that you edit in.
 * Cyclic Window Ordering::  Moving around the existing windows.
 * Buffers and Windows::     Each window displays the contents of a buffer.
@@ -587,7 +589,7 @@ function @code{window-resizable} above.
 The choice of which window edges this function alters depends on the
 values of the option @code{window-combination-resize} and the
 combination limits of the involved windows; in some cases, it may alter
-both edges.  @xref{Splitting Windows}.  To resize by moving only the
+both edges.  @xref{Recombining Windows}.  To resize by moving only the
 bottom or right edge of a window, use the function
 @code{adjust-window-trailing-edge}, below.
 @end defun
@@ -795,26 +797,169 @@ A new live window @var{W2} is created, to the left of the internal
 window @var{W3}.  A new internal window @var{W1} is created, becoming
 the new root window.
 
-@defopt window-combination-resize
-If this variable is @code{nil}, @code{split-window} can only split a
-window (denoted by @var{window}) if @var{window}'s screen area is large
-enough to accommodate both itself and the new window.
+   For interactive use, Emacs provides two commands which always split
+the selected window.  These call @code{split-window} internally.
 
-If this variable is @code{t}, @code{split-window} tries to resize all
-windows that are part of the same combination as @var{window}, in order
-to accommodate the new window.  In particular, this may allow
-@code{split-window} to succeed even if @var{window} is a fixed-size
-window or too small to ordinarily split.  Furthermore, subsequently
-resizing or deleting @var{window} may resize all other windows in its
-combination.
+@deffn Command split-window-right &optional size
+This function splits the selected window into two side-by-side
+windows, putting the selected window on the left.  If @var{size} is
+positive, the left window gets @var{size} columns; if @var{size} is
+negative, the right window gets @minus{}@var{size} columns.
+@end deffn
 
-The default is @code{nil}.  Other values are reserved for future use.
-The value of this variable is ignored when
-@code{window-combination-limit} is non-@code{nil} (see below).
+@deffn Command split-window-below &optional size
+This function splits the selected window into two windows, one above
+the other, leaving the upper window selected.  If @var{size} is
+positive, the upper window gets @var{size} lines; if @var{size} is
+negative, the lower window gets @minus{}@var{size} lines.
+@end deffn
+
+@defopt split-window-keep-point
+If the value of this variable is non-@code{nil} (the default),
+@code{split-window-below} behaves as described above.
+
+If it is @code{nil}, @code{split-window-below} adjusts point in each
+of the two windows to minimize redisplay.  (This is useful on slow
+terminals.)  It selects whichever window contains the screen line that
+point was previously on.  Note that this only affects
+@code{split-window-below}, not the lower-level @code{split-window}
+function.
 @end defopt
 
-  To illustrate the effect of @code{window-combination-resize},
-consider the following window configuration:
+@node Deleting Windows
+@section Deleting Windows
+@cindex deleting windows
+
+  @dfn{Deleting} a window removes it from the frame's window tree.  If
+the window is a live window, it disappears from the screen.  If the
+window is an internal window, its child windows are deleted too.
+
+  Even after a window is deleted, it continues to exist as a Lisp
+object, until there are no more references to it.  Window deletion can
+be reversed, by restoring a saved window configuration (@pxref{Window
+Configurations}).
+
+@deffn Command delete-window &optional window
+This function removes @var{window} from display and returns
+@code{nil}.  If @var{window} is omitted or @code{nil}, it defaults to
+the selected window.  If deleting the window would leave no more
+windows in the window tree (e.g. if it is the only live window in the
+frame), an error is signaled.
+
+By default, the space taken up by @var{window} is given to one of its
+adjacent sibling windows, if any.  However, if the variable
+@code{window-combination-resize} is non-@code{nil}, the space is
+proportionally distributed among any remaining windows in the window
+combination.  @xref{Recombining 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 @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
+called with the argument @var{window}, in lieu of the usual action of
+@code{delete-window}.  Otherwise, this function obeys the
+@code{window-atom} or @code{window-side} window parameter, if any.
+@xref{Window Parameters}.
+@end deffn
+
+@deffn Command delete-other-windows &optional window
+This function makes @var{window} fill its frame, by deleting other
+windows as necessary.  If @var{window} is omitted or @code{nil}, it
+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 @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,
+that function is called with the argument @var{window}, in lieu of the
+usual action of @code{delete-other-windows}.  Otherwise, this function
+obeys the @code{window-atom} or @code{window-side} window parameter,
+if any.  @xref{Window Parameters}.
+@end deffn
+
+@deffn Command delete-windows-on &optional buffer-or-name frame
+This function deletes all windows showing @var{buffer-or-name}, by
+calling @code{delete-window} on those windows.  @var{buffer-or-name}
+should be a buffer, or the name of a buffer; if omitted or @code{nil},
+it defaults to the current buffer.  If there are no windows showing
+the specified buffer, this function does nothing.  If the specified
+buffer is a minibuffer, an error is signaled.
+
+If there is a dedicated window showing the buffer, and that window is
+the only one on its frame, this function also deletes that frame if it
+is not the only frame on the terminal.
+
+The optional argument @var{frame} specifies which frames to operate
+on:
+
+@itemize @bullet
+@item @code{nil}
+means operate on all frames.
+@item @code{t}
+means operate on the selected frame.
+@item @code{visible}
+means operate on all visible frames.
+@item @code{0}
+means operate on all visible or iconified frames.
+@item A frame
+means operate on that frame.
+@end itemize
+
+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 meanings of @code{t} and @code{nil} here
+are the opposite of what they are in those other functions.
+@end deffn
+
+
+@node Recombining Windows
+@section Recombining Windows
+
+When deleting the last sibling of a window @code{W}, its parent window
+is deleted too, with @code{W} replacing it in the window tree.  This
+means that @code{W} must be recombined with its parent's siblings to
+form a new window combination (@pxref{Windows and Frames}).  In some
+occasions, deleting a live window may even entail the deletion of two
+internal windows.
+
+@smallexample
+@group
+     ______________________________________
+    | ______  ____________________________ |
+    ||      || __________________________ ||
+    ||      ||| ___________  ___________ |||
+    ||      ||||           ||           ||||
+    ||      ||||____W6_____||_____W7____||||
+    ||      |||____________W4____________|||
+    ||      || __________________________ ||
+    ||      |||                          |||
+    ||      |||                          |||
+    ||      |||____________W5____________|||
+    ||__W2__||_____________W3_____________ |
+    |__________________W1__________________|
+
+@end group
+@end smallexample
+
+@noindent
+Deleting @code{W5} in this configuration normally causes the deletion of
+@code{W3} and @code{W4}.  The remaining live windows @code{W2},
+@code{W6} and @code{W7} are recombined to form a new horizontal
+combination with parent @code{W1}.
+
+   Sometimes, however, it makes sense to not delete a parent window like
+@code{W4}.  In particular, a parent window should not be removed when it
+was used to preserve a combination embedded in a combination of the same
+type.  Such embeddings make sense to assure that when you split a window
+and subsequently delete the new window, Emacs reestablishes the layout
+of the associated frame as it existed before the splitting.
+
+   Consider a scenario starting with two live windows @code{W2} and
+@code{W3} and their parent @code{W1}.
 
 @smallexample
 @group
@@ -824,10 +969,10 @@ consider the following window configuration:
     ||                                    ||
     ||                                    ||
     ||                                    ||
-    ||_________________W2_________________||
-    | ____________________________________ |
     ||                                    ||
     ||                                    ||
+    ||_________________W2_________________||
+    | ____________________________________ |
     ||                                    ||
     ||                                    ||
     ||_________________W3_________________||
@@ -837,8 +982,7 @@ consider the following window configuration:
 @end smallexample
 
 @noindent
-If @code{window-combination-resize} is @code{nil}, splitting window
-@code{W3} leaves the size of @code{W2} unchanged:
+Split @code{W2} to make a new window @code{W4} as follows.
 
 @smallexample
 @group
@@ -846,24 +990,25 @@ If @code{window-combination-resize} is @code{nil}, splitting window
     | ____________________________________ |
     ||                                    ||
     ||                                    ||
-    ||                                    ||
-    ||                                    ||
     ||_________________W2_________________||
     | ____________________________________ |
     ||                                    ||
-    ||_________________W3_________________||
-    | ____________________________________ |
     ||                                    ||
     ||_________________W4_________________||
+    | ____________________________________ |
+    ||                                    ||
+    ||                                    ||
+    ||_________________W3_________________||
     |__________________W1__________________|
 
 @end group
 @end smallexample
 
 @noindent
-If @code{window-combination-resize} is @code{t}, splitting @code{W3}
-instead leaves all three live windows with approximately the same
-height:
+Now, when enlarging a window vertically, Emacs tries to obtain the
+corresponding space from its lower sibling, provided such a window
+exists.  In our scenario, enlarging @code{W4} will steal space from
+@code{W3}.
 
 @smallexample
 @group
@@ -875,36 +1020,119 @@ height:
     | ____________________________________ |
     ||                                    ||
     ||                                    ||
+    ||                                    ||
+    ||                                    ||
+    ||_________________W4_________________||
+    | ____________________________________ |
     ||_________________W3_________________||
+    |__________________W1__________________|
+
+@end group
+@end smallexample
+
+@noindent
+Deleting @code{W4} will now give its entire space to @code{W2},
+including the space earlier stolen from @code{W3}.
+
+@smallexample
+@group
+     ______________________________________
     | ____________________________________ |
     ||                                    ||
     ||                                    ||
-    ||_________________W4_________________||
+    ||                                    ||
+    ||                                    ||
+    ||                                    ||
+    ||                                    ||
+    ||                                    ||
+    ||                                    ||
+    ||_________________W2_________________||
+    | ____________________________________ |
+    ||_________________W3_________________||
     |__________________W1__________________|
 
 @end group
 @end smallexample
 
+@noindent
+This can be counterintutive, in particular if @code{W4} were used for
+displaying a buffer only temporarily (@pxref{Temporary Displays}), and
+you want to continue working with the initial layout.
+
+The behavior can be fixed by making a new parent window when splitting
+@code{W2}.  The variable described next allows to do that.
+
 @defopt window-combination-limit
-If the value of this variable is @code{t}, the @code{split-window}
-function always creates a new internal window.  If the value is
-@code{nil}, the new live window is allowed to share the existing
+This variable controls whether splitting a window shall make a new
+parent window.  The following values are recognized:
+
+@table @code
+@item nil
+This means that the new live window is allowed to share the existing
 parent window, if one exists, provided the split occurs in the same
-direction as the existing window combination (otherwise, a new
-internal window is created anyway).  The default is @code{nil}.  Other
-values are reserved for future use.
-
-Thus, if the value of this variable is at all times @code{t}, then at
-all times every window tree is a binary tree (a tree where each window
-except the root window has exactly one sibling).
-
-Furthermore, @code{split-window} calls
-@code{set-window-combination-limit} on the newly-created internal
-window, recording the current value of this variable.  This affects
-how the window tree is rearranged when the child windows are deleted
-(see below).
+direction as the existing window combination (otherwise, a new internal
+window is created anyway).
+
+@item window-size
+In this case @code{display-buffer} makes a new parent window if it is
+passed a @code{window-height} or @code{window-width} entry in the
+@var{alist} argument (@pxref{Display Action Functions}).
+
+@item temp-buffer
+This value causes the creation of a new parent window when a window is
+split for showing a temporary buffer (@pxref{Temporary Displays}) only.
+
+@item display-buffer
+This means that when @code{display-buffer} (@pxref{Choosing Window})
+splits a window it always makes a new parent window.
+
+@item t
+In this case a new parent window is always created when splitting a
+window.  Thus, if the value of this variable is at all times @code{t},
+then at all times every window tree is a binary tree (a tree where each
+window except the root window has exactly one sibling).
+@end table
+
+The default is @code{nil}.  Other values are reserved for future use.
+
+If, as a consequence of this variable's setting, @code{split-window}
+makes a new parent window, it also calls
+@code{set-window-combination-limit} (see below) on the newly-created
+internal window.  This affects how the window tree is rearranged when
+the child windows are deleted (see below).
 @end defopt
 
+  If @code{window-combination-limit} is @code{t}, splitting @code{W2} in
+the initial configuration of our scenario would have produced this:
+
+@smallexample
+@group
+     ______________________________________
+    | ____________________________________ |
+    || __________________________________ ||
+    |||                                  |||
+    |||________________W2________________|||
+    || __________________________________ ||
+    |||                                  |||
+    |||________________W4________________|||
+    ||_________________W5_________________||
+    | ____________________________________ |
+    ||                                    ||
+    ||                                    ||
+    ||_________________W3_________________||
+    |__________________W1__________________|
+
+@end group
+@end smallexample
+
+@noindent
+A new internal window @code{W5} has been created; its children are
+@code{W2} and the new live window @code{W4}.  Now, @code{W2} is the only
+sibling of @code{W4}, so enlarging @code{W4} will try to shrink
+@code{W2}, leaving @code{W3} unaffected.  Observe that @code{W5}
+represents a vertical combination of two windows embedded in the
+vertical combination @code{W1}.
+
 @cindex window combination limit
 @defun set-window-combination-limit window limit
 This functions sets the @dfn{combination limit} of the window
@@ -912,25 +1140,52 @@ This functions sets the @dfn{combination limit} of the window
 function @code{window-combination-limit}.  See below for its effects;
 note that it is only meaningful for internal windows.  The
 @code{split-window} function automatically calls this function, passing
-the value of the variable @code{window-combination-limit} as
-@var{limit}.
+it @code{t} as @var{limit}, provided the value of the variable
+@code{window-combination-limit} is @code{t} when it is called.
 @end defun
 
 @defun window-combination-limit window
 This function returns the combination limit for @var{window}.
 
-The combination limit is meaningful only for an internal window.  If
-it is @code{nil}, then Emacs is allowed to automatically delete
+The combination limit is meaningful only for an internal window.  If it
+is @code{nil}, then Emacs is allowed to automatically delete
 @var{window}, in response to a window deletion, in order to group the
 child windows of @var{window} with its sibling windows to form a new
 window combination.  If the combination limit is @code{t}, the child
-windows of @var{window} are never automatically re-combined with its
+windows of @var{window} are never automatically recombined with its
 siblings.
+
+If, in the configuration shown at the beginning of this section, the
+combination limit of @code{W4} (the parent window of @code{W6} and
+@code{W7}) is @code{t}, deleting @code{W5} will not implicitly delete
+@code{W4} too.
 @end defun
 
-  To illustrate the effect of @code{window-combination-limit},
-consider the following configuration (throughout this example, we will
-assume that @code{window-combination-resize} is @code{nil}):
+Alternatively, the problems sketched above can be avoided by always
+resizing all windows in the same combination whenever one of its windows
+is split or deleted.  This also permits to split windows that would be
+otherwise too small for such an operation.
+
+@defopt window-combination-resize
+If this variable is @code{nil}, @code{split-window} can only split a
+window (denoted by @var{window}) if @var{window}'s screen area is large
+enough to accommodate both itself and the new window.
+
+If this variable is @code{t}, @code{split-window} tries to resize all
+windows that are part of the same combination as @var{window}, in order
+to accommodate the new window.  In particular, this may allow
+@code{split-window} to succeed even if @var{window} is a fixed-size
+window or too small to ordinarily split.  Furthermore, subsequently
+resizing or deleting @var{window} may resize all other windows in its
+combination.
+
+The default is @code{nil}.  Other values are reserved for future use.
+The value of this variable is ignored when
+@code{window-combination-limit} is non-@code{nil}.
+@end defopt
+
+  To illustrate the effect of @code{window-combination-resize}, consider
+the following frame layout.
 
 @smallexample
 @group
@@ -940,12 +1195,12 @@ assume that @code{window-combination-resize} is @code{nil}):
     ||                                    ||
     ||                                    ||
     ||                                    ||
-    ||                                    ||
-    ||                                    ||
     ||_________________W2_________________||
     | ____________________________________ |
     ||                                    ||
     ||                                    ||
+    ||                                    ||
+    ||                                    ||
     ||_________________W3_________________||
     |__________________W1__________________|
 
@@ -953,8 +1208,8 @@ assume that @code{window-combination-resize} is @code{nil}):
 @end smallexample
 
 @noindent
-If @code{window-combination-limit} is @code{nil}, splitting @code{W2}
-into two windows, one above the other, yields
+If @code{window-combination-resize} is @code{nil}, splitting window
+@code{W3} leaves the size of @code{W2} unchanged:
 
 @smallexample
 @group
@@ -962,171 +1217,50 @@ into two windows, one above the other, yields
     | ____________________________________ |
     ||                                    ||
     ||                                    ||
-    ||_________________W2_________________||
-    | ____________________________________ |
     ||                                    ||
     ||                                    ||
-    ||_________________W4_________________||
+    ||_________________W2_________________||
     | ____________________________________ |
     ||                                    ||
-    ||                                    ||
     ||_________________W3_________________||
+    | ____________________________________ |
+    ||                                    ||
+    ||_________________W4_________________||
     |__________________W1__________________|
 
 @end group
 @end smallexample
 
 @noindent
-The newly-created window, @code{W4}, shares the same internal window
-@code{W1}.  If @code{W4} is resized, it is allowed to resize the other
-live window, @code{W3}.
-
-  If @code{window-combination-limit} is @code{t}, splitting @code{W2}
-in the initial configuration would instead have produced this:
+If @code{window-combination-resize} is @code{t}, splitting @code{W3}
+instead leaves all three live windows with approximately the same
+height:
 
 @smallexample
 @group
      ______________________________________
     | ____________________________________ |
-    || __________________________________ ||
-    |||                                  |||
-    |||________________W2________________|||
-    || __________________________________ ||
-    |||                                  |||
-    |||________________W4________________|||
-    ||_________________W5_________________||
+    ||                                    ||
+    ||                                    ||
+    ||_________________W2_________________||
     | ____________________________________ |
     ||                                    ||
     ||                                    ||
     ||_________________W3_________________||
+    | ____________________________________ |
+    ||                                    ||
+    ||                                    ||
+    ||_________________W4_________________||
     |__________________W1__________________|
 
 @end group
 @end smallexample
 
 @noindent
-A new internal window @code{W5} has been created; its children are
-@code{W2} and the new live window @code{W4}.  Now, @code{W2} is the
-only sibling of @code{W4}, so resizing @code{W4} will resize
-@code{W2}, leaving @code{W3} unaffected.
+Deleting any of the live windows @code{W2}, @code{W3} or @code{W4} will
+distribute its space proportionally among the two remaining live
+windows.
 
-  For interactive use, Emacs provides two commands which always split
-the selected window.  These call @code{split-window} internally.
-
-@deffn Command split-window-right &optional size
-This function splits the selected window into two side-by-side
-windows, putting the selected window on the left.  If @var{size} is
-positive, the left window gets @var{size} columns; if @var{size} is
-negative, the right window gets @minus{}@var{size} columns.
-@end deffn
-
-@deffn Command split-window-below &optional size
-This function splits the selected window into two windows, one above
-the other, leaving the upper window selected.  If @var{size} is
-positive, the upper window gets @var{size} lines; if @var{size} is
-negative, the lower window gets @minus{}@var{size} lines.
-@end deffn
-
-@defopt split-window-keep-point
-If the value of this variable is non-@code{nil} (the default),
-@code{split-window-below} behaves as described above.
-
-If it is @code{nil}, @code{split-window-below} adjusts point in each
-of the two windows to minimize redisplay.  (This is useful on slow
-terminals.)  It selects whichever window contains the screen line that
-point was previously on.  Note that this only affects
-@code{split-window-below}, not the lower-level @code{split-window}
-function.
-@end defopt
-
-@node Deleting Windows
-@section Deleting Windows
-@cindex deleting windows
-
-  @dfn{Deleting} a window removes it from the frame's window tree.  If
-the window is a live window, it disappears from the screen.  If the
-window is an internal window, its child windows are deleted too.
-
-  Even after a window is deleted, it continues to exist as a Lisp
-object, until there are no more references to it.  Window deletion can
-be reversed, by restoring a saved window configuration (@pxref{Window
-Configurations}).
-
-@deffn Command delete-window &optional window
-This function removes @var{window} from display and returns
-@code{nil}.  If @var{window} is omitted or @code{nil}, it defaults to
-the selected window.  If deleting the window would leave no more
-windows in the window tree (e.g. if it is the only live window in the
-frame), an error is signaled.
-
-By default, the space taken up by @var{window} is given to one of its
-adjacent sibling windows, if any.  However, if the variable
-@code{window-combination-resize} is non-@code{nil}, the space is
-proportionally distributed among any remaining windows in the window
-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 @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
-called with the argument @var{window}, in lieu of the usual action of
-@code{delete-window}.  Otherwise, this function obeys the
-@code{window-atom} or @code{window-side} window parameter, if any.
-@xref{Window Parameters}.
-@end deffn
-
-@deffn Command delete-other-windows &optional window
-This function makes @var{window} fill its frame, by deleting other
-windows as necessary.  If @var{window} is omitted or @code{nil}, it
-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 @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,
-that function is called with the argument @var{window}, in lieu of the
-usual action of @code{delete-other-windows}.  Otherwise, this function
-obeys the @code{window-atom} or @code{window-side} window parameter,
-if any.  @xref{Window Parameters}.
-@end deffn
-
-@deffn Command delete-windows-on &optional buffer-or-name frame
-This function deletes all windows showing @var{buffer-or-name}, by
-calling @code{delete-window} on those windows.  @var{buffer-or-name}
-should be a buffer, or the name of a buffer; if omitted or @code{nil},
-it defaults to the current buffer.  If there are no windows showing
-the specified buffer, this function does nothing.  If the specified
-buffer is a minibuffer, an error is signaled.
-
-If there is a dedicated window showing the buffer, and that window is
-the only one on its frame, this function also deletes that frame if it
-is not the only frame on the terminal.
-
-The optional argument @var{frame} specifies which frames to operate
-on:
-
-@itemize @bullet
-@item @code{nil}
-means operate on all frames.
-@item @code{t}
-means operate on the selected frame.
-@item @code{visible}
-means operate on all visible frames.
-@item @code{0}
-means operate on all visible or iconified frames.
-@item A frame
-means operate on that frame.
-@end itemize
-
-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 meanings of @code{t} and @code{nil} here
-are the opposite of what they are in those other functions.
-@end deffn
 
 @node Selecting Windows
 @section Selecting Windows
@@ -1550,6 +1684,26 @@ normally tries to display the buffer in some other window, by invoking
 instead.
 @end deffn
 
+By default, @code{switch-to-buffer} sets @code{window-point} of the
+window used to the buffer's position of @code{point}.  This behavior can
+be tuned using the following option.
+
+@defopt switch-to-buffer-preserve-window-point
+If this variable is @code{nil}, @code{switch-to-buffer} displays the
+buffer specified by @var{buffer-or-name} at the position of that
+buffer's @code{point}.  If this variable is @code{already-displayed}, it
+tries to display the buffer at its previous position in the selected
+window, provided the buffer is currently displayed in some other window
+on any visible or iconified frame.  If this variable is @code{t},
+@code{switch-to-buffer} unconditionally tries to display the buffer at
+its previous position in the selected window.
+
+This variable is ignored if the buffer is already displayed in the
+selected window or never appeared in it before, or if
+@code{switch-to-buffer} calls @code{pop-to-buffer} to display the
+buffer.
+@end defopt
+
 The next two functions are similar to @code{switch-to-buffer}, except
 for the described features.
 
@@ -1775,9 +1929,51 @@ It actually performs the split by calling the function specified in
 @code{split-window-preferred-function} (@pxref{Choosing Window
 Options}).
 
-It can fail if no window splitting can be performed for some reason
-(e.g. if there is just one frame and it has an @code{unsplittable}
-frame parameter; @pxref{Buffer Parameters}).
+The size of the new window can be adjusted by supplying
+@code{window-height} and @code{window-width} entries in @var{alist}.  To
+adjust the window's height, use an entry whose @sc{car} is
+@code{window-height} and whose @sc{cdr} is one of:
+
+@itemize @bullet
+@item
+@code{nil} means to leave the height of the new window alone.
+
+@item
+A number specifies the desired height of the new window.  An integer
+number specifies the number of lines of the window.  A floating point
+number gives the fraction of the window's height with respect to the
+height of the frame's root window.
+
+@item
+If the @sc{cdr} specifies a function, that function is called with one
+argument - the new window.  The function is supposed to adjust the
+height of the window; its return value is ignored.  Suitable functions
+are @code{shrink-window-if-larger-than-buffer} and
+@code{fit-window-to-buffer}, see @ref{Resizing Windows}.
+@end itemize
+
+To adjust the window's width, use an entry whose @sc{car} is
+@code{window-width} and whose @sc{cdr} is one of:
+
+@itemize @bullet
+@item
+@code{nil} means to leave the width of the new window alone.
+
+@item
+A number specifies the desired width of the new window.  An integer
+number specifies the number of columns of the window.  A floating point
+number gives the fraction of the window's width with respect to the
+width of the frame's root window.
+
+@item
+If the @sc{cdr} specifies a function, that function is called with one
+argument - the new window.  The function is supposed to adjust the width
+of the window; its return value is ignored.
+@end itemize
+
+This function can fail if no window splitting can be performed for some
+reason (e.g. if there is just one frame and it has an
+@code{unsplittable} frame parameter; @pxref{Buffer Parameters}).
 @end defun
 
 @defun display-buffer-use-some-window buffer alist
@@ -1786,6 +1982,26 @@ window and displaying the buffer in that window.  It can fail if all
 windows are dedicated to another buffer (@pxref{Dedicated Windows}).
 @end defun
 
+@defun display-buffer-below-selected buffer alist
+This function tries to display @var{buffer} in a window below the
+selected window.  This means to either split the selected window or
+reuse the window below the selected one.
+@end defun
+
+@defun display-buffer-in-previous-window buffer alist
+This function tries to display @var{buffer} in a window previously
+showing it.  If @var{alist} has a non-@code{nil}
+@code{inhibit-same-window} entry, the selected window is not eligible
+for reuse.  If @var{alist} contains a @code{reusable-frames} entry, its
+value determines which frames to search for a suitable window as with
+@code{display-buffer-reuse-window}.
+
+If @var{alist} has a @code{previous-window} entry, the window
+specified by that entry will override any other window found by the
+methods above, even if that window never showed @var{buffer} before.
+@end defun
+
+
 @node Choosing Window Options
 @section Additional Options for Displaying Buffers
 
@@ -2086,45 +2302,77 @@ 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
-automate the above decisions for you.
+   The following command uses information on how the window for
+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
 @var{window} must be a live window and defaults to the selected one.
 With prefix argument @var{kill} non-@code{nil}, it kills the buffer
-instead of burying it.
-
-Quitting @var{window} means to proceed as follows: If @var{window} was
-created specially for displaying its current buffer, delete @var{window}
-provided its frame contains at least one other live window.  If
-@var{window} is the only window on its frame and there are other frames
-on the frame's terminal, the value of @var{kill} determines how to
-proceed with the window.  If @var{kill} is @code{nil}, the fate of the
-frame is determined by calling @code{frame-auto-hide-function} (see
-below) with that frame as sole argument.  If @var{kill} is
-non-@code{nil}, the frame is deleted unconditionally.
-
-If @var{window} was reused for displaying its buffer, this command tries
-to display the buffer previously shown in it.  It also tries to restore
-the window start (@pxref{Window Start and End}) and point (@pxref{Window
-Point}) positions of the previously shown buffer.  If, in addition, the
-current buffer was temporarily resized, this command will also try to
-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
-calls @code{switch-to-prev-buffer} (@pxref{Window History}) to show some
-other buffer instead.
+instead of burying it.  It calls the function @code{quit-restore-window}
+described next to deal with the window and its buffer.
 @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}
-after it's done.
+@defun quit-restore-window &optional window bury-or-kill
+This function tries to restore the state of @var{window} that existed
+before its buffer was displayed in it.  The optional argument
+@var{window} must be a live window and defaults to the selected one.
+
+If @var{window} was created specially for displaying its buffer, this
+function deletes @var{window} provided its frame contains at least one
+other live window.  If @var{window} is the only window on its frame and
+there are other frames on the frame's terminal, the value of the
+optional argument @var{bury-or-kill} determines how to proceed with the
+window.  If @var{bury-or-kill} equals @code{kill}, the frame is deleted
+unconditionally.  Otherwise, the fate of the frame is determined by
+calling @code{frame-auto-hide-function} (see below) with that frame as
+sole argument.
+
+Otherwise, this function tries to redisplay the buffer previously shown
+in @var{window}.  It also tries to restore the window start
+(@pxref{Window Start and End}) and point (@pxref{Window Point})
+positions of the previously shown buffer.  If, in addition,
+@var{window}'s buffer was temporarily resized, this function will also
+try to restore the original height of @var{window}.
+
+The 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 function calls
+@code{switch-to-prev-buffer} (@pxref{Window History}) to show some other
+buffer instead.
+
+The optional argument @var{bury-or-kill} specifes how to deal with
+@var{window}'s buffer.  The following values are handled:
+
+@table @code
+@item nil
+This means to not deal with the buffer in any particular way.  As a
+consequence, if @var{window} is not deleted, invoking
+@code{switch-to-prev-buffer} will usually show the buffer again.
+
+@item append
+This means that if @var{window} is not deleted, its buffer is moved to
+the end of @var{window}'s list of previous buffers, so it's less likely
+that a future invocation of @code{switch-to-prev-buffer} will switch to
+it.  Also, it moves the buffer to the end of the frame's buffer list.
+
+@item bury
+This means that if @var{window} is not deleted, its buffer is removed
+from @var{window}'s list of previous buffers.  Also, it moves the buffer
+to the end of the frame's buffer list.  This value provides the most
+reliable remedy to not have @code{switch-to-prev-buffer} switch to this
+buffer again without killing the buffer.
+
+@item kill
+This means to kill @var{window}'s buffer.
+@end table
+
+@code{quit-restore-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} after it's done.
+@end defun
 
 The following option specifies how to deal with a frame containing just
 one window that should be either quit, or whose buffer should be buried.
@@ -2135,10 +2383,9 @@ 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 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
-should be buried.
+to bury.  It is also called by @code{quit-restore-window} (see above)
+when the frame of the window to quit has been specially created for
+displaying that window's buffer and the buffer is not killed.
 
 The default is to call @code{iconify-frame} (@pxref{Visibility of
 Frames}).  Alternatively, you may specify either @code{delete-frame}
@@ -2146,9 +2393,9 @@ Frames}).  Alternatively, you may specify either @code{delete-frame}
 @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 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.
+Note that the function specified by this option is called only if the
+specified frame contains just one live window and there is at least one
+other frame on the same terminal.
 @end defopt
 
 
@@ -3123,8 +3370,8 @@ frame into the root window of that very frame only).
 
 @defun window-state-get &optional window writable
 This function returns the state of @var{window} as a Lisp object.  The
-argument @var{window} can be any window and defaults to the root window
-of the selected frame.
+argument @var{window} must be a valid window and defaults to the root
+window 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
@@ -3267,10 +3514,28 @@ from.  It is installed by @code{window-state-get} (@pxref{Window
 Configurations}).
 
 @item @code{quit-restore}
-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}).
+This parameter is installed by the buffer display functions
+(@pxref{Choosing Window}) and consulted by @code{quit-restore-window}
+(@pxref{Quitting Windows}).  It contains four elements:
+
+The first element is one of the symbols @code{window} - meaning that the
+window has been specially created by @code{display-buffer}, @code{frame}
+- a separate frame has been created, @code{same} - the window has
+displayed the same buffer before, or @code{other} - the window showed
+another buffer before.
+
+The second element is either one of the symbols @code{window} or
+@code{frame}, or a list whose elements are the buffer shown in the
+window before, that buffer's window start and window point positions,
+and the window's height at that time.
+
+The third element is the window selected at the time the parameter was
+created.  The function @code{quit-restore-window} tries to reselect that
+window when it deletes the window passed to it as argument.
+
+The fourth element is the buffer whose display caused the creation of
+this parameter.  @code{quit-restore-window} deletes the specified window
+only if it still shows that buffer.
 @end table
 
 There are additional parameters @code{window-atom} and @code{window-side};
diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog
index d719a02e32e..7322613e0db 100644
--- a/doc/misc/ChangeLog
+++ b/doc/misc/ChangeLog
@@ -1,3 +1,68 @@
+2012-11-13  Glenn Morris  <rgm@gnu.org>
+
+        * flymake.texi (Customizable variables)
+        (Highlighting erroneous lines): Mention flymake-error-bitmap,
+        flymake-warning-bitmap, and flymake-fringe-indicator-position.
+
+2012-11-12  Vincent Belaïche  <vincentb1@users.sourceforge.net>
+
+        * ses.texi: Doc for ses-rename-cell, ses-repair-cell-reference-all & ses-range.
+        In all file place SES into @acronym{...}.
+        (Advanced Features): Add key index and function index for
+        ses-set-header-row. Add description for function
+        ses-rename-cell. Add description for function
+        ses-repair-cell-reference-all.
+        (Ranges in formulas): Add description for ses-range flags.
+
+2012-11-12  Paul Eggert  <eggert@cs.ucla.edu>
+
+        * texinfo.tex: Merge from gnulib.
+
+2012-11-10  Chong Yidong  <cyd@gnu.org>
+
+        * url.texi (Introduction): Move url-configuration-directory to
+        Customization node.
+        (Parsed URIs): Split into its own node.
+        (URI Encoding): New node.
+        (Defining New URLs): Remove empty chapter.
+        (Retrieving URLs): Add an introduction.  Doc fix for url-retrieve.
+        Improve docs for url-queue-*.
+        (Supported URL Types): Copyedits.  Delete empty subnodes.
+
+        * url.texi (Introduction): Rename from Getting Started.  Rewrite
+        the introduction.
+        (URI Parsing): Rewrite.  Omit the obsolete attributes slot.
+
+2012-11-10  Glenn Morris  <rgm@gnu.org>
+
+        * cl.texi (Obsolete Setf Customization):
+        Revert defsetf example to the more correct let rather than prog1.
+        Give define-modify-macro, defsetf, and define-setf-method
+        gv.el replacements.
+
+        * cl.texi (Overview): Mention EIEIO here, as well as the appendix.
+        (Setf Extensions): Remove obsolete reference.
+        (Obsolete Setf Customization):
+        Move note on lack of setf functions to lispref/variables.texi.
+        Undocument get-setf-method, since it no longer exists.
+        Mention simple defsetf replaced by gv-define-simple-setter.
+
+2012-11-03  Glenn Morris  <rgm@gnu.org>
+
+        * cl.texi: Further general copyedits.
+        (List Functions): Remove copy-tree, standard elisp for some time.
+        (Efficiency Concerns): Comment out examples that no longer apply.
+        (Compiler Optimizations): Rename from "Optimizing Compiler"; reword.
+        (Creating Symbols, Random Numbers): De-emphasize internal
+        variables cl--gensym-counter and cl--random-state.  (Bug#12788)
+        (Naming Conventions, Type Predicates, Macros)
+        (Predicates on Numbers): No longer mention cl-floatp-safe.
+
+2012-11-02  Katsumi Yamaoka  <yamaoka@jpl.org>
+
+        * gnus.texi (Mail Source Specifiers):
+        Document :leave keyword used for pop mail source.
+
 2012-11-01  Glenn Morris  <rgm@gnu.org>
 
         * cl.texi: General copyedits for style, line-breaks, etc.
diff --git a/doc/misc/cl.texi b/doc/misc/cl.texi
index 4a728049ce8..a50be1027f3 100644
--- a/doc/misc/cl.texi
+++ b/doc/misc/cl.texi
@@ -107,7 +107,8 @@ for various reasons:
 @item
 Some features are too complex or bulky relative to their benefit
 to Emacs Lisp programmers.  CLOS and Common Lisp streams are fine
-examples of this group.
+examples of this group.  (The separate package EIEIO implements
+a subset of CLOS functionality.  @xref{Top, , Introduction, eieio, EIEIO}.)
 
 @item
 Other features cannot be implemented without modification to the
@@ -229,7 +230,7 @@ by @code{cl--}.  Here is a complete list of functions prefixed by
 
 @example
 cl-callf           cl-callf2          cl-defsubst
-cl-floatp-safe     cl-letf            cl-letf*
+cl-letf            cl-letf*
 @end example
 
 @c This is not uninteresting I suppose, but is of zero practical relevance
@@ -239,13 +240,13 @@ they do not cause other components like @file{cl-extra} to be loaded.
 
 @example
 cl-evenp           cl-oddp            cl-minusp
-cl-plusp           cl-floatp-safe     cl-endp
+cl-plusp           cl-endp            cl-subst
 cl-copy-list       cl-list*           cl-ldiff
 cl-rest            cl-decf [1]        cl-incf [1]
 cl-acons           cl-adjoin [2]      cl-pairlis
 cl-pushnew [1,2]   cl-declaim         cl-proclaim
 cl-caaar@dots{}cl-cddddr                  cl-first@dots{}cl-tenth
-cl-subst           cl-mapcar [3]
+cl-mapcar [3]
 @end example
 
 @noindent
@@ -300,7 +301,8 @@ calls to it may be expanded into in-line code by the byte compiler.
 This is analogous to the @code{defsubst} form;
 @code{cl-defsubst} uses a different method (compiler macros) which
 works in all versions of Emacs, and also generates somewhat more
-@c Really?
+@c For some examples,
+@c see http://lists.gnu.org/archive/html/emacs-devel/2012-11/msg00009.html
 efficient inline expansions.  In particular, @code{cl-defsubst}
 arranges for the processing of keyword arguments, default values,
 etc., to be done at compile-time whenever possible.
@@ -702,11 +704,13 @@ The type symbol @code{real} is a synonym for @code{number}, and
 The type symbols @code{character} and @code{string-char} match
 integers in the range from 0 to 255.
 
+@c No longer relevant, so covered by first item above (float -> floatp).
+@ignore
 @item
 The type symbol @code{float} uses the @code{cl-floatp-safe} predicate
 defined by this package rather than @code{floatp}, so it will work
-@c FIXME are any such platforms still relevant?
 correctly even in Emacs versions without floating-point support.
+@end ignore
 
 @item
 The type list @code{(integer @var{low} @var{high})} represents all
@@ -833,7 +837,7 @@ constructs.
 * Conditionals::           @code{cl-case}, @code{cl-typecase}.
 * Blocks and Exits::       @code{cl-block}, @code{cl-return}, @code{cl-return-from}.
 * Iteration::              @code{cl-do}, @code{cl-dotimes}, @code{cl-dolist}, @code{cl-do-symbols}.
-* Loop Facility::          The Common Lisp @code{cl-loop} macro.
+* Loop Facility::          The Common Lisp @code{loop} macro.
 * Multiple Values::        @code{cl-values}, @code{cl-multiple-value-bind}, etc.
 @end menu
 
@@ -971,7 +975,7 @@ a
 The generalized variable @code{buffer-substring}, listed above,
 also works in this way by replacing a portion of the current buffer.
 
-@c FIXME? Also `eq'? (see cl-lib.el)
+@c FIXME?  Also `eq'? (see cl-lib.el)
 
 @c Currently commented out in cl.el.
 @ignore
@@ -986,13 +990,10 @@ only interesting when used with places you define yourself with
 @xref{Obsolete Setf Customization}.
 @end ignore
 
+@c FIXME?  Is this still true?
 @item
 A macro call, in which case the macro is expanded and @code{setf}
 is applied to the resulting form.
-
-@item
-Any form for which a @code{defsetf} or @code{define-setf-method}
-has been made.  @xref{Obsolete Setf Customization}.
 @end itemize
 
 @c FIXME should this be in lispref?  It seems self-evident.
@@ -1521,7 +1522,7 @@ Common Lisp @dfn{blocks} provide a non-local exit mechanism very
 similar to @code{catch} and @code{throw}, with lexical scoping.
 This package actually implements @code{cl-block}
 in terms of @code{catch}; however, the lexical scoping allows the
-optimizing byte-compiler to omit the costly @code{catch} step if the
+byte-compiler to omit the costly @code{catch} step if the
 body of the block does not actually @code{cl-return-from} the block.
 
 @defmac cl-block name forms@dots{}
@@ -1558,7 +1559,7 @@ just as in Common Lisp.
 Because they are implemented in terms of Emacs Lisp's @code{catch}
 and @code{throw}, blocks have the same overhead as actual
 @code{catch} constructs (roughly two function calls).  However,
-the optimizing byte compiler will optimize away the @code{catch}
+the byte compiler will optimize away the @code{catch}
 if the block does
 not in fact contain any @code{cl-return} or @code{cl-return-from} calls
 that jump to it.  This means that @code{cl-do} loops and @code{cl-defun}
@@ -1723,18 +1724,18 @@ iterating over vectors or lists.
 @section Loop Facility
 
 @noindent
-A common complaint with Lisp's traditional looping constructs is
-that they are either too simple and limited, such as Common Lisp's
-@code{dotimes} or Emacs Lisp's @code{while}, or too unreadable and
-obscure, like Common Lisp's @code{do} loop.
+A common complaint with Lisp's traditional looping constructs was
+that they were either too simple and limited, such as @code{dotimes}
+or @code{while}, or too unreadable and obscure, like Common Lisp's
+@code{do} loop.
 
-To remedy this, recent versions of Common Lisp have added a new
-construct called the ``Loop Facility'' or ``@code{loop} macro'',
-with an easy-to-use but very powerful and expressive syntax.
+To remedy this, Common Lisp added a construct called the ``Loop
+Facility'' or ``@code{loop} macro'', with an easy-to-use but very
+powerful and expressive syntax.
 
 @menu
-* Loop Basics::           @code{cl-loop} macro, basic clause structure.
-* Loop Examples::         Working examples of @code{cl-loop} macro.
+* Loop Basics::           The @code{cl-loop} macro, basic clause structure.
+* Loop Examples::         Working examples of the @code{cl-loop} macro.
 * For Clauses::           Clauses introduced by @code{for} or @code{as}.
 * Iteration Clauses::     @code{repeat}, @code{while}, @code{thereis}, etc.
 * Accumulation Clauses::  @code{collect}, @code{sum}, @code{maximize}, etc.
@@ -1767,9 +1768,9 @@ Common Lisp specifies a certain general order of clauses in a
 loop:
 
 @example
-(cl-loop @var{name-clause}
-         @var{var-clauses}@dots{}
-         @var{action-clauses}@dots{})
+(loop @var{name-clause}
+      @var{var-clauses}@dots{}
+      @var{action-clauses}@dots{})
 @end example
 
 The @var{name-clause} optionally gives a name to the implicit
@@ -1795,10 +1796,10 @@ also use regular Lisp @code{cl-return} or @code{cl-return-from} to
 break out of the loop.)
 @end defmac
 
-The following sections give some examples of the Loop Macro in
+The following sections give some examples of the loop macro in
 action, and describe the particular loop clauses in great detail.
 Consult the second edition of Steele for additional discussion
-and examples of the @code{loop} macro.
+and examples.
 
 @node Loop Examples
 @subsection Loop Examples
@@ -2162,8 +2163,9 @@ that was just set by the previous clause; in the second loop,
 based on the value of @code{x} left over from the previous time
 through the loop.
 
-Another feature of the @code{cl-loop} macro is @dfn{destructuring},
-similar in concept to the destructuring provided by @code{defmacro}.
+Another feature of the @code{cl-loop} macro is @emph{destructuring},
+similar in concept to the destructuring provided by @code{defmacro}
+(@pxref{Argument Lists}).
 The @var{var} part of any @code{for} clause can be given as a list
 of variables instead of a single variable.  The values produced
 during loop execution must be lists; the values in the lists are
@@ -2375,7 +2377,7 @@ by the name @code{it} in the ``then'' part.  For example:
 (setq funny-numbers '(6 13 -1))
      @result{} (6 13 -1)
 (cl-loop for x below 10
-         if (oddp x)
+         if (cl-oddp x)
            collect x into odds
            and if (memq x funny-numbers) return (cdr it) end
          else
@@ -2441,15 +2443,14 @@ loop.  Many of the examples in this section illustrate the use of
 
 @item return @var{form}
 This clause causes the loop to return immediately.  The following
-Lisp form is evaluated to give the return value of the @code{loop}
+Lisp form is evaluated to give the return value of the loop
 form.  The @code{finally} clauses, if any, are not executed.
 Of course, @code{return} is generally used inside an @code{if} or
 @code{unless}, as its use in a top-level loop clause would mean
 the loop would never get to ``loop'' more than once.
 
 The clause @samp{return @var{form}} is equivalent to
-@c FIXME cl-do, cl-return?
-@samp{do (return @var{form})} (or @code{return-from} if the loop
+@samp{do (cl-return @var{form})} (or @code{cl-return-from} if the loop
 was named).  The @code{return} clause is implemented a bit more
 efficiently, though.
 @end table
@@ -2463,7 +2464,7 @@ clause, respectively.  Consult the source code in file
 
 This package's @code{cl-loop} macro is compatible with that of Common
 Lisp, except that a few features are not implemented:  @code{loop-finish}
-and data-type specifiers.  Naturally, the @code{for} clauses which
+and data-type specifiers.  Naturally, the @code{for} clauses that
 iterate over keymaps, overlays, intervals, frames, windows, and
 buffers are Emacs-specific extensions.
 
@@ -2516,17 +2517,17 @@ Destructuring is made available to the user by way of the
 following macro:
 
 @defmac cl-destructuring-bind arglist expr forms@dots{}
-This macro expands to code which executes @var{forms}, with
+This macro expands to code that executes @var{forms}, with
 the variables in @var{arglist} bound to the list of values
 returned by @var{expr}.  The @var{arglist} can include all
-the features allowed for @code{defmacro} argument lists,
+the features allowed for @code{cl-defmacro} argument lists,
 including destructuring.  (The @code{&environment} keyword
 is not allowed.)  The macro expansion will signal an error
 if @var{expr} returns a list of the wrong number of arguments
 or with incorrect keyword arguments.
 @end defmac
 
-This package also includes the Common Lisp @code{cl-define-compiler-macro}
+This package also includes the Common Lisp @code{define-compiler-macro}
 facility, which allows you to define compile-time expansions and
 optimizations for your functions.
 
@@ -2551,7 +2552,7 @@ appears as a standard part of this package:
 (cl-define-compiler-macro cl-member (&whole form a list &rest keys)
      (if (and (null keys)
               (eq (car-safe a) 'quote)
-              (not (floatp-safe (cadr a))))
+              (not (floatp (cadr a))))
          (list 'memq a list)
        form))
 @end example
@@ -2589,16 +2590,19 @@ mechanism that allows you to give the compiler special hints
 about the types of data that will be stored in particular variables,
 and about the ways those variables and functions will be used.  This
 package defines versions of all the Common Lisp declaration forms:
-@code{cl-declare}, @code{cl-locally}, @code{cl-proclaim}, @code{cl-declaim},
-and @code{cl-the}.
+@code{declare}, @code{locally}, @code{proclaim}, @code{declaim},
+and @code{the}.
 
-Most of the Common Lisp declarations are not currently useful in
-Emacs Lisp, as the byte-code system provides little opportunity
-to benefit from type information, and @code{special} declarations
-are redundant in a fully dynamically-scoped Lisp.  A few
-declarations are meaningful when the optimizing byte
-compiler is being used, however.  Under the earlier non-optimizing
-compiler, these declarations will effectively be ignored.
+Most of the Common Lisp declarations are not currently useful in Emacs
+Lisp.  For example, the byte-code system provides little
+opportunity to benefit from type information.
+@ignore
+and @code{special} declarations are redundant in a fully
+dynamically-scoped Lisp.
+@end ignore
+A few declarations are meaningful when byte compiler optimizations
+are enabled, as they are by the default.  Otherwise these
+declarations will effectively be ignored.
 
 @defun cl-proclaim decl-spec
 This function records a ``global'' declaration specified by
@@ -2609,7 +2613,7 @@ is evaluated and thus should normally be quoted.
 @defmac cl-declaim decl-specs@dots{}
 This macro is like @code{cl-proclaim}, except that it takes any number
 of @var{decl-spec} arguments, and the arguments are unevaluated and
-unquoted.  The @code{cl-declaim} macro also puts an @code{(cl-eval-when
+unquoted.  The @code{cl-declaim} macro also puts @code{(cl-eval-when
 (compile load eval) @dots{})} around the declarations so that they will
 be registered at compile-time as well as at run-time.  (This is vital,
 since normally the declarations are meant to influence the way the
@@ -2632,9 +2636,9 @@ In this package, @code{cl-locally} is no different from @code{progn}.
 
 @defmac cl-the type form
 Type information provided by @code{cl-the} is ignored in this package;
-in other words, @code{(cl-the @var{type} @var{form})} is equivalent
-to @var{form}.  Future versions of the optimizing byte-compiler may
-make use of this information.
+in other words, @code{(cl-the @var{type} @var{form})} is equivalent to
+@var{form}.  Future byte-compiler optimizations may make use of this
+information.
 
 For example, @code{mapcar} can map over both lists and arrays.  It is
 hard for the compiler to expand @code{mapcar} into an in-line loop
@@ -2655,35 +2659,31 @@ such as @code{type} and @code{ftype}, are silently ignored.
 
 @table @code
 @item special
+@c FIXME ?
 Since all variables in Emacs Lisp are ``special'' (in the Common
 Lisp sense), @code{special} declarations are only advisory.  They
-simply tell the optimizing byte compiler that the specified
+simply tell the byte compiler that the specified
 variables are intentionally being referred to without being
 bound in the body of the function.  The compiler normally emits
 warnings for such references, since they could be typographical
 errors for references to local variables.
 
 The declaration @code{(cl-declare (special @var{var1} @var{var2}))} is
-equivalent to @code{(defvar @var{var1}) (defvar @var{var2})} in the
-optimizing compiler, or to nothing at all in older compilers (which
-do not warn for non-local references).
+equivalent to @code{(defvar @var{var1}) (defvar @var{var2})}.
 
 In top-level contexts, it is generally better to write
 @code{(defvar @var{var})} than @code{(cl-declaim (special @var{var}))},
-since @code{defvar} makes your intentions clearer.  But the older
-byte compilers can not handle @code{defvar}s appearing inside of
-functions, while @code{(cl-declare (special @var{var}))} takes care
-to work correctly with all compilers.
+since @code{defvar} makes your intentions clearer.
 
 @item inline
 The @code{inline} @var{decl-spec} lists one or more functions
 whose bodies should be expanded ``in-line'' into calling functions
 whenever the compiler is able to arrange for it.  For example,
-the Common Lisp function @code{cadr} is declared @code{inline}
-by this package so that the form @code{(cadr @var{x})} will
-expand directly into @code{(car (cdr @var{x}))} when it is called
-in user functions, for a savings of one (relatively expensive)
-function call.
+the function @code{cl-acons} is declared @code{inline}
+by this package so that the form @code{(cl-acons @var{key} @var{value}
+@var{alist})} will
+expand directly into @code{(cons (cons @var{key} @var{value}) @var{alist})}
+when it is called in user functions, so as to save function calls.
 
 The following declarations are all equivalent.  Note that the
 @code{defsubst} form is a convenient way to define a function
@@ -2702,7 +2702,7 @@ request that a function you have defined should be inlined,
 but it is impolite to use it to request inlining of an external
 function.
 
-In Common Lisp, it is possible to use @code{(cl-declare (inline @dots{}))}
+In Common Lisp, it is possible to use @code{(declare (inline @dots{}))}
 before a particular call to a function to cause just that call to
 be inlined; the current byte compilers provide no way to implement
 this, so @code{(cl-declare (inline @dots{}))} is currently ignored by
@@ -2715,8 +2715,7 @@ declaration.
 
 @item optimize
 This declaration controls how much optimization is performed by
-the compiler.  Naturally, it is ignored by the earlier non-optimizing
-compilers.
+the compiler.
 
 The word @code{optimize} is followed by any number of lists like
 @code{(speed 3)} or @code{(safety 2)}.  Common Lisp defines several
@@ -2725,8 +2724,7 @@ and @code{safety}.  The value of a quality should be an integer from
 0 to 3, with 0 meaning ``unimportant'' and 3 meaning ``very important''.
 The default level for both qualities is 1.
 
-In this package, with the optimizing compiler, the
-@code{speed} quality is tied to the @code{byte-optimize}
+In this package, the @code{speed} quality is tied to the @code{byte-optimize}
 flag, which is set to @code{nil} for @code{(speed 0)} and to
 @code{t} for higher settings; and the @code{safety} quality is
 tied to the @code{byte-compile-delete-errors} flag, which is
@@ -2745,22 +2743,22 @@ just because of an error in a fully-optimized Lisp program.
 
 The @code{optimize} declaration is normally used in a top-level
 @code{cl-proclaim} or @code{cl-declaim} in a file; Common Lisp allows
-it to be used with @code{cl-declare} to set the level of optimization
+it to be used with @code{declare} to set the level of optimization
 locally for a given form, but this will not work correctly with the
-current version of the optimizing compiler.  (The @code{cl-declare}
+current byte-compiler.  (The @code{cl-declare}
 will set the new optimization level, but that level will not
 automatically be unset after the enclosing form is done.)
 
 @item warn
 This declaration controls what sorts of warnings are generated
-by the byte compiler.  Again, only the optimizing compiler
-generates warnings.  The word @code{warn} is followed by any
+by the byte compiler.  The word @code{warn} is followed by any
 number of ``warning qualities'', similar in form to optimization
 qualities.  The currently supported warning types are
 @code{redefine}, @code{callargs}, @code{unresolved}, and
 @code{free-vars}; in the current system, a value of 0 will
 disable these warnings and any higher value will enable them.
-See the documentation for the optimizing byte compiler for details.
+See the documentation of the variable @code{byte-compile-warnings}
+for more details.
 @end table
 
 @node Symbols
@@ -2873,19 +2871,17 @@ string is used as a prefix instead of @samp{G}.  Uninterned symbols
 are used in macro expansions for temporary variables, to ensure that
 their names will not conflict with ``real'' variables in the user's
 code.
-@end defun
 
-@defvar cl--gensym-counter
-This variable holds the counter used to generate @code{cl-gensym} names.
-It is incremented after each use by @code{cl-gensym}.  In Common Lisp
-this is initialized with 0, but this package initializes it with a
-random (time-dependent) value to avoid trouble when two files that
+(Internally, the variable @code{cl--gensym-counter} holds the counter
+used to generate names.  It is incremented after each use.  In Common
+Lisp this is initialized with 0, but this package initializes it with
+a random time-dependent value to avoid trouble when two files that
 each used @code{cl-gensym} in their compilation are loaded together.
-(Uninterned symbols become interned when the compiler writes them
-out to a file and the Emacs loader loads them, so their names have to
-be treated a bit more carefully than in Common Lisp where uninterned
+Uninterned symbols become interned when the compiler writes them out
+to a file and the Emacs loader loads them, so their names have to be
+treated a bit more carefully than in Common Lisp where uninterned
 symbols remain uninterned after loading.)
-@end defvar
+@end defun
 
 @defun cl-gentemp &optional x
 This function is like @code{cl-gensym}, except that it produces a new
@@ -2905,13 +2901,13 @@ provided.
 
 @noindent
 This section defines a few simple Common Lisp operations on numbers
-which were left out of Emacs Lisp.
+that were left out of Emacs Lisp.
 
 @menu
-* Predicates on Numbers::       @code{cl-plusp}, @code{cl-oddp}, @code{cl-floatp-safe}, etc.
-* Numerical Functions::         @code{abs}, @code{cl-floor}, etc.
+* Predicates on Numbers::       @code{cl-plusp}, @code{cl-oddp}, etc.
+* Numerical Functions::         @code{cl-floor}, @code{cl-ceiling}, etc.
 * Random Numbers::              @code{cl-random}, @code{cl-make-random-state}.
-* Implementation Parameters::   @code{cl-most-positive-float}.
+* Implementation Parameters::   @code{cl-most-positive-float}, etc.
 @end menu
 
 @node Predicates on Numbers
@@ -2941,11 +2937,13 @@ This predicate tests whether @var{integer} is even.  It is an
 error if the argument is not an integer.
 @end defun
 
+@ignore
 @defun cl-floatp-safe object
 This predicate tests whether @var{object} is a floating-point
 number.  On systems that support floating-point, this is equivalent
 to @code{floatp}.  On other systems, this always returns @code{nil}.
 @end defun
+@end ignore
 
 @node Numerical Functions
 @section Numerical Functions
@@ -3036,6 +3034,7 @@ of @code{cl-truncate}.
 This package also provides an implementation of the Common Lisp
 random number generator.  It uses its own additive-congruential
 algorithm, which is much more likely to give statistically clean
+@c FIXME?  Still true?
 random numbers than the simple generators supplied by many
 operating systems.
 
@@ -3043,22 +3042,16 @@ operating systems.
 This function returns a random nonnegative number less than
 @var{number}, and of the same type (either integer or floating-point).
 The @var{state} argument should be a @code{random-state} object
-which holds the state of the random number generator.  The
+that holds the state of the random number generator.  The
 function modifies this state object as a side effect.  If
-@var{state} is omitted, it defaults to the variable
+@var{state} is omitted, it defaults to the internal variable
 @code{cl--random-state}, which contains a pre-initialized
-@code{random-state} object.
+default @code{random-state} object.  (Since any number of programs in
+the Emacs process may be accessing @code{cl--random-state} in
+interleaved fashion, the sequence generated from this will be
+irreproducible for all intents and purposes.)
 @end defun
 
-@defvar cl--random-state
-This variable contains the system ``default'' @code{random-state}
-object, used for calls to @code{cl-random} that do not specify an
-alternative state object.  Since any number of programs in the
-Emacs process may be accessing @code{cl--random-state} in interleaved
-fashion, the sequence generated from this variable will be
-irreproducible for all intents and purposes.
-@end defvar
-
 @defun cl-make-random-state &optional state
 This function creates or copies a @code{random-state} object.
 If @var{state} is omitted or @code{nil}, it returns a new copy of
@@ -3094,10 +3087,10 @@ This predicate returns @code{t} if @var{object} is a
 @section Implementation Parameters
 
 @noindent
-This package defines several useful constants having to with numbers.
+This package defines several useful constants having to do with
+floating-point numbers.
 
-The following parameters have to do with floating-point numbers.
-This package determines their values by exercising the computer's
+It determines their values by exercising the computer's
 floating-point arithmetic in various ways.  Because this operation
 might be slow, the code for initializing them is kept in a separate
 function that must be called before the parameters can be used.
@@ -3105,12 +3098,13 @@ function that must be called before the parameters can be used.
 @defun cl-float-limits
 This function makes sure that the Common Lisp floating-point parameters
 like @code{cl-most-positive-float} have been initialized.  Until it is
-called, these parameters will be @code{nil}.  If this version of Emacs
-does not support floats, the parameters will remain @code{nil}.  If the
-parameters have already been initialized, the function returns
+called, these parameters will be @code{nil}.
+@c If this version of Emacs does not support floats, the parameters will
+@c remain @code{nil}.
+If the parameters have already been initialized, the function returns
 immediately.
 
-The algorithm makes assumptions that will be valid for most modern
+The algorithm makes assumptions that will be valid for almost all
 machines, but will fail if the machine's arithmetic is extremely
 unusual, e.g., decimal.
 @end defun
@@ -3130,7 +3124,7 @@ is approximately @code{1.79e+308}.
 @end defvar
 
 @defvar cl-most-negative-float
-This constant equals the most-negative value a Lisp float can hold.
+This constant equals the most negative value a Lisp float can hold.
 (It is assumed to be equal to @code{(- cl-most-positive-float)}.)
 @end defvar
 
@@ -3199,7 +3193,7 @@ may appear in any order.
 The @code{:key} argument should be passed either @code{nil}, or a
 function of one argument.  This key function is used as a filter
 through which the elements of the sequence are seen; for example,
-@code{(cl-find x y :key 'car)} is similar to @code{(cl-assoc x y)}:
+@code{(cl-find x y :key 'car)} is similar to @code{(cl-assoc x y)}.
 It searches for an element of the list whose @sc{car} equals
 @code{x}, rather than for an element which equals @code{x} itself.
 If @code{:key} is omitted or @code{nil}, the filter is effectively
@@ -3217,7 +3211,7 @@ true (non-@code{nil}) to indicate a match; instead, you may use
 @code{:test-not} to give a function which returns @emph{false} to
 indicate a match.  The default test function is @code{eql}.
 
-Many functions which take @var{item} and @code{:test} or @code{:test-not}
+Many functions that take @var{item} and @code{:test} or @code{:test-not}
 arguments also come in @code{-if} and @code{-if-not} varieties,
 where a @var{predicate} function is passed instead of @var{item},
 and sequence elements match if the predicate returns true on them
@@ -3231,7 +3225,7 @@ and sequence elements match if the predicate returns true on them
 to remove all zeros from sequence @code{seq}.
 
 Some operations can work on a subsequence of the argument sequence;
-these function take @code{:start} and @code{:end} arguments which
+these function take @code{:start} and @code{:end} arguments, which
 default to zero and the length of the sequence, respectively.
 Only elements between @var{start} (inclusive) and @var{end}
 (exclusive) are affected by the operation.  The @var{end} argument
@@ -3339,7 +3333,7 @@ the return values using @code{nconc}.
 @defun cl-some predicate seq &rest more-seqs
 This function calls @var{predicate} on each element of @var{seq}
 in turn; if @var{predicate} returns a non-@code{nil} value,
-@code{some} returns that value, otherwise it returns @code{nil}.
+@code{cl-some} returns that value, otherwise it returns @code{nil}.
 Given several sequence arguments, it steps through the sequences
 in parallel until the shortest one runs out, just as in
 @code{cl-mapcar}.  You can rely on the left-to-right order in which
@@ -3388,7 +3382,7 @@ of left-associative:
         @equiv{} (- 1 (- 2 (- 3 4))) @result{} -2
 @end example
 
-If @code{:key} is specified, it is a function of one argument which
+If @code{:key} is specified, it is a function of one argument, which
 is called on each of the sequence elements in turn.
 
 If @code{:initial-value} is specified, it is effectively added to the
@@ -3457,7 +3451,7 @@ of data copied is simply the shorter of the source and destination
 If @var{seq1} and @var{seq2} are @code{eq}, then the replacement
 will work correctly even if the regions indicated by the start
 and end arguments overlap.  However, if @var{seq1} and @var{seq2}
-are lists which share storage but are not @code{eq}, and the
+are lists that share storage but are not @code{eq}, and the
 start and end arguments specify overlapping regions, the effect
 is undefined.
 @end defun
@@ -3480,7 +3474,7 @@ if @var{count} was also specified).
 @end defun
 
 @defun cl-delete item seq @t{&key :test :test-not :key :count :start :end :from-end}
-This deletes all elements of @var{seq} which match @var{item}.
+This deletes all elements of @var{seq} that match @var{item}.
 It is a destructive operation.  Since Emacs Lisp does not support
 stretchable strings or vectors, this is the same as @code{cl-remove}
 for those sequence types.  On lists, @code{cl-remove} will copy the
@@ -3580,7 +3574,7 @@ elements match (according to @code{:test}, @code{:test-not},
 and @code{:key}), the function returns @code{nil}.  If there is
 a mismatch, the function returns the index (relative to @var{seq1})
 of the first mismatching element.  This will be the leftmost pair of
-elements which do not match, or the position at which the shorter of
+elements that do not match, or the position at which the shorter of
 the two otherwise-matching sequences runs out.
 
 If @code{:from-end} is true, then the elements are compared from right
@@ -3595,7 +3589,7 @@ which compares two strings case-insensitively.
 @defun cl-search seq1 seq2 @t{&key :test :test-not :key :from-end :start1 :end1 :start2 :end2}
 This function searches @var{seq2} for a subsequence that matches
 @var{seq1} (or part of it specified by @code{:start1} and
-@code{:end1}.)  Only matches which fall entirely within the region
+@code{:end1}).  Only matches that fall entirely within the region
 defined by @code{:start2} and @code{:end2} will be considered.
 The return value is the index of the leftmost element of the
 leftmost match, relative to the start of @var{seq2}, or @code{nil}
@@ -3606,7 +3600,7 @@ function finds the @emph{rightmost} matching subsequence.
 @node Sorting Sequences
 @section Sorting Sequences
 
-@defun clsort seq predicate @t{&key :key}
+@defun cl-sort seq predicate @t{&key :key}
 This function sorts @var{seq} into increasing order as determined
 by using @var{predicate} to compare pairs of elements.  @var{predicate}
 should return true (non-@code{nil}) if and only if its first argument
@@ -3617,7 +3611,7 @@ numbers into decreasing rather than increasing order.
 
 This function differs from Emacs's built-in @code{sort} in that it
 can operate on any type of sequence, not just lists.  Also, it
-accepts a @code{:key} argument which is used to preprocess data
+accepts a @code{:key} argument, which is used to preprocess data
 fed to the @var{predicate} function.  For example,
 
 @example
@@ -3628,7 +3622,7 @@ fed to the @var{predicate} function.  For example,
 sorts @var{data}, a sequence of strings, into increasing alphabetical
 order without regard to case.  A @code{:key} function of @code{car}
 would be useful for sorting association lists.  It should only be a
-simple accessor though, it's used heavily in the current
+simple accessor though, since it's used heavily in the current
 implementation.
 
 The @code{cl-sort} function is destructive; it sorts lists by actually
@@ -3684,7 +3678,7 @@ i.e., chains of cons cells.
 
 @defun cl-caddr x
 This function is equivalent to @code{(car (cdr (cdr @var{x})))}.
-Likewise, this package defines all 28 @code{c@var{xxx}r} functions
+Likewise, this package defines all 24 @code{c@var{xxx}r} functions
 where @var{xxx} is up to four @samp{a}s and/or @samp{d}s.
 All of these functions are @code{setf}-able, and calls to them
 are expanded inline by the byte-compiler for maximum efficiency.
@@ -3712,7 +3706,8 @@ This function returns the length of list @var{x}, exactly like
 @code{(length @var{x})}, except that if @var{x} is a circular
 list (where the @sc{cdr}-chain forms a loop rather than terminating
 with @code{nil}), this function returns @code{nil}.  (The regular
-@code{length} function would get stuck if given a circular list.)
+@code{length} function would get stuck if given a circular list.
+See also the @code{safe-length} function.)
 @end defun
 
 @defun cl-list* arg &rest others
@@ -3740,18 +3735,6 @@ This function returns a copy of the list @var{list}.  It copies
 dotted lists like @code{(1 2 . 3)} correctly.
 @end defun
 
-@defun copy-tree x &optional vecp
-This function returns a copy of the tree of cons cells @var{x}.
-@c FIXME? cl-copy-list is not an alias of copy-sequence.
-Unlike @code{copy-sequence} (and its alias @code{cl-copy-list}),
-which copies only along the @sc{cdr} direction, this function
-copies (recursively) along both the @sc{car} and the @sc{cdr}
-directions.  If @var{x} is not a cons cell, the function simply
-returns @var{x} unchanged.  If the optional @var{vecp} argument
-is true, this function copies vectors (recursively) as well as
-cons cells.
-@end defun
-
 @defun cl-tree-equal x y @t{&key :test :test-not :key}
 This function compares two trees of cons cells.  If @var{x} and
 @var{y} are both cons cells, their @sc{car}s and @sc{cdr}s are
@@ -3814,7 +3797,7 @@ This is a destructive version of @code{cl-sublis}.
 @section Lists as Sets
 
 @noindent
-These functions perform operations on lists which represent sets
+These functions perform operations on lists that represent sets
 of elements.
 
 @defun cl-member item list @t{&key :test :test-not :key}
@@ -3827,13 +3810,14 @@ are compared by @code{eql} by default; you can use the @code{:test},
 
 The standard Emacs lisp function @code{member} uses @code{equal} for
 comparisons; it is equivalent to @code{(cl-member @var{item} @var{list}
-:test 'equal)}.
+:test 'equal)}.  With no keyword arguments, @code{cl-member} is
+equivalent to @code{memq}.
 @end defun
 
 @findex cl-member-if
 @findex cl-member-if-not
 The @code{cl-member-if} and @code{cl-member-if-not} functions
-analogously search for elements which satisfy a given predicate.
+analogously search for elements that satisfy a given predicate.
 
 @defun cl-tailp sublist list
 This function returns @code{t} if @var{sublist} is a sublist of
@@ -3852,11 +3836,11 @@ become part of the list.
 @end defun
 
 @defun cl-union list1 list2 @t{&key :test :test-not :key}
-This function combines two lists which represent sets of items,
+This function combines two lists that represent sets of items,
 returning a list that represents the union of those two sets.
-The result list will contain all items which appear in @var{list1}
+The resulting list contains all items that appear in @var{list1}
 or @var{list2}, and no others.  If an item appears in both
-@var{list1} and @var{list2} it will be copied only once.  If
+@var{list1} and @var{list2} it is copied only once.  If
 an item is duplicated in @var{list1} or @var{list2}, it is
 undefined whether or not that duplication will survive in the
 result list.  The order of elements in the result list is also
@@ -3871,7 +3855,7 @@ it tries to reuse the storage of the argument lists if possible.
 @defun cl-intersection list1 list2 @t{&key :test :test-not :key}
 This function computes the intersection of the sets represented
 by @var{list1} and @var{list2}.  It returns the list of items
-which appear in both @var{list1} and @var{list2}.
+that appear in both @var{list1} and @var{list2}.
 @end defun
 
 @defun cl-nintersection list1 list2 @t{&key :test :test-not :key}
@@ -3921,7 +3905,7 @@ This function searches the association list @var{a-list} for an
 element whose @sc{car} matches (in the sense of @code{:test},
 @code{:test-not}, and @code{:key}, or by comparison with @code{eql})
 a given @var{item}.  It returns the matching element, if any,
-otherwise @code{nil}.  It ignores elements of @var{a-list} which
+otherwise @code{nil}.  It ignores elements of @var{a-list} that
 are not cons cells.  (This corresponds to the behavior of
 @code{assq} and @code{assoc} in Emacs Lisp; Common Lisp's
 @code{assoc} ignores @code{nil}s but considers any other non-cons
@@ -3982,11 +3966,11 @@ are symbols.  For example,
 @end example
 
 @noindent
-defines a struct type called @code{person} which contains three
+defines a struct type called @code{person} that contains three
 slots.  Given a @code{person} object @var{p}, you can access those
 slots by calling @code{(person-name @var{p})}, @code{(person-age @var{p})},
 and @code{(person-sex @var{p})}.  You can also change these slots by
-using @code{setf} on any of these place forms:
+using @code{setf} on any of these place forms, for example:
 
 @example
 (cl-incf (person-age birthday-boy))
@@ -4003,10 +3987,10 @@ Given a @code{person}, @code{(copy-person @var{p})} makes a new
 object of the same type whose slots are @code{eq} to those of @var{p}.
 
 Given any Lisp object @var{x}, @code{(person-p @var{x})} returns
-true if @var{x} looks like a @code{person}, false otherwise.  (Again,
+true if @var{x} looks like a @code{person}, and false otherwise.  (Again,
 in Common Lisp this predicate would be exact; in Emacs Lisp the
 best it can do is verify that @var{x} is a vector of the correct
-length which starts with the correct tag symbol.)
+length that starts with the correct tag symbol.)
 
 Accessors like @code{person-name} normally check their arguments
 (effectively using @code{person-p}) and signal an error if the
@@ -4043,7 +4027,7 @@ In general, @var{name} is either a name symbol or a list of a name
 symbol followed by any number of @dfn{struct options}; each @var{slot}
 is either a slot symbol or a list of the form @samp{(@var{slot-name}
 @var{default-value} @var{slot-options}@dots{})}.  The @var{default-value}
-is a Lisp form which is evaluated any time an instance of the
+is a Lisp form that is evaluated any time an instance of the
 structure type is created without specifying that slot's value.
 
 Common Lisp defines several slot options, but the only one
@@ -4101,11 +4085,11 @@ The argument names should match the slot names; each slot is
 initialized from the corresponding argument.  Slots whose names
 do not appear in the argument list are initialized based on the
 @var{default-value} in their slot descriptor.  Also, @code{&optional}
-and @code{&key} arguments which don't specify defaults take their
+and @code{&key} arguments that don't specify defaults take their
 defaults from the slot descriptor.  It is valid to include arguments
-which don't correspond to slot names; these are useful if they are
+that don't correspond to slot names; these are useful if they are
 referred to in the defaults for optional, keyword, or @code{&aux}
-arguments which @emph{do} correspond to slots.
+arguments that @emph{do} correspond to slots.
 
 You can specify any number of full-format @code{:constructor}
 options on a structure.  The default constructor is still generated
@@ -4146,7 +4130,7 @@ means not to generate a copier function.  (In this implementation,
 all copier functions are simply synonyms for @code{copy-sequence}.)
 
 @item :predicate
-The argument is an alternate name for the predicate which recognizes
+The argument is an alternate name for the predicate that recognizes
 objects of this type.  The default is @code{@var{name}-p}.  @code{nil}
 means not to generate a predicate function.  (If the @code{:type}
 option is used without the @code{:named} option, no predicate is
@@ -4206,7 +4190,7 @@ work on astronauts just like other people.
 
 @item :print-function
 In full Common Lisp, this option allows you to specify a function
-which is called to print an instance of the structure type.  The
+that is called to print an instance of the structure type.  The
 Emacs Lisp system offers no hooks into the Lisp printer which would
 allow for such a feature, so this package simply ignores
 @code{:print-function}.
@@ -4383,7 +4367,7 @@ You can find out how a macro expands by using the
 This function takes a single Lisp form as an argument and inserts
 a nicely formatted copy of it in the current buffer (which must be
 in Lisp mode so that indentation works properly).  It also expands
-all Lisp macros which appear in the form.  The easiest way to use
+all Lisp macros that appear in the form.  The easiest way to use
 this function is to go to the @file{*scratch*} buffer and type, say,
 
 @example
@@ -4392,7 +4376,7 @@ this function is to go to the @file{*scratch*} buffer and type, say,
 
 @noindent
 and type @kbd{C-x C-e} immediately after the closing parenthesis;
-the expansion
+an expansion similar to:
 
 @example
 (cl-block nil
@@ -4413,7 +4397,11 @@ variable @code{G1004} was created by @code{cl-gensym}.)
 If the optional argument @var{full} is true, then @emph{all}
 macros are expanded, including @code{cl-block}, @code{cl-eval-when},
 and compiler macros.  Expansion is done as if @var{form} were
-a top-level form in a file being compiled.  For example,
+a top-level form in a file being compiled.
+
+@c FIXME none of these examples are still applicable.
+@ignore
+For example,
 
 @example
 (cl-prettyexpand '(cl-pushnew 'x list))
@@ -4423,16 +4411,12 @@ a top-level form in a file being compiled.  For example,
 (cl-prettyexpand '(caddr (cl-member 'a list)) t)
      @print{} (car (cdr (cdr (memq 'a list))))
 @end example
+@end ignore
 
 Note that @code{cl-adjoin}, @code{cl-caddr}, and @code{cl-member} all
 have built-in compiler macros to optimize them in common cases.
 @end defun
 
-@ifinfo
-@example
-
-@end example
-@end ifinfo
 @appendixsec Error Checking
 
 @noindent
@@ -4442,7 +4426,7 @@ where substantial gains were possible at the expense of marginal
 incompatibility.
 
 The Common Lisp standard (as embodied in Steele's book) uses the
-phrase ``it is an error if'' to indicate a situation which is not
+phrase ``it is an error if'' to indicate a situation that is not
 supposed to arise in complying programs; implementations are strongly
 encouraged but not required to signal an error in these situations.
 This package sometimes omits such error checking in the interest of
@@ -4464,46 +4448,36 @@ you can use @code{&allow-other-keys} to omit this check.  Functions
 defined in this package such as @code{cl-find} and @code{cl-member}
 do check their keyword arguments for validity.
 
-@ifinfo
-@example
-
-@end example
-@end ifinfo
-@appendixsec Optimizing Compiler
+@appendixsec Compiler Optimizations
 
 @noindent
-Use of the optimizing Emacs compiler is highly recommended; many of the Common
+Changing the value of @code{byte-optimize} from the default @code{t}
+is highly discouraged; many of the Common
 Lisp macros emit
-code which can be improved by optimization.  In particular,
+code that can be improved by optimization.  In particular,
 @code{cl-block}s (whether explicit or implicit in constructs like
 @code{cl-defun} and @code{cl-loop}) carry a fair run-time penalty; the
-optimizing compiler removes @code{cl-block}s which are not actually
+byte-compiler removes @code{cl-block}s that are not actually
 referenced by @code{cl-return} or @code{cl-return-from} inside the block.
 
 @node Common Lisp Compatibility
 @appendix Common Lisp Compatibility
 
 @noindent
-Following is a list of all known incompatibilities between this
+The following is a list of all known incompatibilities between this
 package and Common Lisp as documented in Steele (2nd edition).
 
 The word @code{cl-defun} is required instead of @code{defun} in order
 to use extended Common Lisp argument lists in a function.  Likewise,
 @code{cl-defmacro} and @code{cl-function} are versions of those forms
 which understand full-featured argument lists.  The @code{&whole}
-keyword does not work in @code{defmacro} argument lists (except
+keyword does not work in @code{cl-defmacro} argument lists (except
 inside recursive argument lists).
 
 The @code{equal} predicate does not distinguish
 between IEEE floating-point plus and minus zero.  The @code{cl-equalp}
 predicate has several differences with Common Lisp; @pxref{Predicates}.
 
-@c FIXME no longer provided by cl.
-The @code{setf} mechanism is entirely compatible, except that
-setf-methods return a list of five values rather than five
-values directly.  Also, the new ``@code{setf} function'' concept
-(typified by @code{(defun (setf foo) @dots{})}) is not implemented.
-
 The @code{cl-do-all-symbols} form is the same as @code{cl-do-symbols}
 with no @var{obarray} argument.  In Common Lisp, this form would
 iterate over all symbols in all packages.  Since Emacs obarrays
@@ -4635,7 +4609,7 @@ However, the Emacs parser does not understand colons and just
 treats them as part of the symbol name.  Thus, while @code{mapcar}
 and @code{lisp:mapcar} may refer to the same symbol in Common
 Lisp, they are totally distinct in Emacs Lisp.  Common Lisp
-programs which refer to a symbol by the full name sometimes
+programs that refer to a symbol by the full name sometimes
 and the short name other times will not port cleanly to Emacs.
 
 Emacs Lisp does have a concept of ``obarrays'', which are
@@ -4923,13 +4897,16 @@ Common Lisp defines three macros, @code{define-modify-macro},
 user to extend generalized variables in various ways.
 In Emacs, these are obsolete, replaced by various features of
 @file{gv.el} in Emacs 24.3.
-@c FIXME details.
+@xref{Adding Generalized Variables,,,elisp,GNU Emacs Lisp Reference Manual}.
+
 
 @defmac define-modify-macro name arglist function [doc-string]
 This macro defines a ``read-modify-write'' macro similar to
-@code{cl-incf} and @code{cl-decf}.  The macro @var{name} is defined
-to take a @var{place} argument followed by additional arguments
-described by @var{arglist}.  The call
+@code{cl-incf} and @code{cl-decf}.  You can replace this macro
+with @code{gv-letplace}.
+
+The macro @var{name} is defined to take a @var{place} argument
+followed by additional arguments described by @var{arglist}.  The call
 
 @example
 (@var{name} @var{place} @var{args}@dots{})
@@ -4952,8 +4929,8 @@ which in turn is roughly equivalent to
 For example:
 
 @example
-(define-modify-macro cl-incf (&optional (n 1)) +)
-(define-modify-macro cl-concatf (&rest args) concat)
+(define-modify-macro incf (&optional (n 1)) +)
+(define-modify-macro concatf (&rest args) concat)
 @end example
 
 Note that @code{&key} is not allowed in @var{arglist}, but
@@ -4962,16 +4939,31 @@ Note that @code{&key} is not allowed in @var{arglist}, but
 Most of the modify macros defined by Common Lisp do not exactly
 follow the pattern of @code{define-modify-macro}.  For example,
 @code{push} takes its arguments in the wrong order, and @code{pop}
-is completely irregular.  You can define these macros ``by hand''
-using @code{get-setf-method}, or consult the source
-to see how to use the internal @code{setf} building blocks.
+is completely irregular.
+
+The above @code{incf} example could be written using
+@code{gv-letplace} as:
+@example
+(defmacro incf (place &optional n)
+  (gv-letplace (getter setter) place
+    (macroexp-let2 nil v (or n 1)
+      (funcall setter `(+ ,v ,getter)))))
+@end example
+@ignore
+(defmacro concatf (place &rest args)
+  (gv-letplace (getter setter) place
+    (macroexp-let2 nil v (mapconcat 'identity args "")
+      (funcall setter `(concat ,getter ,v)))))
+@end ignore
 @end defmac
 
 @defmac defsetf access-fn update-fn
-This is the simpler of two @code{defsetf} forms.  Where
-@var{access-fn} is the name of a function which accesses a place,
-this declares @var{update-fn} to be the corresponding store
-function.  From now on,
+This is the simpler of two @code{defsetf} forms, and is
+replaced by @code{gv-define-simple-setter}.
+
+With @var{access-fn} the name of a function that accesses a place,
+this declares @var{update-fn} to be the corresponding store function.
+From now on,
 
 @example
 (setf (@var{access-fn} @var{arg1} @var{arg2} @var{arg3}) @var{value})
@@ -4986,13 +4978,13 @@ will be expanded to
 
 @noindent
 The @var{update-fn} is required to be either a true function, or
-a macro which evaluates its arguments in a function-like way.  Also,
+a macro that evaluates its arguments in a function-like way.  Also,
 the @var{update-fn} is expected to return @var{value} as its result.
 Otherwise, the above expansion would not obey the rules for the way
 @code{setf} is supposed to behave.
 
 As a special (non-Common-Lisp) extension, a third argument of @code{t}
-to @code{defsetf} says that the @code{update-fn}'s return value is
+to @code{defsetf} says that the return value of @code{update-fn} is
 not suitable, so that the above @code{setf} should be expanded to
 something more like
 
@@ -5002,25 +4994,32 @@ something more like
   temp)
 @end example
 
-Some examples of the use of @code{defsetf}, drawn from the standard
-suite of setf methods, are:
+Some examples are:
 
 @example
 (defsetf car setcar)
-(defsetf symbol-value set)
 (defsetf buffer-name rename-buffer t)
 @end example
+
+These translate directly to @code{gv-define-simple-setter}:
+
+@example
+(gv-define-simple-setter car setcar)
+(gv-define-simple-setter buffer-name rename-buffer t)
+@end example
 @end defmac
 
 @defmac defsetf access-fn arglist (store-var) forms@dots{}
-This is the second, more complex, form of @code{defsetf}.  It is
-rather like @code{defmacro} except for the additional @var{store-var}
-argument.  The @var{forms} should return a Lisp form which stores
-the value of @var{store-var} into the generalized variable formed
-by a call to @var{access-fn} with arguments described by @var{arglist}.
-The @var{forms} may begin with a string which documents the @code{setf}
-method (analogous to the doc string that appears at the front of a
-function).
+This is the second, more complex, form of @code{defsetf}.
+It can be replaced by @code{gv-define-setter}.
+
+This form of @code{defsetf} is rather like @code{defmacro} except for
+the additional @var{store-var} argument.  The @var{forms} should
+return a Lisp form that stores the value of @var{store-var} into the
+generalized variable formed by a call to @var{access-fn} with
+arguments described by @var{arglist}.  The @var{forms} may begin with
+a string which documents the @code{setf} method (analogous to the doc
+string that appears at the front of a function).
 
 For example, the simple form of @code{defsetf} is shorthand for
 
@@ -5031,23 +5030,32 @@ For example, the simple form of @code{defsetf} is shorthand for
 
 The Lisp form that is returned can access the arguments from
 @var{arglist} and @var{store-var} in an unrestricted fashion;
-macros like @code{setf} and @code{cl-incf} which invoke this
+macros like @code{cl-incf} that invoke this
 setf-method will insert temporary variables as needed to make
 sure the apparent order of evaluation is preserved.
 
-Another example drawn from the standard package:
+Another standard example:
 
 @example
 (defsetf nth (n x) (store)
-  (list 'setcar (list 'nthcdr n x) store))
+  `(setcar (nthcdr ,n ,x) ,store))
+@end example
+
+You could write this using @code{gv-define-setter} as:
+
+@example
+(gv-define-setter nth (store n x)
+  `(setcar (nthcdr ,n ,x) ,store))
 @end example
 @end defmac
 
 @defmac define-setf-method access-fn arglist forms@dots{}
-This is the most general way to create new place forms.  When
-a @code{setf} to @var{access-fn} with arguments described by
-@var{arglist} is expanded, the @var{forms} are evaluated and
-must return a list of five items:
+This is the most general way to create new place forms.  You can
+replace this by @code{gv-define-setter} or @code{gv-define-expander}.
+
+When a @code{setf} to @var{access-fn} with arguments described by
+@var{arglist} is expanded, the @var{forms} are evaluated and must
+return a list of five items:
 
 @enumerate
 @item
@@ -5063,12 +5071,12 @@ A list of exactly one @dfn{store variable} (generally obtained
 from a call to @code{gensym}).
 
 @item
-A Lisp form which stores the contents of the store variable into
+A Lisp form that stores the contents of the store variable into
 the generalized variable, assuming the temporaries have been
 bound as described above.
 
 @item
-A Lisp form which accesses the contents of the generalized variable,
+A Lisp form that accesses the contents of the generalized variable,
 assuming the temporaries have been bound.
 @end enumerate
 
@@ -5076,6 +5084,9 @@ This is exactly like the Common Lisp macro of the same name,
 except that the method returns a list of five values rather
 than the five values themselves, since Emacs Lisp does not
 support Common Lisp's notion of multiple return values.
+(Note that the @code{setf} implementation provided by @file{gv.el}
+does not use this five item format.  Its use here is only for
+backwards compatibility.)
 
 Once again, the @var{forms} may begin with a documentation string.
 
@@ -5084,47 +5095,29 @@ temporary variables.  In the setf-methods generated by
 @code{defsetf}, the second return value is simply the list of
 arguments in the place form, and the first return value is a
 list of a corresponding number of temporary variables generated
-by @code{cl-gensym}.  Macros like @code{setf} and @code{cl-incf} which
+@c FIXME I don't think this is true anymore.
+by @code{cl-gensym}.  Macros like @code{cl-incf} that
 use this setf-method will optimize away most temporaries that
 turn out to be unnecessary, so there is little reason for the
 setf-method itself to optimize.
 @end defmac
 
+@c Removed in Emacs 24.3, not possible to make a compatible replacement.
+@ignore
 @defun get-setf-method place &optional env
 This function returns the setf-method for @var{place}, by
 invoking the definition previously recorded by @code{defsetf}
 or @code{define-setf-method}.  The result is a list of five
 values as described above.  You can use this function to build
-your own @code{cl-incf}-like modify macros.  (Actually, it is
-@c FIXME?
-better to use the internal functions @code{cl-setf-do-modify}
-and @code{cl-setf-do-store}, which are a bit easier to use and
-which also do a number of optimizations; consult the source
-code for the @code{cl-incf} function for a simple example.)
+your own @code{cl-incf}-like modify macros.
 
 The argument @var{env} specifies the ``environment'' to be
 passed on to @code{macroexpand} if @code{get-setf-method} should
 need to expand a macro in @var{place}.  It should come from
 an @code{&environment} argument to the macro or setf-method
 that called @code{get-setf-method}.
-
-See also the source code for the setf-method for
-@c Also @code{apply}, but that is commented out.
-@code{substring}, which works by calling @code{get-setf-method} on a
-simpler case, then massaging the result.
 @end defun
-
-Modern Common Lisp defines a second, independent way to specify
-the @code{setf} behavior of a function, namely ``@code{setf}
-functions'' whose names are lists @code{(setf @var{name})}
-rather than symbols.  For example, @code{(defun (setf foo) @dots{})}
-defines the function that is used when @code{setf} is applied to
-@code{foo}.  This package does not currently support @code{setf}
-functions.  In particular, it is a compile-time error to use
-@code{setf} on a form which has not already been @code{defsetf}'d
-or otherwise declared; in newer Common Lisps, this would not be
-an error since the function @code{(setf @var{func})} might be
-defined later.
+@end ignore
 
 
 @node GNU Free Documentation License
diff --git a/doc/misc/flymake.texi b/doc/misc/flymake.texi
index 28fb7864f06..4a873490e86 100644
--- a/doc/misc/flymake.texi
+++ b/doc/misc/flymake.texi
@@ -337,6 +337,17 @@ been reported.
 A custom face for highlighting lines for which at least one warning
 and no errors have been reported.
 
+@item flymake-error-bitmap
+A bitmap used in the fringe to mark lines for which an error has
+been reported.
+
+@item flymake-warning-bitmap
+A bitmap used in the fringe to mark lines for which a warning has
+been reported.
+
+@item flymake-fringe-indicator-position
+Which fringe (if any) should show the warning/error bitmaps.
+
 @end table
 
 @node Adding support for a new syntax check tool
@@ -718,6 +729,15 @@ are used: @code{flymake-errline} and
 @code{flymake-warnline}.  Errors belonging outside the current
 buffer are considered to belong to line 1 of the current buffer.
 
+@c This manual does not use vindex.
+@c @vindex flymake-fringe-indicator-position
+@c @vindex flymake-error-bitmap
+@c @vindex flymake-warning-bitmap
+If the option @code{flymake-fringe-indicator-position} is non-@code{nil},
+errors and warnings are also highlighted in the left or right fringe,
+using the bitmaps specified by @code{flymake-error-bitmap}
+and @code{flymake-warning-bitmap}.
+
 @node Interaction with other modes
 @section Interaction with other modes
 @cindex Interaction with other modes
diff --git a/doc/misc/gnus.texi b/doc/misc/gnus.texi
index a9cd0d3567c..47ff355d946 100644
--- a/doc/misc/gnus.texi
+++ b/doc/misc/gnus.texi
@@ -14759,20 +14759,37 @@ This can be either the symbol @code{password} or the symbol @code{apop}
 and says what authentication scheme to use.  The default is
 @code{password}.
 
+@item :leave
+Non-@code{nil} if the mail is to be left on the @acronym{POP} server
+after fetching.  Mails once fetched will never be fetched again by the
+@acronym{UIDL} control.  Only the built-in @code{pop3-movemail} program
+(the default) supports this keyword.
+
+If this is neither @code{nil} nor a number, all mails will be left on
+the server.  If this is a number, leave mails on the server for this
+many days since you first checked new mails.  If this is @code{nil}
+(the default), mails will be deleted on the server right after fetching.
+
+@vindex pop3-uidl-file
+The @code{pop3-uidl-file} variable specifies the file to which the
+@acronym{UIDL} data are locally stored.  The default value is
+@file{~/.pop3-uidl}.
+
+Note that @acronym{POP} servers maintain no state information between
+sessions, so what the client believes is there and what is actually
+there may not match up.  If they do not, then you may get duplicate
+mails or the whole thing can fall apart and leave you with a corrupt
+mailbox.
+
 @end table
 
-@vindex pop3-movemail
+@findex pop3-movemail
 @vindex pop3-leave-mail-on-server
 If the @code{:program} and @code{:function} keywords aren't specified,
-@code{pop3-movemail} will be used.  If @code{pop3-leave-mail-on-server}
-is non-@code{nil} the mail is to be left on the @acronym{POP} server
-after fetching when using @code{pop3-movemail}.  Note that POP servers
-maintain no state information between sessions, so what the client
-believes is there and what is actually there may not match up.  If they
-do not, then you may get duplicate mails or the whole thing can fall
-apart and leave you with a corrupt mailbox.
+@code{pop3-movemail} will be used.
 
 Here are some examples for getting mail from a @acronym{POP} server.
+
 Fetch from the default @acronym{POP} server, using the default user
 name, and default fetcher:
 
@@ -14787,6 +14804,14 @@ Fetch from a named server with a named user and password:
      :user "user-name" :password "secret")
 @end lisp
 
+Leave mails on the server for 14 days:
+
+@lisp
+(pop :server "my.pop.server"
+     :user "user-name" :password "secret"
+     :leave 14)
+@end lisp
+
 Use @samp{movemail} to move the mail:
 
 @lisp
diff --git a/doc/misc/ses.texi b/doc/misc/ses.texi
index a70bb9c407e..5de87a2f1c7 100644
--- a/doc/misc/ses.texi
+++ b/doc/misc/ses.texi
@@ -1,7 +1,7 @@
 \input texinfo   @c -*-texinfo-*-
 @c %**start of header
 @setfilename ../../info/ses
-@settitle SES: Simple Emacs Spreadsheet
+@settitle @acronym{SES}: Simple Emacs Spreadsheet
 @setchapternewpage off
 @syncodeindex fn cp
 @syncodeindex vr cp
@@ -9,7 +9,7 @@
 @c %**end of header
 
 @copying
-This file documents SES: the Simple Emacs Spreadsheet.
+This file documents @acronym{SES}: the Simple Emacs Spreadsheet.
 
 Copyright @copyright{} 2002-2012 Free Software Foundation, Inc.
 
@@ -29,13 +29,13 @@ developing GNU and promoting software freedom.''
 
 @dircategory Emacs misc features
 @direntry
-* SES: (ses).                   Simple Emacs Spreadsheet.
+* @acronym{SES}: (ses).                   Simple Emacs Spreadsheet.
 @end direntry
 
 @finalout
 
 @titlepage
-@title SES
+@title @acronym{SES}
 @subtitle Simple Emacs Spreadsheet
 @author Jonathan A. Yavner
 @author @email{jyavner@@member.fsf.org}
@@ -52,10 +52,10 @@ developing GNU and promoting software freedom.''
 @ifnottex
 @node Top, Sales Pitch, (dir), (dir)
 @comment  node-name,  next,  previous,  up
-@top SES: Simple Emacs Spreadsheet
+@top @acronym{SES}: Simple Emacs Spreadsheet
 
 @display
-SES is a major mode for GNU Emacs to edit spreadsheet files, which
+@acronym{SES} is a major mode for GNU Emacs to edit spreadsheet files, which
 contain a rectangular grid of cells.  The cells' values are specified
 by formulas that can refer to the values of other cells.
 @end display
@@ -66,7 +66,7 @@ To report bugs, send email to @email{jyavner@@member.fsf.org}.
 @insertcopying
 
 @menu
-* Sales Pitch::                 Why use SES?
+* Sales Pitch::                 Why use @acronym{SES}?
 * The Basics::                  Basic spreadsheet commands
 * Advanced Features::           Want to know more?
 * For Gurus::                   Want to know @emph{even more}?
@@ -126,9 +126,9 @@ Moves point to cell, specified by identifier (@code{ses-jump}).
 
 Point is always at the left edge of a cell, or at the empty endline.
 When mark is inactive, the current cell is underlined.  When mark is
-active, the range is the highlighted rectangle of cells (SES always
+active, the range is the highlighted rectangle of cells (@acronym{SES} always
 uses transient mark mode).  Drag the mouse from A1 to A3 to create the
-range A1-A2.  Many SES commands operate only on single cells, not
+range A1-A2.  Many @acronym{SES} commands operate only on single cells, not
 ranges.
 
 @table @kbd
@@ -155,7 +155,7 @@ Highlight all cells (@code{mark-whole-buffer}).
 * Printer functions::
 * Clearing cells::
 * Copy/cut/paste::
-* Customizing SES::
+* Customizing @acronym{SES}::
 @end menu
 
 @node Formulas, Resizing, The Basics, The Basics
@@ -192,7 +192,7 @@ this cell's formula will be reevaluated.  While typing in the
 expression, you can use @kbd{M-@key{TAB}} to complete symbol names.
 
 @item ' @r{(apostrophe)}
-Enter a symbol (ses-read-symbol).  SES remembers all symbols that have
+Enter a symbol (ses-read-symbol).  @acronym{SES} remembers all symbols that have
 been used as formulas, so you can type just the beginning of a symbol
 and use @kbd{@key{SPC}}, @kbd{@key{TAB}}, and @kbd{?} to complete it.
 @end table
@@ -349,7 +349,7 @@ Clear cell and move right (@code{ses-clear-cell-forward}).
 @end table
 
 
-@node Copy/cut/paste, Customizing SES, Clearing cells, The Basics
+@node Copy/cut/paste, Customizing @acronym{SES}, Clearing cells, The Basics
 @section Copy, cut, and paste
 @cindex copy
 @cindex cut
@@ -365,7 +365,7 @@ Clear cell and move right (@code{ses-clear-cell-forward}).
 @findex ses-yank-pop
 
 The copy functions work on rectangular regions of cells.  You can paste the
-copies into non-SES buffers to export the print text.
+copies into non-@acronym{SES} buffers to export the print text.
 
 @table @kbd
 @item M-w
@@ -394,7 +394,7 @@ Paste from kill ring (@code{yank}).  The paste functions behave
 differently depending on the format of the text being inserted:
 @itemize @bullet
 @item
-When pasting cells that were cut from a SES buffer, the print text is
+When pasting cells that were cut from a @acronym{SES} buffer, the print text is
 ignored and only the attached formula and printer are inserted; cell
 references in the formula are relocated unless you use @kbd{C-u}.
 @item
@@ -402,7 +402,7 @@ The pasted text overwrites a rectangle of cells whose top left corner
 is the current cell.  If part of the rectangle is beyond the edges of
 the spreadsheet, you must confirm the increase in spreadsheet size.
 @item
-Non-SES text is usually inserted as a replacement formula for the
+Non-@acronym{SES} text is usually inserted as a replacement formula for the
 current cell.  If the formula would be a symbol, it's treated as a
 string unless you use @kbd{C-u}.  Pasted formulas with syntax errors
 are always treated as strings.
@@ -420,12 +420,12 @@ Set point and paste from secondary clipboard (@code{mouse-yank-secondary}).
 @item M-y
 Immediately after a paste, you can replace the text with a preceding
 element from the kill ring (@code{ses-yank-pop}).  Unlike the standard
-Emacs yank-pop, the SES version uses @code{undo} to delete the old
+Emacs yank-pop, the @acronym{SES} version uses @code{undo} to delete the old
 yank.  This doesn't make any difference?
 @end table
 
-@node Customizing SES,  , Copy/cut/paste, The Basics
-@section Customizing SES
+@node Customizing @acronym{SES},  , Copy/cut/paste, The Basics
+@section Customizing @acronym{SES}
 @cindex customizing
 @vindex enable-local-eval
 @vindex ses-mode-hook
@@ -443,7 +443,7 @@ up or down.  For diagonal movement, select two functions from the
 list.
 
 @code{ses-mode-hook} is a normal mode hook (list of functions to
-execute when starting SES mode for a buffer).
+execute when starting @acronym{SES} mode for a buffer).
 
 The variable @code{safe-functions} is a list of possibly-unsafe
 functions to be treated as safe when analyzing formulas and printers.
@@ -469,7 +469,10 @@ safety belts!
 
 @table @kbd
 @item C-c M-C-h
-(@code{ses-set-header-row}).  The header line at the top of the SES
+(@code{ses-set-header-row}).
+@findex ses-set-header-row
+@kindex C-c M-C-h
+The header line at the top of the @acronym{SES}
 window normally shows the column letter for each column.  You can set
 it to show a copy of some row, such as a row of column titles, so that
 row will always be visible.  Default is to set the current row as the
@@ -478,6 +481,16 @@ show column letters again.
 @item [header-line mouse-3]
 Pops up a menu to set the current row as the header, or revert to
 column letters.
+@item M-x ses-rename-cell
+@findex ses-rename-cell 
+Rename a cell from a standard A1-like name to any 
+string. 
+@item M-x ses-repair-cell-reference-all
+@findex ses-repair-cell-reference-all
+When you interrupt a cell formula update by clicking @kbd{C-g}, then
+the cell reference link may be broken, which will jeopardize automatic
+cell update when any other cell on which it depends is changed. To
+repair that use function @code{ses-repair-cell-reference-all}
 @end table
 
 @menu
@@ -498,9 +511,9 @@ column letters.
 @findex ses-renarrow-buffer
 @findex ses-reprint-all
 
-A SES file consists of a print area and a data area.  Normally the
+A @acronym{SES} file consists of a print area and a data area.  Normally the
 buffer is narrowed to show only the print area.  The print area is
-read-only except for special SES commands; it contains cell values
+read-only except for special @acronym{SES} commands; it contains cell values
 formatted by printer functions.  The data area records the formula and
 printer functions, etc.
 
@@ -576,6 +589,52 @@ If you insert a new row just beyond the end of a one-column range, or
 a new column just beyond a one-row range, the new cell is included in
 the range.  New cells inserted just before a range are not included.
 
+Flags can be added to @code{ses-range} immediately after the @var{to}
+cell.
+@table @code
+@item !
+Empty cells in range can be removed by adding the @code{!} flag. An
+empty cell is a cell the value of which is one of symbols @code{nil}
+or @code{*skip*}. For instance @code{(ses-range A1 A4 !)} will do the
+same as @code{(list A1 A3)} when cells @code{A2} and @code{A4} are
+empty.
+@item _
+Empty cell values are replaced by the argument following flag
+@code{_}, or @code{0} when flag @code{_} is last in argument list. For
+instance @code{(ses-range A1 A4 _ "empty")} will do the same as
+@code{(list A1 "empty" A3 "empty")} when cells @code{A2} and @code{A4}
+are empty. Similarly, @code{(ses-range A1 A4 _ )} will do the same as
+@code{(list A1 0 A3 0)}.
+@item >v
+When order matters, list cells by reading cells rowwise from top left
+to bottom right. This flag is provided for completeness only as it is
+the default reading order.
+@item <v
+List cells by reading cells rowwise from top right to bottom left.
+@item v>
+List cells by reading cells columnwise from top left to bottom right.
+@item v<
+List cells by reading cells columnwise from top right to bottom left.
+@item v
+A short hand for @code{v>}.
+@item ^
+A short hand for @code{^>}.
+@item >
+A short hand for @code{>v}.
+@item <
+A short hand for @code{>^}.
+@item *
+Instead of listing cells, it makes a Calc vector or matrix of it
+(@pxref{Top,,,calc,GNU Emacs Calc Manual}). If the range contains only
+one row or one column a vector is made, otherwise a matrix is made.
+@item *2
+Same as @code{*} except that a matrix is always made even when there
+is only one row or column in the range.
+@item *1
+Same as @code{*} except that a vector is always made even when there
+is only one row or column in the range, that is to say the
+corresponding matrix is flattened.
+@end table
 
 @node Sorting by column, Standard formula functions, Ranges in formulas, Advanced Features
 @section Sorting by column
@@ -653,7 +712,7 @@ the result is too wide for the available space (up to the end of the
 row or the next non-@code{nil} cell), the result is truncated if the cell's
 value is a string, or replaced with hash marks otherwise.
 
-SES could get confused by printer results that contain newlines or
+@acronym{SES} could get confused by printer results that contain newlines or
 tabs, so these are replaced with question marks.
 
 @table @kbd
@@ -734,7 +793,7 @@ for more info on how Lisp forms are classified as safe or unsafe.
 A common organization for spreadsheets is to have a bunch of ``detail''
 rows, each perhaps describing a transaction, and then a set of
 ``summary'' rows that each show reduced data for some subset of the
-details.  SES supports this organization via the @code{ses-select}
+details.  @acronym{SES} supports this organization via the @code{ses-select}
 function.
 
 @table @code
@@ -771,7 +830,7 @@ details-and-summary spreadsheet.
 * Nonrelocatable references::
 * The data area::
 * Buffer-local variables in spreadsheets::
-* Uses of defadvice in SES::
+* Uses of defadvice in @acronym{SES}::
 @end menu
 
 @node Deferred updates, Nonrelocatable references, For Gurus, For Gurus
@@ -799,7 +858,7 @@ progress message of the form ``Writing... (@var{nnn} cells left)''.
 These deferred cell-writes cannot be interrupted by @kbd{C-g}, so
 you'll just have to wait.
 
-SES uses @code{run-with-idle-timer} to move the cell underline when
+@acronym{SES} uses @code{run-with-idle-timer} to move the cell underline when
 Emacs will be scrolling the buffer after the end of a command, and
 also to narrow and underline after @kbd{C-x C-v}.  This is visible as
 a momentary glitch after C-x C-v and certain scrolling commands.  You
@@ -843,14 +902,14 @@ Begins with an 014 character, followed by sets of cell-definition
 macros for each row, followed by column-widths, column-printers,
 default-printer, and header-row.  Then there's the global parameters
 (file-format ID, numrows, numcols) and the local variables (specifying
-SES mode for the buffer, etc.)
+@acronym{SES} mode for the buffer, etc.)
 
-When a SES file is loaded, first the numrows and numcols values are
+When a @acronym{SES} file is loaded, first the numrows and numcols values are
 loaded, then the entire data area is @code{eval}ed, and finally the local
 variables are processed.
 
 You can edit the data area, but don't insert or delete any newlines
-except in the local-variables part, since SES locates things by
+except in the local-variables part, since @acronym{SES} locates things by
 counting newlines.  Use @kbd{C-x C-e} at the end of a line to install
 your edits into the spreadsheet data structures (this does not update
 the print area, use e.g. @kbd{C-c C-l} for that).
@@ -866,7 +925,7 @@ data structures:
 @end table
 
 
-@node Buffer-local variables in spreadsheets, Uses of defadvice in SES, The data area, For Gurus
+@node Buffer-local variables in spreadsheets, Uses of defadvice in @acronym{SES}, The data area, For Gurus
 @section Buffer-local variables in spreadsheets
 @cindex buffer-local variables
 @cindex variables, buffer-local
@@ -900,8 +959,8 @@ avoid virus warnings, each function used in a formula needs
 (put 'your-function-name 'safe-function t)
 @end lisp
 
-@node Uses of defadvice in SES,  , Buffer-local variables in spreadsheets, For Gurus
-@section Uses of defadvice in SES
+@node Uses of defadvice in @acronym{SES},  , Buffer-local variables in spreadsheets, For Gurus
+@section Uses of defadvice in @acronym{SES}
 @cindex defadvice
 @cindex undo-more
 @cindex copy-region-as-kill
diff --git a/doc/misc/texinfo.tex b/doc/misc/texinfo.tex
index f3093d0853f..b5f31415771 100644
--- a/doc/misc/texinfo.tex
+++ b/doc/misc/texinfo.tex
@@ -3,7 +3,7 @@
 % Load plain if necessary, i.e., if running under initex.
 \expandafter\ifx\csname fmtname\endcsname\relax\input plain\fi
 %
-\def\texinfoversion{2012-09-12.16}
+\def\texinfoversion{2012-11-08.11}
 %
 % Copyright 1985, 1986, 1988, 1990, 1991, 1992, 1993, 1994, 1995,
 % 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006,
@@ -6559,16 +6559,9 @@ end
 \makedispenvdef{quotation}{\quotationstart}
 %
 \def\quotationstart{%
-  {\parskip=0pt \aboveenvbreak}% because \aboveenvbreak inserts \parskip
-  \parindent=0pt
-  %
-  % @cartouche defines \nonarrowing to inhibit narrowing at next level down.
+  \indentedblockstart % same as \indentedblock, but increase right margin too.
   \ifx\nonarrowing\relax
-    \advance\leftskip by \lispnarrowing
     \advance\rightskip by \lispnarrowing
-    \exdentamount = \lispnarrowing
-  \else
-    \let\nonarrowing = \relax
   \fi
   \parsearg\quotationlabel
 }
@@ -6594,6 +6587,32 @@ end
   \fi
 }
 
+% @indentedblock is like @quotation, but indents only on the left and
+% has no optional argument.
+% 
+\makedispenvdef{indentedblock}{\indentedblockstart}
+%
+\def\indentedblockstart{%
+  {\parskip=0pt \aboveenvbreak}% because \aboveenvbreak inserts \parskip
+  \parindent=0pt
+  %
+  % @cartouche defines \nonarrowing to inhibit narrowing at next level down.
+  \ifx\nonarrowing\relax
+    \advance\leftskip by \lispnarrowing
+    \exdentamount = \lispnarrowing
+  \else
+    \let\nonarrowing = \relax
+  \fi
+}
+
+% Keep a nonzero parskip for the environment, since we're doing normal filling.
+%
+\def\Eindentedblock{%
+  \par
+  {\parskip=0pt \afterenvbreak}%
+}
+\def\Esmallindentedblock{\Eindentedblock}
+
 
 % LaTeX-like @verbatim...@end verbatim and @verb{<char>...<char>}
 % If we want to allow any <char> as delimiter,
diff --git a/doc/misc/url.texi b/doc/misc/url.texi
index 898a9994a86..fdb3ab452f2 100644
--- a/doc/misc/url.texi
+++ b/doc/misc/url.texi
@@ -18,7 +18,7 @@
 @end direntry
 
 @copying
-This file documents the Emacs Lisp URL loading package.
+This is the manual for the @code{url} Emacs Lisp library.
 
 Copyright @copyright{} 1993-1999, 2002, 2004-2012 Free Software Foundation, Inc.
 
@@ -57,10 +57,10 @@ developing GNU and promoting software freedom.''
 @end ifnottex
 
 @menu
-* Getting Started::             Preparing your program to use URLs.
+* Introduction::                About the @code{url} library.
+* URI Parsing::                 Parsing (and unparsing) URIs.
 * Retrieving URLs::             How to use this package to retrieve a URL.
 * Supported URL Types::         Descriptions of URL types currently supported.
-* Defining New URLs::           How to define a URL loader for a new protocol.
 * General Facilities::          URLs can be cached, accessed via a gateway
                                 and tracked in a history list.
 * Customization::               Variables you can alter.
@@ -70,93 +70,129 @@ developing GNU and promoting software freedom.''
 * Concept Index::
 @end menu
 
-@node Getting Started
-@chapter Getting Started
-@cindex URLs, definition
-@cindex URIs
+@node Introduction
+@chapter Introduction
+@cindex URL
+@cindex URI
+@cindex uniform resource identifier
+@cindex uniform resource locator
 
-@dfn{Uniform Resource Locators} (URLs) are a specific form of
-@dfn{Uniform Resource Identifiers} (URI) described in RFC 2396 which
-updates RFC 1738 and RFC 1808.  RFC 2016 defines uniform resource
-agents.
+A @dfn{Uniform Resource Identifier} (URI) is a specially-formatted
+name, such as an Internet address, that identifies some name or
+resource.  The format of URIs is described in RFC 3986, which updates
+and replaces the earlier RFCs 2732, 2396, 1808, and 1738.  A
+@dfn{Uniform Resource Locator} (URL) is an older but still-common
+term, which basically refers to a URI corresponding to a resource that
+can be accessed (usually over a network) in a specific way.
 
-URIs have the form @var{scheme}:@var{scheme-specific-part}, where the
-@var{scheme}s supported by this library are described below.
-@xref{Supported URL Types}.
+  Here are some examples of URIs (taken from RFC 3986):
 
-FTP, NFS, HTTP, HTTPS, @code{rlogin}, @code{telnet}, tn3270,
-IRC and gopher URLs all have the form
+@example
+ftp://ftp.is.co.za/rfc/rfc1808.txt
+http://www.ietf.org/rfc/rfc2396.txt
+ldap://[2001:db8::7]/c=GB?objectClass?one
+mailto:John.Doe@@example.com
+news:comp.infosystems.www.servers.unix
+tel:+1-816-555-1212
+telnet://192.0.2.16:80/
+urn:oasis:names:specification:docbook:dtd:xml:4.1.2
+@end example
+
+  This manual describes the @code{url} library, an Emacs Lisp library
+for parsing URIs and retrieving the resources to which they refer.
+(The library is so-named for historical reasons; nowadays, the ``URI''
+terminology is regarded as the more general one, and ``URL'' is
+technically obsolete despite its widespread vernacular usage.)
+
+@node URI Parsing
+@chapter URI Parsing
+
+  A URI consists of several @dfn{components}, each having a different
+meaning.  For example, the URI
 
 @example
-@var{scheme}://@r{[}@var{userinfo}@@@r{]}@var{hostname}@r{[}:@var{port}@r{]}@r{[}/@var{path}@r{]}
+http://www.gnu.org/software/emacs/
 @end example
+
 @noindent
-where @samp{@r{[}} and @samp{@r{]}} delimit optional parts.
-@var{userinfo} sometimes takes the form @var{username}:@var{password}
-but you should beware of the security risks of sending cleartext
-passwords.  @var{hostname} may be a domain name or a dotted decimal
-address.  If the @samp{:@var{port}} is omitted then the library will
-use the ``well known'' port for that service when accessing URLs.  With
-the possible exception of @code{telnet}, it is rare for ports to be
-specified, and it is possible using a non-standard port may have
-undesired consequences if a different service is listening on that
-port (e.g., an HTTP URL specifying the SMTP port can cause mail to be
-sent). @c , but @xref{Other Variables, url-bad-port-list}.
-The meaning of the @var{path} component depends on the service.
+specifies the scheme component @samp{http}, the hostname component
+@samp{www.gnu.org}, and the path component @samp{/software/emacs/}.
+
+@cindex parsed URIs
+  The format of URIs is specified by RFC 3986.  The @code{url} library
+provides the Lisp function @code{url-generic-parse-url}, a (mostly)
+standard-compliant URI parser, as well as function
+@code{url-recreate-url}, which converts a parsed URI back into a URI
+string.
+
+@defun url-generic-parse-url uri-string
+This function returns a parsed version of the string @var{uri-string}.
+@end defun
 
-@menu
-* Configuration::
-* Parsed URLs::                 URLs are parsed into vector structures.
-@end menu
+@defun url-recreate-url uri-obj
+@cindex unparsing URLs
+Given a parsed URI, this function returns the corresponding URI string.
+@end defun
 
-@node Configuration
-@section Configuration
+@cindex parsed URI
+  The return value of @code{url-generic-parse-url}, and the argument
+expected by @code{url-recreate-url}, is a @dfn{parsed URI}: a CL
+structure whose slots hold the various components of the URI.
+@xref{top,the CL Manual,,cl,GNU Emacs Common Lisp Emulation}, for
+details about CL structures.  Most of the other functions in the
+@code{url} library act on parsed URIs.
 
-@defvar url-configuration-directory
-@cindex @file{~/.url}
-@cindex configuration files
-The directory in which URL configuration files, the cache etc.,
-reside.  The old default was @file{~/.url}, and this directory
-is still used if it exists.  The new default is a @file{url/}
-directory in @code{user-emacs-directory}, which is normally
-@file{~/.emacs.d}.
-@end defvar
+@menu
+* Parsed URIs::           Format of parsed URI structures.
+* URI Encoding::          Non-@acronym{ASCII} characters in URIs.
+@end menu
 
-@node Parsed URLs
-@section Parsed URLs
-@cindex parsed URLs
-The library functions typically operate on @dfn{parsed} versions of
-URLs.  These are actually CL structures (vectors) of the form:
+@node Parsed URIs
+@section Parsed URI structures
 
-@example
-[cl-struct-url @var{type} @var{user} @var{password} @var{host} @var{port} @var{filename} @var{target} @var{attributes} @var{fullness} @var{use-cookies}]
-@end example
+  Each parsed URI structure contains the following slots:
 
-@noindent where
-@table @var
+@table @code
 @item type
-is the type of the URL scheme, e.g., @code{http}
+The URI scheme (a string, e.g.@: @code{http}).  @xref{Supported URL
+Types}, for a list of schemes that the @code{url} library knows how to
+process.  This slot can also be @code{nil}, if the URI is not fully
+specified.
+
 @item user
-is the username associated with it, or @code{nil};
+The user name (a string), or @code{nil}.
+
 @item password
-is the user password associated with it, or @code{nil};
+The user password (a string), or @code{nil}.  The use of this URI
+component is strongly discouraged; nowadays, passwords are transmitted
+by other means, not as part of a URI.
+
 @item host
-is the host name associated with it, or @code{nil};
+The host name (a string), or @code{nil}.  If present, this is
+typically a domain name or IP address.
+
 @item port
-is the port number associated with it, or @code{nil};
+The port number (an integer), or @code{nil}.  Omitting this component
+usually means to use the ``standard'' port associated with the URI
+scheme.
+
 @item filename
-is the ``file'' part of it, or @code{nil}.  This doesn't necessarily
-actually refer to a file;
+The combination of the ``path'' and ``query'' components of the URI (a
+string), or @code{nil}.  If the query component is present, it is the
+substring following the first @samp{?} character, and the path
+component is the substring before the @samp{?}.  The meaning of these
+components is scheme-dependent; they do not necessarily refer to a
+file on a disk.
+
 @item target
-is the target part, or @code{nil};
-@item attributes
-is the attributes associated with it, or @code{nil};
+The fragment component (a string), or @code{nil}.  The fragment
+component specifies a ``secondary resource'', such as a section of a
+webpage.
+
 @item fullness
-is @code{t} for a fully-specified URL, with a host part indicated by
-@samp{//} after the scheme part.
-@item use-cookies
-is @code{nil} to neither send or store cookies to the server, @code{t}
-otherwise.
+This is @code{t} if the URI is fully specified, i.e.@: the
+hierarchical components of the URI (the hostname and/or username
+and/or password) are preceded by @samp{//}.
 @end table
 
 @findex url-type
@@ -168,64 +204,165 @@ otherwise.
 @findex url-target
 @findex url-attributes
 @findex url-fullness
-These attributes have accessors named @code{url-@var{part}}, where
-@var{part} is the name of one of the elements above, e.g.,
-@code{url-host}.  These attributes can be set with the same accessors
-using @code{setf}:
+These slots have accessors named @code{url-@var{part}}, where
+@var{part} is the slot name.  For example, the accessor for the
+@code{host} slot is the function @code{url-host}.  The @code{url-port}
+accessor returns the default port for the URI scheme if the parsed
+URI's @var{port} slot is @code{nil}.
+
+  The slots can be set using @code{setf}.  For example:
 
 @example
 (setf (url-port url) 80)
 @end example
 
-If @var{port} is @var{nil}, @code{url-port} returns the default port
-of the protocol.
-
-There are functions for parsing and unparsing between the string and
-vector forms.
+@node URI Encoding
+@section URI Encoding
+
+@cindex percent encoding
+  The @code{url-generic-parse-url} parser does not obey RFC 3986 in
+one respect: it allows non-@acronym{ASCII} characters in URI strings.
+
+  Strictly speaking, RFC 3986 compatible URIs may only consist of
+@acronym{ASCII} characters; non-@acronym{ASCII} characters are
+represented by converting them to UTF-8 byte sequences, and performing
+@dfn{percent encoding} on the bytes.  For example, the o-umlaut
+character is converted to the UTF-8 byte sequence @samp{\xD3\xA7},
+then percent encoded to @samp{%D3%A7}.  (Certain ``reserved''
+@acronym{ASCII} characters must also be percent encoded when they
+appear in URI components.)
+
+  The function @code{url-encode-url} can be used to convert a URI
+string containing arbitrary characters to one that is properly
+percent-encoded in accordance with RFC 3986.
+
+@defun url-encode-url url-string
+This function return a properly URI-encoded version of
+@var{url-string}.  It also performs @dfn{URI normalization},
+e.g.@: converting the scheme component to lowercase if it was
+previously uppercase.
+@end defun
 
-@defun url-generic-parse-url url
-Return a parsed version of the string @var{url}.
+  To convert between a string containing arbitrary characters and a
+percent-encoded all-@acronym{ASCII} string, use the functions
+@code{url-hexify-string} and @code{url-unhex-string}:
+
+@defun url-hexify-string string &optional allowed-chars
+This function performs percent-encoding on @var{string}, and returns
+the result.
+
+If @var{string} is multibyte, it is first converted to a UTF-8 byte
+string.  Each byte corresponding to an allowed character is left
+as-is, while all other bytes are converted to a three-character
+sequence: @samp{%} followed by two upper-case hex digits.
+
+@vindex url-unreserved-chars
+@cindex unreserved characters
+The allowed characters are specified by @var{allowed-chars}.  If this
+argument is @code{nil}, the allowed characters are those specified as
+@dfn{unreserved characters} by RFC 3986 (see the variable
+@code{url-unreserved-chars}).  Otherwise, @var{allowed-chars} should
+be a vector whose @var{n}-th element is non-@code{nil} if character
+@var{n} is allowed.
 @end defun
 
-@defun url-recreate-url url
-@cindex unparsing URLs
-Recreates a URL string from the parsed @var{url}.
+@defun url-unhex-string string &optional allow-newlines
+This function replaces percent-encoding sequences in @var{string} with
+their character equivalents, and returns the resulting string.
+
+If @var{allow-newlines} is non-@code{nil}, it allows the decoding of
+carriage returns and line feeds, which are normally forbidden in URIs.
 @end defun
 
 @node Retrieving URLs
 @chapter Retrieving URLs
 
+  The @code{url} library defines the following three functions for
+retrieving the data specified by a URL.  The actual retrieval protocol
+depends on the URL's URI scheme, and is performed by lower-level
+scheme-specific functions.  (Those lower-level functions are not
+documented here, and generally should not be called directly.)
+
+  In each of these functions, the @var{url} argument can be either a
+string or a parsed URL structure.  If it is a string, that string is
+passed through @code{url-encode-url} before using it, to ensure that
+it is properly URI-encoded (@pxref{URI Encoding}).
+
 @defun url-retrieve-synchronously url
-Retrieve @var{url} synchronously and return a buffer containing the
-data.  @var{url} is either a string or a parsed URL structure.  Return
-@code{nil} if there are no data associated with it (the case for dired,
-info, or mailto URLs that need no further processing).
+This function synchronously retrieves the data specified by @var{url},
+and returns a buffer containing the data.  The return value is
+@code{nil} if there is no data associated with the URL (as is the case
+for @code{dired}, @code{info}, and @code{mailto} URLs).
 @end defun
 
 @defun url-retrieve url callback &optional cbargs silent no-cookies
-Retrieve @var{url} asynchronously and call @var{callback} with args
-@var{cbargs} when finished.  The callback is called when the object
-has been completely retrieved, with the current buffer containing the
-object and any MIME headers associated with it.  @var{url} is either a
-string or a parsed URL structure.  Returns the buffer @var{url} will
-load into, or @code{nil} if the process has already completed.
-If the optional argument @var{silent} is non-@code{nil}, suppress
-progress messages.  If the optional argument @var{no-cookies} is
-non-@code{nil}, do not store or send cookies.
+This function retrieves @var{url} asynchronously, calling the function
+@var{callback} when the object has been completely retrieved.  The
+return value is the buffer into which the data will be inserted, or
+@code{nil} if the process has already completed.
+
+The callback function is called this way:
+
+@example
+(apply @var{callback} @var{status} @var{cbargs})
+@end example
+
+@noindent
+where @var{status} is a plist representing what happened during the
+retrieval, with most recent events first, or an empty list if no
+events have occurred.  Each pair in the plist is one of:
+
+@table @code
+@item (:redirect @var{redirected-to})
+This means that the request was redirected to the URL
+@var{redirected-to}.
+
+@item (:error (@var{error-symbol} . @var{data}))
+This means that an error occurred.  If so desired, the error can be
+signaled with @code{(signal @var{error-symbol} @var{data})}.
+@end table
+
+When the callback function is called, the current buffer is the one
+containing the retrieved data (if any).  The buffer also contains any
+MIME headers associated with the data retrieval.
+
+If the optional argument @var{silent} is non-@code{nil}, progress
+messages are suppressed.  If the optional argument @var{no-cookies} is
+non-@code{nil}, cookies are not stored or sent.
 @end defun
 
-@vindex url-queue-parallel-processes
-@vindex url-queue-timeout
 @defun url-queue-retrieve url callback &optional cbargs silent no-cookies
-This acts like the @code{url-retrieve} function, but with limits on
-the degree of parallelism.  The option @code{url-queue-parallel-processes}
-controls the number of concurrent processes, and the option
-@code{url-queue-timeout} sets a timeout in seconds.
+This function acts like @code{url-retrieve}, but with limits on the
+number of concurrently-running network processes.  The option
+@code{url-queue-parallel-processes} controls the number of concurrent
+processes, and the option @code{url-queue-timeout} sets a timeout in
+seconds.
+
+To use this function, you must @code{(require 'url-queue)}.
 @end defun
 
+@vindex url-queue-parallel-processes
+@defopt url-queue-parallel-processes
+The value of this option is an integer specifying the maximum number
+of concurrent @code{url-queue-retrieve} network processes.  If the
+number of @code{url-queue-retrieve} calls is larger than this number,
+later ones are queued until ealier ones are finished.
+@end defopt
+
+@vindex url-queue-timeout
+@defopt url-queue-timeout
+The value of this option is a number specifying the maximum lifetime
+of a @code{url-queue-retrieve} network process, once it is started.
+If a process is not finished by then, it is killed and removed from
+the queue.
+@end defopt
+
 @node Supported URL Types
 @chapter Supported URL Types
 
+This chapter describes functions and variables affecting URL retrieval
+for specific schemes.
+
 @menu
 * http/https::                  Hypertext Transfer Protocol.
 * file/ftp::                    Local files and FTP archives.
@@ -236,48 +373,31 @@ controls the number of concurrent processes, and the option
 * irc::                         Internet Relay Chat.
 * data::                        Embedded data URLs.
 * nfs::                         Networked File System
-@c * finger::
-@c * gopher::
-@c * netrek::
-@c * prospero::
-* cid::                         Content-ID.
-* about::
 * ldap::                        Lightweight Directory Access Protocol
-* imap::                        IMAP mailboxes.
 * man::                         Unix man pages.
 @end menu
 
 @node http/https
 @section @code{http} and @code{https}
 
-The scheme @code{http} is Hypertext Transfer Protocol.  The library
-supports version 1.1, specified in RFC 2616.  (This supersedes 1.0,
-defined in RFC 1945) HTTP URLs have the following form, where most of
-the parts are optional:
-@example
-http://@var{user}:@var{password}@@@var{host}:@var{port}/@var{path}?@var{searchpart}#@var{fragment}
-@end example
-@c The @code{:@var{port}} part is optional, and @var{port} defaults to
-@c 80.  The @code{/@var{path}} part, if present, is a slash-separated
-@c series elements.  The @code{?@var{searchpart}}, if present, is the
-@c query for a search or the content of a form submission.  The
-@c @code{#fragment} part, if present, is a location in the document.
-
-The scheme @code{https} is a secure version of @code{http}, with
-transmission via SSL.  It is defined in RFC 2069.  Its default port is
-443.  This scheme depends on SSL support in Emacs via the
-@file{ssl.el} library and is actually implemented by forcing the
-@code{ssl} gateway method to be used.  @xref{Gateways in general}.
+The @code{http} scheme refers to the Hypertext Transfer Protocol.  The
+@code{url} library supports HTTP version 1.1, specified in RFC 2616.
+Its default port is 80.
+
+  The @code{https} scheme is a secure version of @code{http}, with
+transmission via SSL.  It is defined in RFC 2069, and its default port
+is 443.  When using @code{https}, the @code{url} library performs SSL
+encryption via the @code{ssl} library, by forcing the @code{ssl}
+gateway method to be used.  @xref{Gateways in general}.
 
 @defopt url-honor-refresh-requests
-This controls honoring of HTTP @samp{Refresh} headers by which
-servers can direct clients to reload documents from the same URL or a
-or different one.  @code{nil} means they will not be honored,
-@code{t} (the default) means they will always be honored, and
-otherwise the user will be asked on each request.
+If this option is non-@code{nil} (the default), the @code{url} library
+honors the HTTP @samp{Refresh} header, which is used by servers to
+direct clients to reload documents from the same URL or a or different
+one.  If the value is @code{nil}, the @samp{Refresh} header is
+ignored; any other value means to ask the user on each request.
 @end defopt
 
-
 @menu
 * Cookies::
 * HTTP language/coding::
@@ -409,26 +529,32 @@ emacs-mime, The Emacs MIME Manual}.
 @cindex compressed files
 @cindex dired
 
+The @code{ftp} and @code{file} schemes are defined in RFC 1808.  The
+@code{url} library treats @samp{ftp:} and @samp{file:} as synonymous.
+Such URLs have the form
+
 @example
 ftp://@var{user}:@var{password}@@@var{host}:@var{port}/@var{file}
 file://@var{user}:@var{password}@@@var{host}:@var{port}/@var{file}
 @end example
 
-These schemes are defined in RFC 1808.
-@samp{ftp:} and @samp{file:} are synonymous in this library.  They
-allow reading arbitrary files from hosts.  Either @samp{ange-ftp}
-(Emacs) or @samp{efs} (XEmacs) is used to retrieve them from remote
-hosts.  Local files are accessed directly.
+@noindent
+If the URL specifies a local file, it is retrieved by reading the file
+contents in the usual way.  If it specifies a remote file, it is
+retrieved using the Ange-FTP package.  @xref{Remote Files,,, emacs,
+The GNU Emacs Manual}.
 
-Compressed files are handled, but support is hard-coded so that
-@code{jka-compr-compression-info-list} and so on have no affect.
-Suffixes recognized are @samp{.z}, @samp{.gz}, @samp{.Z} and
-@samp{.bz2}.
+  When retrieving a compressed file, it is automatically uncompressed
+if it has the file suffix @file{.z}, @file{.gz}, @file{.Z},
+@file{.bz2}, or @file{.xz}.  (The list of supported suffixes is
+hard-coded, and cannot be altered by customizing
+@code{jka-compr-compression-info-list}.)
 
 @defopt url-directory-index-file
-The filename to look for when indexing a directory, default
-@samp{"index.html"}.  If this file exists, and is readable, then it
-will be viewed instead of using @code{dired} to view the directory.
+This option specifies the filename to look for when a @code{file} or
+@code{ftp} URL specifies a directory.  The default is
+@file{index.html}.  If this file exists and is readable, it is viewed.
+Otherwise, Emacs visits the directory using Dired.
 @end defopt
 
 @node info
@@ -437,47 +563,53 @@ will be viewed instead of using @code{dired} to view the directory.
 @cindex Texinfo
 @findex Info-goto-node
 
+The @code{info} scheme is non-standard.  Such URLs have the form
+
 @example
 info:@var{file}#@var{node}
 @end example
 
-Info URLs are not officially defined.  They invoke
-@code{Info-goto-node} with argument @samp{(@var{file})@var{node}}.
-@samp{#@var{node}} is optional, defaulting to @samp{Top}.
+@noindent
+and are retrieved by invoking @code{Info-goto-node} with argument
+@samp{(@var{file})@var{node}}.  If @samp{#@var{node}} is omitted, the
+@samp{Top} node is opened.
 
 @node mailto
 @section mailto
 
 @cindex mailto
 @cindex email
-A mailto URL will send an email message to the address in the
-URL, for example @samp{mailto:foo@@bar.com} would compose a
-message to @samp{foo@@bar.com}.
-
-@defopt url-mail-command
-@vindex mail-user-agent
-The function called whenever url needs to send mail.  This should
-normally be left to default from @var{mail-user-agent}.  @xref{Mail
-Methods, , Mail-Composition Methods, emacs, The GNU Emacs Manual}.
-@end defopt
+A @code{mailto} URL specifies an email message to be sent to a given
+email address.  For example, @samp{mailto:foo@@bar.com} specifies
+sending a message to @samp{foo@@bar.com}.  The ``retrieval method''
+for such URLs is to open a mail composition buffer in which the
+appropriate content (e.g.@: the recipient address) has been filled in.
 
-An @samp{X-Url-From} header field containing the URL of the document
-that contained the mailto URL is added if that URL is known.
+  As defined in RFC 2368, a @code{mailto} URL has the form
 
-RFC 2368 extends the definition of mailto URLs in RFC 1738.
-The form of a mailto URL is
 @example
 @samp{mailto:@var{mailbox}[?@var{header}=@var{contents}[&@var{header}=@var{contents}]]}
 @end example
-@noindent where an arbitrary number of @var{header}s can be added.  If the
-@var{header} is @samp{body}, then @var{contents} is put in the body
-otherwise a @var{header} header field is created with @var{contents}
-as its contents.  Note that the URL library does not consider any
-headers ``dangerous'' so you should check them before sending the
-message.
 
-@c Fixme: update
-Email messages are defined in @sc{rfc}822.
+@noindent
+where an arbitrary number of @var{header}s can be added.  If the
+@var{header} is @samp{body}, then @var{contents} is put in the message
+body; otherwise, a @var{header} header field is created with
+@var{contents} as its contents.  Note that the @code{url} library does
+not perform any checking of @var{header} or @var{contents}, so you
+should check them before sending the message.
+
+@defopt url-mail-command
+@vindex mail-user-agent
+The value of this variable is the function called whenever url needs
+to send mail.  This should normally be left its default, which is the
+standard mail-composition command @code{compose-mail}.  @xref{Sending
+Mail,,, emacs, The GNU Emacs Manual}.
+@end defopt
+
+  If the document containing the @code{mailto} URL itself possessed a
+known URL, Emacs automatically inserts an @samp{X-Url-From} header
+field into the mail buffer, specifying that URL.
 
 @node news/nntp/snews
 @section @code{news}, @code{nntp} and @code{snews}
@@ -487,11 +619,13 @@ Email messages are defined in @sc{rfc}822.
 @cindex NNTP
 @cindex snews
 
-@c draft-gilman-news-url-01
-The network news URL scheme take the following forms following RFC
-1738 except that for compatibility with other clients, host and port
-fields may be included in news URLs though they are properly only
-allowed for nntp an snews.
+The @code{news}, @code{nntp}, and @code{snews} schemes, defined in RFC
+1738, are used for reading Usenet newsgroups.  For compatibility with
+non-standard-compliant news clients, the @code{url} library allows
+host and port fields to be included in @code{news} URLs, even though
+they are properly only allowed for @code{nntp} and @code{snews}.
+
+  @code{news} and @code{nntp} URLs have the following form:
 
 @table @samp
 @item news:@var{newsgroup}
@@ -506,24 +640,22 @@ Retrieves a list of all available newsgroups;
 Similar to the @samp{news} versions.
 @end table
 
-@samp{:@var{port}} is optional and defaults to :119.
-
-@samp{snews} is the same as @samp{nntp} except that the default port
-is :563.
-@cindex SSL
-(It is tunneled through SSL.)
+  The default port for @code{nntp} (and @code{news}) is 119.  The
+difference between an @code{nntp} URL and a @code{news} URL is that an
+@code{nttp} URL may specify an article by its number.  The
+@samp{snews} scheme is the same as @samp{nntp}, except that it is
+tunneled through SSL and has default port 563.
 
-An @samp{nntp} URL is the same as a news URL, except that the URL may
-specify an article by its number.
+  These URLs are retrieved via the Gnus package.
 
-@defopt url-news-server
-This variable can be used to override the default news server.
-Usually this will be set by the Gnus package, which is used to fetch
-news.
 @cindex environment variable
 @vindex NNTPSERVER
-It may be set from the conventional environment variable
-@code{NNTPSERVER}.
+@defopt url-news-server
+This variable specifies the default news server from which to fetch
+news, if no server was specified in the URL.  The default value,
+@code{nil}, means to use the server specified by the standard
+environment variable @samp{NNTPSERVER}, or @samp{news} if that
+environment variable is unset.
 @end defopt
 
 @node rlogin/telnet/tn3270
@@ -534,12 +666,15 @@ It may be set from the conventional environment variable
 @cindex terminal emulation
 @findex terminal-emulator
 
-These URL schemes from RFC 1738 for logon via a terminal emulator have
-the form
+These URL schemes are defined in RFC 1738, and are used for logging in
+via a terminal emulator.  They have the form
+
 @example
 telnet://@var{user}:@var{password}@@@var{host}:@var{port}
 @end example
-but the @code{:@var{password}} component is ignored.
+
+@noindent
+but the @var{password} component is ignored.
 
 To handle rlogin, telnet and tn3270 URLs, a @code{rlogin},
 @code{telnet} or @code{tn3270} (the program names and arguments are
@@ -553,39 +688,43 @@ Well-known ports are used if the URL does not specify a port.
 @cindex ZEN IRC
 @cindex ERC
 @cindex rcirc
-@c Fixme: reference (was http://www.w3.org/Addressing/draft-mirashi-url-irc-01.txt)
-@dfn{Internet Relay Chat} (IRC) is handled by handing off the @sc{irc}
-session to a function named in @code{url-irc-function}.
+
+  The @code{irc} scheme is defined in the Internet Draft at
+@url{http://www.w3.org/Addressing/draft-mirashi-url-irc-01.txt} (which
+was never approved as an RFC).  Such URLs have the form
+
+@example
+irc://@var{host}:@var{port}/@var{target},@var{needpass}
+@end example
+
+@noindent
+and are retrieved by opening an @acronym{IRC} session using the
+function specified by @code{url-irc-function}.
 
 @defopt url-irc-function
-A function to actually open an IRC connection.
-This function
-must take five arguments, @var{host}, @var{port}, @var{channel},
-@var{user} and @var{password}.  The @var{channel} argument specifies the
-channel to join immediately, this can be @code{nil}.  By default this is
-@code{url-irc-rcirc}.
+The value of this option is a function, which is called to open an IRC
+connection for @code{irc} URLs.  This function must take five
+arguments, @var{host}, @var{port}, @var{channel}, @var{user} and
+@var{password}.  The @var{channel} argument specifies the channel to
+join immediately, and may be @code{nil}.
+
+The default is @code{url-irc-rcirc}, which uses the Rcirc package.
+Other options are @code{url-irc-erc} (which uses ERC) and
+@code{url-irc-zenirc} (which uses ZenIRC).
 @end defopt
-@defun url-irc-rcirc host port channel user password
-Processes the arguments and lets @code{rcirc} handle the session.
-@end defun
-@defun url-irc-erc host port channel user password
-Processes the arguments and lets @code{ERC} handle the session.
-@end defun
-@defun url-irc-zenirc host port channel user password
-Processes the arguments and lets @code{zenirc} handle the session.
-@end defun
 
 @node data
 @section data
 @cindex data URLs
 
+  The @code{data} scheme, defined in RFC 2397, contains MIME data in
+the URL itself.  Such URLs have the form
+
 @example
 data:@r{[}@var{media-type}@r{]}@r{[};@var{base64}@r{]},@var{data}
 @end example
 
-Data URLs contain MIME data in the URL itself.  They are defined in
-RFC 2397.
-
+@noindent
 @var{media-type} is a MIME @samp{Content-Type} string, possibly
 including parameters.  It defaults to
 @samp{text/plain;charset=US-ASCII}.  The @samp{text/plain} can be
@@ -598,14 +737,14 @@ present, the @var{data} are base64-encoded.
 @cindex Network File System
 @cindex automounter
 
+The @code{nfs} scheme, defined in RFC 2224, is similar to @code{ftp}
+except that it points to a file on a remote host that is handled by an
+NFS automounter on the local host.  Such URLs have the form
+
 @example
 nfs://@var{user}:@var{password}@@@var{host}:@var{port}/@var{file}
 @end example
 
-The @samp{nfs:} scheme is defined in RFC 2224.  It is similar to
-@samp{ftp:} except that it points to a file on a remote host that is
-handled by the automounter on the local host.
-
 @defvar url-nfs-automounter-directory-spec
 @end defvar
 A string saying how to invoke the NFS automounter.  Certain @samp{%}
@@ -628,15 +767,6 @@ A literal @samp{%}.
 
 Each can be used any number of times.
 
-@node cid
-@section cid
-@cindex Content-ID
-
-RFC 2111
-
-@node about
-@section about
-
 @node ldap
 @section ldap
 @cindex LDAP
@@ -644,50 +774,21 @@ RFC 2111
 
 The LDAP scheme is defined in RFC 2255.
 
-@node imap
-@section imap
-@cindex IMAP
-
-RFC 2192
-
 @node man
 @section man
 @cindex @command{man}
 @cindex Unix man pages
 @findex man
 
+The @code{man} scheme is a non-standard one.  Such URLs have the form
+
 @example
 @samp{man:@var{page-spec}}
 @end example
 
-This is a non-standard scheme.  @var{page-spec} is passed directly to
-the Lisp @code{man} function.
-
-@node Defining New URLs
-@chapter Defining New URLs
-
-@menu
-* Naming conventions::
-* Required functions::
-* Optional functions::
-* Asynchronous fetching::
-* Supporting file-name-handlers::
-@end menu
-
-@node Naming conventions
-@section Naming conventions
-
-@node Required functions
-@section Required functions
-
-@node Optional functions
-@section Optional functions
-
-@node Asynchronous fetching
-@section Asynchronous fetching
-
-@node Supporting file-name-handlers
-@section Supporting file-name-handlers
+@noindent
+and are retrieved by passing @var{page-spec} to the Lisp function
+@code{man}.
 
 @node General Facilities
 @chapter General Facilities
@@ -1108,11 +1209,9 @@ You can use this function to do completion of URLs from the history.
 @node Customization
 @chapter Customization
 
-@section Environment Variables
-
 @cindex environment variables
-The following environment variables affect the library's operation at
-startup.
+  The following environment variables affect the @code{url} library's
+operation at startup.
 
 @table @code
 @item TMPDIR
@@ -1122,10 +1221,21 @@ If this is defined, @var{url-temporary-directory} is initialized from
 it.
 @end table
 
-@section General User Options
+  The following user options affect the general operation of
+@code{url} library.
 
-The following user options, settable with Customize, affect the
-general operation of the package.
+@defopt url-configuration-directory
+@cindex configuration files
+The value of this variable specifies the name of the directory where
+the @code{url} library stores its various configuration files, cache
+files, etc.
+
+The default value specifies a subdirectory named @file{url/} in the
+standard Emacs user data directory specified by the variable
+@code{user-emacs-directory} (normally @file{~/.emacs.d}).  However,
+the old default was @file{~/.url}, and this directory is used instead
+if it exists.
+@end defopt
 
 @defopt url-debug
 @cindex debugging