upstream

8 files changed, 547 insertions, 656 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 0fa50492481..293f253c545 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,43 @@
+2011-11-21  Martin Rudalics  <rudalics@gmx.at>
+
+        * windows.texi (Windows and Frames, Splitting Windows): Fix
+        typos.
+
+2011-11-21  Chong Yidong  <cyd@gnu.org>
+
+        * windows.texi (Splitting Windows): Fix error in documentation of
+        window-combination-limit.
+        (Cyclic Window Ordering): Minor fixes to next-window,
+        one-window-p, and get-lru-window docs.  Don't document
+        window-list-1.
+        (Buffers and Windows): Copyedits.
+        (Choosing Window): Document special handling of special-display-*.
+        (Choosing Window Options): Fix display-buffer-reuse-frames doc.
+        Don't document even-window-heights, which is going away.  Clarify
+        which options are obeyed by which action functions.
+
+2011-11-20  Stefan Monnier  <monnier@iro.umontreal.ca>
+
+        * display.texi (Invisible Text): Clarify point adjustment (bug#10072).
+
+2011-11-20  Martin Rudalics  <rudalics@gmx.at>
+
+        * windows.texi (Resizing Windows, Splitting Windows):
+        Remove term "status" when talking about combination limits.
+
+2011-11-20  Juanma Barranquero  <lekktu@gmail.com>
+
+        * compile.texi (Compiler Errors):
+        * help.texi (Help Functions): Fix typos.
+
+2011-11-19  Chong Yidong  <cyd@gnu.org>
+
+        * windows.texi (Splitting Windows): Clarify role of window
+        parameters in split-window.  Shorten the example.
+        (Deleting Windows): Rewrite intro to handle internal windows.
+        Fix delete-windows-on doc.
+        (Selecting Windows): Copyedits.
+
 2011-11-17  Martin Rudalics  <rudalics@gmx.at>
 
         * windows.texi (Resizing Windows, Splitting Windows)
@@ -6,8 +46,8 @@
 
 2011-11-16  Martin Rudalics  <rudalics@gmx.at>
 
-        * windows.texi (Resizing Windows, Splitting Windows): Rename
-        occurrences of window-nest to window-combination-limit.
+        * windows.texi (Resizing Windows, Splitting Windows):
+        Rename occurrences of window-nest to window-combination-limit.
 
 2011-11-14  Juanma Barranquero  <lekktu@gmail.com>
 
@@ -15,8 +55,8 @@
 
 2011-11-12  Martin Rudalics  <rudalics@gmx.at>
 
-        * windows.texi (Splitting Windows, Deleting Windows): Remove
-        references to splits status of windows.
+        * windows.texi (Splitting Windows, Deleting Windows):
+        Remove references to splits status of windows.
 
 2011-11-10  Glenn Morris  <rgm@gnu.org>
 
@@ -68,8 +108,8 @@
         (Windows and Frames): Various clarifications, e.g. non-live
         windows also belong to frames.  Fix window-list description.
         Simplify window nesting example.
-        (Splitting Windows, Window Configurations): Use
-        split-window-below.
+        (Splitting Windows, Window Configurations):
+        Use split-window-below.
 
 2011-11-04  Eli Zaretskii  <eliz@gnu.org>
 
@@ -119,8 +159,8 @@
 
 2011-10-05  Chong Yidong  <cyd@stupidchicken.com>
 
-        * display.texi (Low-Level Font, Face Attributes, Font Lookup): Fix
-        Emacs manual xref (Bug#9675).
+        * display.texi (Low-Level Font, Face Attributes, Font Lookup):
+        Fix Emacs manual xref (Bug#9675).
 
 2011-10-01  Chong Yidong  <cyd@stupidchicken.com>
 
@@ -159,8 +199,8 @@
         * windows.texi (Window History): New node.  Move text here from
         Buffers and Windows.
         (Switching Buffers): Rename from Displaying Buffers, since we
-        don't document display-buffer here; callers changed.  Document
-        FORCE-SAME-WINDOW arg to switch-to-buffer and
+        don't document display-buffer here; callers changed.
+        Document FORCE-SAME-WINDOW arg to switch-to-buffer and
         switch-to-buffer-other-frame.  Delete duplicate
         replace-buffer-in-windows doc.
         (Choosing Window): Document display actions.
@@ -191,10 +231,10 @@
         Provide examples.  Describe window-nest and window-splits
         options.
         (Deleting Windows): Minor rewrite.
-        (Selecting Windows): Minor rewrite.  Describe
-        frame-selected-window and set-frame-selected-window here.
-        (Cyclic Window Ordering): Minor rewrite.  Describe
-        window-list-1.
+        (Selecting Windows): Minor rewrite.
+        Describe frame-selected-window and set-frame-selected-window here.
+        (Cyclic Window Ordering): Minor rewrite.
+        Describe window-list-1.
         (Buffers and Windows): Rewrite.  Explain a window's previous and
         next buffers and the corresponding functions.
         (Window Tree): Merge into Windows and Frames section.
@@ -296,8 +336,8 @@
 
         * display.texi (Bidirectional Display): Document the pitfalls of
         concatenating strings with bidirectional content, with possible
-        solutions.  Document bidi-string-mark-left-to-right.  Mention
-        paragraph direction in modes that inherit from prog-mode.
+        solutions.  Document bidi-string-mark-left-to-right.
+        Mention paragraph direction in modes that inherit from prog-mode.
         Document use of `bidi-class' and `mirroring' properties as part of
         reordering.
 
@@ -353,8 +393,8 @@
         the next character, and doesn't affect longer sequences in
         particular (bug#8935).
 
-        * debugging.texi (Using Debugger): Mention
-        @code{eval-expression-debug-on-error} (bug#8549).
+        * debugging.texi (Using Debugger):
+        Mention @code{eval-expression-debug-on-error} (bug#8549).
 
 2011-07-14  Eli Zaretskii  <eliz@gnu.org>
 
@@ -503,7 +543,7 @@
 
 2011-06-15  Lars Magne Ingebrigtsen  <larsi@gnus.org>
 
-        * processes.texi (Process Information): Renamed `process-alive-p'
+        * processes.texi (Process Information): Rename `process-alive-p'
         to `process-live-p' for consistency with other `-live-p' functions.
 
 2011-06-03  Paul Eggert  <eggert@cs.ucla.edu>
@@ -520,8 +560,8 @@
 
 2011-05-31  Lars Magne Ingebrigtsen  <larsi@gnus.org>
 
-        * processes.texi (Process Information): Document
-        `process-alive-p'.
+        * processes.texi (Process Information):
+        Document `process-alive-p'.
 
 2011-05-29  Chong Yidong  <cyd@stupidchicken.com>
 
@@ -1919,8 +1959,8 @@
 
 2009-05-09  Eli Zaretskii  <eliz@gnu.org>
 
-        * nonascii.texi (Default Coding Systems): Document
-        find-auto-coding, set-auto-coding, and auto-coding-alist.
+        * nonascii.texi (Default Coding Systems):
+        Document find-auto-coding, set-auto-coding, and auto-coding-alist.
         Add indexing.
         (Lisp and Coding Systems): Add index entries.
 
@@ -2237,7 +2277,7 @@
         (Future Local Variables): Node deleted.
 
         * objects.texi (General Escape Syntax): Update explanation of
-        unicode escape syntax.
+        Unicode escape syntax.
 
 2009-02-23  Chong Yidong  <cyd@stupidchicken.com>
 
@@ -5151,8 +5191,8 @@
         (Saving Buffers): Mention code and EOL conversions by file I/O
         primitives and subroutines.
 
-        * nonascii.texi (Lisp and Coding Systems): Document
-        coding-system-eol-type.  Add index entries for eol conversion.
+        * nonascii.texi (Lisp and Coding Systems):
+        Document coding-system-eol-type.  Add index entries for eol conversion.
 
         * display.texi (Defining Faces): Mention `mac', and add an xref to
         where window-system is described.
@@ -9102,7 +9142,7 @@
 
         * functions.texi (Defining Functions): Explain about redefining
         primitives.
-        (Function Safety): Renamed.  Minor changes.
+        (Function Safety): Rename.  Minor changes.
         Comment out the detailed criteria for what is safe.
 
 2003-06-22  Andreas Schwab  <schwab@suse.de>
@@ -9603,7 +9643,7 @@
 
         * Makefile (infodir, prefix): New vars.
         (install): Use infodir.
-        (emacsinfodir): Deleted.
+        (emacsinfodir): Delete.
 
 1993-05-27  Richard Stallman  (rms@mole.gnu.ai.mit.edu)
 
@@ -9614,7 +9654,7 @@
 
 1993-05-16  Jim Blandy  (jimb@wookumz.gnu.ai.mit.edu)
 
-        * Makefile (dist): Changed to use Gzip instead of compress.
+        * Makefile (dist): Change to use Gzip instead of compress.
 
 1993-04-23  Eric S. Raymond  (eric@mole.gnu.ai.mit.edu)
 
diff --git a/doc/lispref/compile.texi b/doc/lispref/compile.texi
index fe5563370c4..372c041ab7a 100644
--- a/doc/lispref/compile.texi
+++ b/doc/lispref/compile.texi
@@ -528,7 +528,7 @@ but the compiler does not issue warnings for anything that occurs
 inside @var{body}.
 
 We recommend that you use this construct around the smallest
-possible piece of code, to avoid missing possible warnings other than one
+possible piece of code, to avoid missing possible warnings other than
 one you intend to suppress.
 @end defspec
 
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 034d92f78c3..9849420b1f5 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -870,15 +870,21 @@ ignore invisible newlines if @code{line-move-ignore-invisible} is
 non-@code{nil} (the default), but only because they are explicitly
 programmed to do so.
 
-  However, if a command ends with point inside or immediately before
-invisible text, the main editing loop moves point further forward or
-further backward (in the same direction that the command already moved
-it) until that condition is no longer true.  Thus, if the command
-moved point back into an invisible range, Emacs moves point back to
-the beginning of that range, and then back one more character.  If the
-command moved point forward into an invisible range, Emacs moves point
-forward up to the first visible character that follows the invisible
-text.
+  However, if a command ends with point inside or at the boundary of invisible
+text, the main editing loop moves point to one of the two ends of the invisible
+text.  Which end to move to is chosen based on the following factors: make sure
+that the overall movement of the command is still in the same direction, and
+prefer a position where an inserted char would not inherit the @code{invisible}
+property.  Additionally, if the text is not replaced by an ellipsis and the
+command only moved within the invisible text, then point is moved one extra
+character so as to try and reflect the command's movement by a visible movement
+of the cursor.
+
+  Thus, if the command moved point back to an invisible range (with the usual
+stickiness), Emacs moves point back to the beginning of that range.  If the
+command moved point forward into an invisible range, Emacs moves point forward
+to the first visible character that follows the invisible text and then forward
+one more character.
 
   Incremental search can make invisible overlays visible temporarily
 and/or permanently when a match includes invisible text.  To enable
@@ -4546,7 +4552,7 @@ you may prefer to use a different one for a given image type (which
 @c FIXME how is this priority determined?
 loader will be used in practice depends on the priority of the loaders).
 @c FIXME why are these uppercase when image-types is lower-case?
-@c FIXME what are the possibe options?  Are these actually file extensions?
+@c FIXME what are the possible options?  Are these actually file extensions?
 For example, if you never want to use the ImageMagick loader to use
 JPEG files, add @code{JPG} to this list.
 
diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index d2e86a77112..dad1f28026e 100644
--- a/doc/lispref/frames.texi
+++ b/doc/lispref/frames.texi
@@ -953,7 +953,7 @@ variable, Emacs uses the latter.  By default,
 The @code{alpha} frame parameter can also be a cons cell
 @code{(@samp{active} . @samp{inactive})}, where @samp{active} is the
 opacity of the frame when it is selected, and @samp{inactive} is the
-opactity when it is not selected.
+opacity when it is not selected.
 @end table
 
 The following frame parameters are semi-obsolete in that they are
diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi
index 0ce05d55a07..3426e81cdb3 100644
--- a/doc/lispref/help.texi
+++ b/doc/lispref/help.texi
@@ -653,7 +653,7 @@ buffer, which is used to regenerate the help information when the user
 clicks on the @samp{Back} or @samp{Forward} buttons.  Most commands
 that use the @samp{*Help*} buffer should invoke this function before
 clearing the buffer.  The @var{item} argument should have the form
-@code{(@var{funtion} . @var{args})}, where @var{funtion} is a function
+@code{(@var{function} . @var{args})}, where @var{function} is a function
 to call, with argument list @var{args}, to regenerate the help buffer.
 The @var{interactive-p} argument is non-@code{nil} if the calling
 command was invoked interactively; in that case, the stack of items
diff --git a/doc/lispref/searching.texi b/doc/lispref/searching.texi
index fe7c805c6f7..a601ed0c2c0 100644
--- a/doc/lispref/searching.texi
+++ b/doc/lispref/searching.texi
@@ -1213,7 +1213,7 @@ match data around it, to prevent it from being overwritten.
 
   Notice that all functions are allowed to overwrite the match data
 unless they're explicitly documented not to do so.  A consequence is
-that functions that are run implictly in the background
+that functions that are run implicitly in the background
 (@pxref{Timers}, and @ref{Idle Timers}) should likely save and restore
 the match data explicitly.
 
diff --git a/doc/lispref/spellfile b/doc/lispref/spellfile
index e66dcc88f71..5c0a6d0f5ea 100644
--- a/doc/lispref/spellfile
+++ b/doc/lispref/spellfile
@@ -376,7 +376,6 @@ inserting'
 integerp
 intermixed
 ints
-inturned
 irreversibly
 jum
 keymapp
@@ -530,7 +529,6 @@ pointer'
 pointm
 pos
 preallocate
-predicale
 preload
 prepend
 prepended
@@ -641,7 +639,7 @@ suspension'
 symbolp
 symlink
 syms
-syntatic
+syntactic
 tabname
 temacs
 temporarily'
diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index 8c99a06909b..bb1b0524689 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -110,6 +110,7 @@ including for the case where @var{object} is a deleted window.
 @end defun
 
 @cindex selected window
+@cindex window selected within a frame
   In each frame, at any time, exactly one Emacs window is designated
 as @dfn{selected within the frame}.  For the selected frame, that
 window is called the @dfn{selected window}---the one in which most
@@ -148,10 +149,10 @@ the minibuffer window in the returned list.  If @var{minibuffer} is
 active.  If @var{minibuffer} is neither @code{nil} nor @code{t}, the
 minibuffer window is never included.
 
-The optional argument @var{window}, if non-@code{nil}, should be a
-live window on the specified frame; then @var{window} will be the
-first element in the returned list.  If @var{window} is omitted or
-@code{nil}, the window selected within the frame is first element.
+The optional argument @var{window}, if non-@code{nil}, should be a live
+window on the specified frame; then @var{window} will be the first
+element in the returned list.  If @var{window} is omitted or @code{nil},
+the window selected within the frame is the first element.
 @end defun
 
 @cindex window tree
@@ -634,9 +635,9 @@ 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-limit status of the involved windows; in some cases, it may
-alter both edges.  @xref{Splitting Windows}.  To resize by moving only
-the bottom or right edge of a window, use the function
+combination limits of the involved windows; in some cases, it may alter
+both edges.  @xref{Splitting 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
 
@@ -774,22 +775,24 @@ properties from it, including margins and scroll bars.  If
 @var{window} is an internal window, the new window inherits the
 properties of the window selected within @var{window}'s frame.
 
-If the variable @code{ignore-window-parameters} is non-@code{nil}
-(@pxref{Window Parameters}), this function ignores window parameters.
-Otherwise, it consults the @code{split-window} parameter of
-@var{window}; if this is @code{t}, it splits the window disregarding
-any other window parameters.  If the @code{split-window} parameter
-specifies a function, that function is called with the arguments
-@var{window}, @var{size}, and @var{side} to split @var{window}, in
-lieu of the usual action of @code{split-window}.
+The behavior of this function may be altered by the window parameters
+of @var{window}, so long as the variable
+@code{ignore-window-parameters} is non-@code{nil}.  If the value of
+the @code{split-window} window parameter is @code{t}, this function
+ignores all other window parameters.  Otherwise, if the value of the
+@code{split-window} window parameter is a function, that function is
+called with the arguments @var{window}, @var{size}, and @var{side}, in
+lieu of the usual action of @code{split-window}.  Otherwise, this
+function obeys the @code{window-atom} or @code{window-side} window
+parameter, if any.  @xref{Window Parameters}.
 @end deffn
 
-  As an example, we show a combination of @code{split-window} calls
-that yields the window configuration discussed in @ref{Windows and
-Frames}.  This example demonstrates splitting a live window as well as
-splitting an internal window.  We begin with a frame containing a
-single window (a live root window), which we denote by @var{W4}.
-Calling @code{(split-window W3)} yields this window configuration:
+  As an example, here is a sequence of @code{split-window} calls that
+yields the window configuration discussed in @ref{Windows and Frames}.
+This example demonstrates splitting a live window as well as splitting
+an internal window.  We begin with a frame containing a single window
+(a live root window), which we denote by @var{W4}.  Calling
+@code{(split-window W4)} yields this window configuration:
 
 @smallexample
 @group
@@ -841,9 +844,6 @@ 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.
 
-  The following two options can be used to modify the operation of
-@code{split-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
@@ -854,18 +854,17 @@ If this variable is non-@code{nil}, @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.
-
-Also if this variable is non-@code{nil}, subsequent resizing and
-deleting @var{window} will usually affect @emph{all} windows in
-@var{window}'s combination.
+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 setting of this variable has no effect if
-@code{window-combination-limit} (see below) is non-@code{nil}.
+This variable has no effect if @code{window-combination-limit} is
+non-@code{nil} (see below).
 @end defopt
 
-To illustrate the use of @code{window-combination-resize} consider the
-following window configuration:
+  To illustrate the effect of @code{window-combination-resize},
+consider the following window configuration:
+
 @smallexample
 @group
      ______________________________________
@@ -886,9 +885,10 @@ following window configuration:
 @end group
 @end smallexample
 
-Splitting window @code{W3} with @code{window-combination-resize}
-@code{nil} produces a configuration where the size of @code{W2} remains
-unchanged:
+@noindent
+If @code{window-combination-resize} is @code{nil}, splitting window
+@code{W3} leaves the size of @code{W2} unchanged:
+
 @smallexample
 @group
      ______________________________________
@@ -909,8 +909,11 @@ unchanged:
 @end group
 @end smallexample
 
-Splitting @code{W3} with @code{window-combination-resize} non-@code{nil}
-instead steals the space for @code{W4} from both @code{W2} and @code{W3}:
+@noindent
+If @code{window-combination-resize} is non-@code{nil}, splitting
+@code{W3} instead leaves all three live windows with approximately the
+same height:
+
 @smallexample
 @group
      ______________________________________
@@ -932,53 +935,51 @@ instead steals the space for @code{W4} from both @code{W2} and @code{W3}:
 @end smallexample
 
 @defopt window-combination-limit
-If this variable is @code{nil}, @code{split-window} creates a new parent
-window if and only if the old window has no parent window or shall be
-split orthogonally to the combination it is part of.  If this variable
-is @code{t}, @code{split-window} always creates a new parent window.  If
-this variable is always @code{t}, a frame's window tree is a binary tree
-so every window but the frame's root window has exactly one sibling.
-Other values are reserved for future use.
-
-The value of this variable is also assigned to the combination-limit
-status of the new parent window.  The combination-limit status of any
-window can be retrieved via the function @code{window-combination-limit}
-and altered by the function @code{set-window-combination-limit}, see
-below.
+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
+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 is always @code{t}, each window tree is a binary
+tree: 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).
 @end defopt
 
-@defun window-combination-limit &optional window
-This function returns the combination-limit status of @var{window}.  The
-argument @var{window} can be any window and defaults to the selected
-one.  Note, however, that the combination-limit status is currently
-meaningful for internal windows only.
-
-@cindex combination-limit status
-The @dfn{combination-limit status} of a window specifies whether that
-window may be removed and its child windows recombined with that
-window's siblings when such a sibling's child window is deleted.  The
-combination-limit status is initially assigned by @code{split-window}
-from the current value of the variable @code{window-combination-limit}
-(see above) and can be reset by the function
-@code{set-window-combination-limit} (see below).
-
-If the return value is @code{nil}, child windows of @var{window} may be
-recombined with @var{window}'s siblings when a window gets deleted.  A
-return value of @code{nil} means that child windows of @var{window} are
-never (re-)combined with @var{window}'s siblings in such a case.
-@end defun
-
-@defun set-window-combination-limit window &optional status
-This functions sets the combination-limit status (see above) of
-@var{window} to @var{status}.  The argument @var{window} can be any
-window and defaults to the selected one.  Note that setting the
-combination-limit status is meaningful for internal windows only.  The
-return value is @var{status}.
-@end defun
-
-To illustrate the use of @code{window-combination-limit} consider the
-following configuration (throughout the following examples we shall
-assume that @code{window-combination-resize} invariantly is @code{nil}).
+@cindex window combination limit
+@defun set-window-combination-limit window limit
+This functions sets the @dfn{combination limit} of the window
+@var{window} to @var{limit}.  This value can be retrieved via the
+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}.
+@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
+@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
+siblings.
+@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}):
+
 @smallexample
 @group
      ______________________________________
@@ -999,31 +1000,10 @@ assume that @code{window-combination-resize} invariantly is @code{nil}).
 @end group
 @end smallexample
 
-Splitting @code{W2} into two windows above each other with
-@code{window-combination-limit} equal @code{nil} will get you a
-configuration like:
-@smallexample
-@group
-     ______________________________________
-    | ____________________________________ |
-    ||                                    ||
-    ||                                    ||
-    ||_________________W2_________________||
-    | ____________________________________ |
-    ||                                    ||
-    ||                                    ||
-    ||_________________W4_________________||
-    | ____________________________________ |
-    ||                                    ||
-    ||                                    ||
-    ||_________________W3_________________||
-    |__________________W1__________________|
-
-@end group
-@end smallexample
+@noindent
+If @code{window-combination-limit} is @code{nil}, splitting @code{W2}
+into two windows, one above the other, yields
 
-If you now enlarge window @code{W4}, Emacs steals the necessary space
-from window @code{W3} resulting in a configuration like:
 @smallexample
 @group
      ______________________________________
@@ -1034,43 +1014,24 @@ from window @code{W3} resulting in a configuration like:
     | ____________________________________ |
     ||                                    ||
     ||                                    ||
-    ||                                    ||
     ||_________________W4_________________||
     | ____________________________________ |
     ||                                    ||
+    ||                                    ||
     ||_________________W3_________________||
     |__________________W1__________________|
 
 @end group
 @end smallexample
 
-Deleting window @code{W4}, will return its space to @code{W2} as
-follows:
-@smallexample
-@group
-     ______________________________________
-    | ____________________________________ |
-    ||                                    ||
-    ||                                    ||
-    ||                                    ||
-    ||                                    ||
-    ||                                    ||
-    ||                                    ||
-    ||                                    ||
-    ||_________________W2_________________||
-    | ____________________________________ |
-    ||                                    ||
-    ||_________________W3_________________||
-    |__________________W1__________________|
+@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}.
 
-@end group
-@end smallexample
+  If @code{window-combination-limit} is @code{t}, splitting @code{W2}
+in the initial configuration would instead have produced this:
 
-Hence, with respect to the initial configuration, window @code{W2} has
-grown at the expense of window @code{W3}.  If, however, in the initial
-configuration you had split @code{W2} with
-@code{window-combination-limit} bound to @code{t}, a new internal window
-@code{W5} would have been created as depicted below.
 @smallexample
 @group
      ______________________________________
@@ -1091,143 +1052,110 @@ configuration you had split @code{W2} with
 @end group
 @end smallexample
 
-Enlarging @code{W4} would now have stolen the necessary space from
-@code{W2} instead of @code{W3} as
-@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 resizing @code{W4} will resize
+@code{W2}, leaving @code{W3} unaffected.
 
-and the subsequent deletion of @code{W4} would have restored the initial
-configuration.
+  For interactive use, Emacs provides two commands which always split
+the selected window.  These call @code{split-window} internally.
 
-For interactive use, Emacs provides two commands which always split the
-selected window.
+@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 of the two windows selected, with @var{size}
-lines.  (If @var{size} is negative, then the lower of the two windows
-gets @minus{}@var{size} lines and the upper window gets the rest, but
-the upper window is still the one selected.)  However, if
-@code{split-window-keep-point} (see below) is @code{nil}, then either
-window can be selected.
-
-   In other respects, this function is similar to @code{split-window}.
-In particular, the upper window is the original one and the return value
-is the new, lower window.
+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 this variable is non-@code{nil} (the default), then
+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}, then @code{split-window-below} adjusts point
-in each of the two windows to avoid scrolling.  (This is useful on
-slow terminals.)  It selects whichever window contains the screen line
-that point was previously on.  Other functions are not affected by
-this variable.
+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
 
-@deffn Command split-window-right &optional size
-This function splits the selected window into two windows
-side-by-side, leaving the selected window on the left with @var{size}
-columns.  If @var{size} is negative, the rightmost window gets
-@minus{}@var{size} columns, but the leftmost window still remains
-selected.
-@end deffn
-
-
 @node Deleting Windows
 @section Deleting Windows
 @cindex deleting windows
 
-A window remains visible on its frame unless you @dfn{delete} it by
-calling certain functions that delete windows.  A deleted window cannot
-appear on the screen, but continues to exist as a Lisp object until
-there are no references to it.  There is no way to cancel the deletion
-of a window aside from restoring a saved window configuration
-(@pxref{Window Configurations}).  Restoring a window configuration also
-deletes any windows that aren't part of that configuration.  Erroneous
-information may result from using a deleted window as if it were live.
+  @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.
 
-@deffn Command delete-window &optional window
-This function removes @var{window} from display and returns @code{nil}.
-The argument @var{window} can denote any window and defaults to the
-selected one.  An error is signaled if @var{window} is the only window
-on its frame.  Hence @var{window} must have at least one sibling window
-(@pxref{Windows and Frames}) in order to get deleted.  If @var{window}
-is the selected window on its frame, this function selects the most
-recently selected live window on that frame instead.
-
-If the variable @code{ignore-window-parameters} (@pxref{Window
-Parameters}) is non-@code{nil}, this function ignores all parameters of
-@var{window}.  Otherwise, if the @code{delete-window} parameter of
-@var{window} is @code{t}, it deletes the window disregarding other
-window parameters.  If the @code{delete-window} parameter specifies a
-function, that function is called with @var{window} as its sole
-argument.
+  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}).
 
-If @code{window-combination-resize} (@pxref{Splitting Windows}) is
-@code{nil}, the space @var{window} took up is given to its left sibling
-if such a window exists and to its right sibling otherwise.  If
-@code{window-combination-resize} is non-@code{nil}, the space of
-@var{window} is proportionally distributed among the remaining windows
-in the same combination.
+@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 non-@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 and returns @code{nil}.
-The argument @var{window} can denote an arbitrary window and defaults to
-the selected one.  Upon exit, @var{window} will be the selected window
-on its frame.
-
-If the variable @code{ignore-window-parameters} (@pxref{Window
-Parameters}) is non-@code{nil}, this function ignores all parameters of
-@var{window}.  Otherwise, if the @code{delete-other-windows} parameter
-of @var{window} equals @code{t}, it deletes all other windows
-disregarding any remaining window parameters.  If the
-@code{delete-other-windows} parameter of @var{window} specifies a
-function, it calls that function with @var{window} as its sole argument.
+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 non-@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}.  If
-there are no windows showing @var{buffer-or-name}, it does nothing.
-The optional argument @var{buffer-or-name} may be a buffer or the name
-of an existing buffer and defaults to the current buffer.  Invoking
-this command on a minibuffer signals an error.
-
-The function @code{delete-windows-on} operates by calling
-@code{delete-window} for each window showing @var{buffer-or-name}.  If a
-frame has several windows showing different buffers, then those showing
-@var{buffer-or-name} are removed, and the other windows expand to fill
-the space.
-
-If all windows in some frame are showing @var{buffer-or-name} (including
-the case where there is only one window), then that frame is deleted
-provided there are other frames left.
-
-The optional argument @var{frame} specifies which frames to operate on.
-This function does not use it in quite the same way as the other
-functions which scan all live windows (@pxref{Cyclic Window Ordering});
-specifically, the values @code{t} and @code{nil} have the opposite of
-their meanings in the other functions.  Here are the full details:
+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}
@@ -1241,34 +1169,37 @@ means operate on all visible or iconified frames.
 @item A frame
 means operate on that frame.
 @end itemize
-@end deffn
 
+Note that this argument does not have the same meaning as in other
+functions which scan all live windows (@pxref{Cyclic Window
+Ordering}).  Specifically, the values @code{t} and @code{nil} have the
+opposite of their meanings in those other functions.
+@end deffn
 
 @node Selecting Windows
 @section Selecting Windows
 @cindex selecting a window
 
 @defun select-window window &optional norecord
-This function makes @var{window} the selected window, see @ref{Basic
-Windows}.  Unless @var{window} already is the selected window, this also
-makes @var{window}'s buffer (@pxref{Buffers and Windows}) the current
-buffer.  Moreover, the cursor for selected windows will be displayed in
-@var{window} after the next redisplay.  This function returns
-@var{window}.
+This function makes @var{window} the selected window, as well as the
+window selected within its frame (@pxref{Basic Windows}).
+@var{window} must be a live window.  Unless @var{window} already is the
+selected window, its buffer becomes the current buffer (@pxref{Buffers
+and Windows}).  The return value is @var{window}.
 
-Normally, @var{window}'s selected buffer is moved to the front of the
-buffer list (@pxref{The Buffer List}) and @var{window} becomes the most
-recently selected window.  But if the optional argument @var{norecord}
-is non-@code{nil}, the buffer list remains unchanged and @var{window}
-does not become the most recently selected one.
+By default, this function also moves @var{window}'s selected buffer to
+the front of the buffer list (@pxref{The Buffer List}), and makes
+@var{window} the most recently selected window.  However, if the
+optional argument @var{norecord} is non-@code{nil}, these additional
+actions are omitted.
 @end defun
 
 @cindex most recently selected windows
-The sequence of calls to @code{select-window} with a non-@code{nil}
+  The sequence of calls to @code{select-window} with a non-@code{nil}
 @var{norecord} argument determines an ordering of windows by their
 selection time.  The function @code{get-lru-window} can be used to
-retrieve the least recently selected live window in this ordering, see
-@ref{Cyclic Window Ordering}.
+retrieve the least recently selected live window (@pxref{Cyclic Window
+Ordering}).
 
 @defmac save-selected-window forms@dots{}
 This macro records the selected frame, as well as the selected window
@@ -1300,33 +1231,26 @@ The order of recently selected windows and the buffer list are not
 changed by this macro.
 @end defmac
 
-@cindex frame selected window
-@cindex window selected within frame
-Earlier (@pxref{Basic Windows}) we mentioned that at any time, exactly
-one window on any frame is selected within the frame.  The significance
-of this designation is that selecting the frame also selects this
-window.  Conversely, selecting a window for Emacs with
-@code{select-window} also makes that window selected within its frame.
-
-@defun frame-selected-window  &optional frame
-This function returns the window on @var{frame} that is selected within
-@var{frame}.  The optional argument @var{frame} must denote a live frame
-and defaults to the selected one.
+@defun frame-selected-window &optional frame
+This function returns the window on @var{frame} that is selected
+within that frame.  @var{frame} should be a live frame; if omitted or
+@code{nil}, it defaults to the selected frame.
 @end defun
 
 @defun set-frame-selected-window frame window &optional norecord
-This function sets the selected window of frame @var{frame} to
-@var{window}.  The argument @var{frame} must denote a live frame and
-defaults to the selected one.  If @var{frame} is the selected frame,
-this also makes @var{window} the selected window.  The argument
-@var{window} must denote a live window.  This function returns
-@var{window}.
+This function makes @code{window} the window selected within the frame
+@var{frame}.  @var{frame} should be a live frame; if omitted or
+@code{nil}, it defaults to the selected frame.  @var{window} should be
+a live window; if omitted or @code{nil}, it defaults to the selected
+window.
 
-Optional argument @var{norecord} non-@code{nil} means to neither change
-the list of most recently selected windows (@pxref{Selecting Windows})
-nor the buffer list (@pxref{The Buffer List}).
-@end defun
+If @var{frame} is the selected frame, this makes @var{window} the
+selected window.
 
+If the optional argument @var{norecord} is non-@code{nil}, this
+function does not alter the list of most recently selected windows,
+nor the buffer list.
+@end defun
 
 @node Cyclic Window Ordering
 @section Cyclic Ordering of Windows
@@ -1334,28 +1258,22 @@ nor the buffer list (@pxref{The Buffer List}).
 @cindex ordering of windows, cyclic
 @cindex window ordering, cyclic
 
-When you use the command @kbd{C-x o} (@code{other-window}) to select
+  When you use the command @kbd{C-x o} (@code{other-window}) to select
 some other window, it moves through live windows in a specific order.
-For any given configuration of windows, this order never varies.  It is
-called the @dfn{cyclic ordering of windows}.
-
-   For a particular frame, this ordering is determined by the window
-tree of that frame, see @ref{Windows and Frames}.  More precisely, the
-ordering is obtained by a depth-first traversal of the frame's window
-tree supplemented, if requested, by the frame's minibuffer window.
+For any given configuration of windows, this order never varies.  It
+is called the @dfn{cyclic ordering of windows}.
 
-   If there's just one live frame, the cyclic ordering is the ordering
-for that frame.  Otherwise, the cyclic ordering is obtained by appending
-the orderings for individual frames in order of the list of all live
-frames, @ref{Finding All Frames}.  In any case, the ordering is made
-``cyclic'' by having the last window precede the first window in the
-ordering.
+  The ordering is determined by a depth-first traversal of the frame's
+window tree, retrieving the live windows which are the leaf nodes of
+the tree (@pxref{Windows and Frames}).  If the minibuffer is active,
+the minibuffer window is included too.  The ordering is cyclic, so the
+last window in the sequence is followed by the first one.
 
 @defun next-window &optional window minibuf all-frames
 @cindex minibuffer window, and @code{next-window}
-This function returns the window following @var{window} in the cyclic
-ordering of windows.  The argument @var{window} must specify a live
-window and defaults to the selected one.
+This function returns a live window, the one following @var{window} in
+the cyclic ordering of windows.  @var{window} should be a live window;
+if omitted or @code{nil}, it defaults to the selected window.
 
 The optional argument @var{minibuf} specifies whether minibuffer windows
 shall be included in the cyclic ordering.  Normally, when @var{minibuf}
@@ -1369,139 +1287,100 @@ minibuffer windows.  If @var{minibuf} is neither @code{t} nor
 @code{nil}, minibuffer windows are not included even if they are active.
 
 The optional argument @var{all-frames} specifies which frames to
-consider.  Here are the possible values and their meanings:
+consider:
 
 @itemize @bullet
 @item @code{nil}
-means consider all windows on @var{window}'s frame, plus the minibuffer
-window used by that frame even if it lies in some other frame.  If the
-minibuffer counts (as determined by @var{minibuf}), then all windows on
-all frames that share that minibuffer count too.
+means to consider windows on @var{window}'s frame.  If the minibuffer
+window is considered (as specified by the @var{minibuf} argument),
+then frames that share the minibuffer window are considered too.
 
 @item @code{t}
-means consider all windows on all existing frames.
+means to consider windows on all existing frames.
 
 @item @code{visible}
-means consider all windows on all visible frames.  (To get useful
-results, ensure that @var{window} is on a visible frame.)
+means to consider windows on all visible frames.
 
 @item 0
-means consider all windows on all visible or iconified frames.
+means to consider windows on all visible or iconified frames.
 
 @item A frame
-means consider all windows on that frame.
+means to consider windows on that specific frame.
 
 @item Anything else
-means consider the windows on @var{window}'s frame, and no others.
+means to consider windows on @var{window}'s frame, and no others.
 @end itemize
 
-This example assumes there are two windows, both displaying the
-buffer @samp{windows.texi}:
-
-@example
-@group
-(selected-window)
-     @result{} #<window 56 on windows.texi>
-@end group
-@group
-(next-window (selected-window))
-     @result{} #<window 52 on windows.texi>
-@end group
-@group
-(next-window (next-window (selected-window)))
-     @result{} #<window 56 on windows.texi>
-@end group
-@end example
+If more than one frame is considered, the cyclic ordering is obtained
+by appending the orderings for those frames, in the same order as the
+list of all live frames (@pxref{Finding All Frames}).
 @end defun
 
 @defun previous-window &optional window minibuf all-frames
-This function returns the window preceding @var{window} in the cyclic
-ordering of windows.  The other arguments specify which windows to
-consider as in @code{next-window}.
+This function returns a live window, the one preceding @var{window} in
+the cyclic ordering of windows.  The other arguments are handled like
+in @code{next-window}.
 @end defun
 
 @deffn Command other-window count &optional all-frames
-This function selects another window in the cyclic ordering of windows.
-@var{count} specifies the number of windows to skip in the ordering,
-starting with the selected window, before making the selection.  If
-@var{count} is a positive number, it skips @var{count} windows forwards.
-@var{count} negative means skip @minus{}@var{count} windows backwards.
-If @var{count} is zero, it does not skip any window, thus re-selecting
-the selected window.  In an interactive call, @var{count} is the numeric
-prefix argument.
+This function selects a live window, one @var{count} places from the
+selected window in the cyclic ordering of windows.  If @var{count} is
+a positive number, it skips @var{count} windows forwards; if
+@var{count} is negative, it skips @minus{}@var{count} windows
+backwards; if @var{count} is zero, that simply re-selects the selected
+window.  When called interactively, @var{count} is the numeric prefix
+argument.
 
 The optional argument @var{all-frames} has the same meaning as in
-@code{next-window}, but the @var{minibuf} argument of @code{next-window}
-is always effectively @code{nil}.  This function returns @code{nil}.
+@code{next-window}, like a @code{nil} @var{minibuf} argument to
+@code{next-window}.
 
 This function does not select a window that has a non-@code{nil}
 @code{no-other-window} window parameter (@pxref{Window Parameters}).
 @end deffn
 
-The following function returns a copy of the list of windows in the
-cyclic ordering.
+@defun walk-windows fun &optional minibuf all-frames
+This function calls the function @var{fun} once for each live window,
+with the window as the argument.
 
-@defun window-list-1 &optional window &optional minibuf &optional all_frames
-This function returns a list of live windows.  The optional arguments
-@var{minibuf} and @var{all-frames} specify the set of windows to include
-in the list.  See the description of @code{next-window} for details.
+It follows the cyclic ordering of windows.  The optional arguments
+@var{minibuf} and @var{all-frames} specify the set of windows
+included; these have the same arguments as in @code{next-window}.  If
+@var{all-frames} specifies a frame, the first window walked is the
+first window on that frame (the one returned by
+@code{frame-first-window}), not necessarily the selected window.
 
-The optional argument @var{window} specifies the first window to list
-and defaults to the selected window.  If @var{window} is not on the list
-of windows returned, some other window will be listed first but no error
-is signaled.
+If @var{fun} changes the window configuration by splitting or deleting
+windows, that does not alter the set of windows walked, which is
+determined prior to calling @var{fun} for the first time.
 @end defun
 
-The functions described below use @code{window-list-1} for generating a
-copy of the list of all relevant windows.  Hence, any change of the
-window configuration that occurs while one of these functions is
-executed is @emph{not} reflected in the list of windows investigated.
-
-@defun walk-windows proc &optional minibuf all-frames
-This function cycles through live windows.  It calls the function
-@var{proc} once for each window, with the window as its sole argument.
-
-The optional arguments @var{minibuf} and @var{all-frames} specify the
-set of windows to include in the walk, see @code{next-window} above.  If
-@var{all-frames} specifies a frame, the first window walked is the first
-window on that frame as returned by @code{frame-first-window} and not
-necessarily the selected window.
-
-If @var{proc} changes the window configuration by splitting or deleting
-windows, that change is not reflected in the set of windows walked.
-That set is determined entirely by the set of live windows at the time
-this function was invoked.
-@end defun
-
-The following function allows to determine whether a specific window is
-the only live window.
-
 @defun one-window-p &optional no-mini all-frames
-This function returns non-@code{nil} if the selected window is the only
-window.
+This function returns @code{t} if the selected window is the only live
+window, and @code{nil} otherwise.
 
-The optional argument @var{no-mini}, if non-@code{nil}, means don't
-count the minibuffer even if it is active; otherwise, the minibuffer
-window is counted when it is active.  The optional argument
-@var{all-frames} has the same meaning as for @code{next-window}, see
-above.
+If the minibuffer window is active, it is normally considered (so that
+this function returns @code{nil}).  However, if the optional argument
+@var{no-mini} is non-@code{nil}, the minibuffer window is ignored even
+if active.  The optional argument @var{all-frames} has the same
+meaning as for @code{next-window}.
 @end defun
 
 @cindex finding windows
-  The following functions choose (but do not select) one of the windows
-on the screen, offering various criteria for the choice.
+  The following functions return a window which satisfies some
+criterion, without selecting it:
 
 @cindex least recently used window
 @defun get-lru-window &optional all-frames dedicated
-This function returns the window least recently ``used'' (that is,
-selected).  If any full-width windows are present, it only considers
-these.  The optional argument @var{all-frames} has the same meaning as
-in @code{next-window}.
+This function returns a live window which is heuristically the ``least
+recently used'' window.  The optional argument @var{all-frames} has
+the same meaning as in @code{next-window}.
 
-The selected window is returned if it is the only candidate.  A
-minibuffer window is never a candidate.  A dedicated window
-(@pxref{Dedicated Windows}) is never a candidate unless the optional
-argument @var{dedicated} is non-@code{nil}.
+If any full-width windows are present, only those windows are
+considered.  The selected window is never returned, unless it is the
+only candidate.  A minibuffer window is never a candidate.  A
+dedicated window (@pxref{Dedicated Windows}) is never a candidate
+unless the optional argument @var{dedicated} is non-@code{nil}.
 @end defun
 
 @cindex largest window
@@ -1515,22 +1394,23 @@ If there are two candidate windows of the same size, this function
 prefers the one that comes first in the cyclic ordering of windows,
 starting from the selected window.
 
-The optional argument @var{all-frames} specifies which set of windows to
-consider as with @code{next-window}, see above.
+The optional argument @var{all-frames} specifies the windows to
+search, and has the same meaning as in @code{next-window}.
 @end defun
 
 @cindex window that satisfies a predicate
 @cindex conditional selection of windows
 @defun get-window-with-predicate predicate &optional minibuf all-frames default
-This function returns a window satisfying @var{predicate}.  It cycles
-through all visible windows calling @var{predicate} on each one of them
-with that window as its argument.  The function returns the first window
-for which @var{predicate} returns a non-@code{nil} value; if that never
-happens, it returns @var{default} (which defaults to @code{nil}).
+This function calls the function @var{predicate} for each of the
+windows in the cyclic order of windows in turn, passing it the window
+as an argument.  If the predicate returns non-@code{nil} for any
+window, this function stops and returns that window.  If no such
+window is found, the return value is @var{default} (which defaults to
+@code{nil}).
 
 The optional arguments @var{minibuf} and @var{all-frames} specify the
-set of windows to investigate.  See the description of
-@code{next-window} for details.
+windows to search, and have the same meanings as in
+@code{next-window}.
 @end defun
 
 @node Buffers and Windows
@@ -1539,47 +1419,41 @@ set of windows to investigate.  See the description of
 @cindex windows, controlling precisely
 @cindex buffers, controlled in windows
 
-To find out which buffer is displayed in a given window the following
-function is used.
+  This section describes low-level functions for examining and setting
+the contents of windows.  @xref{Switching Buffers}, for higher-level
+functions for displaying a specific buffer in a window.
 
 @defun window-buffer &optional window
-This function returns the buffer that @var{window} is displaying.  The
-argument @var{window} can be any window and defaults to the selected
-one.  If @var{window} is an internal window, this function returns
+This function returns the buffer that @var{window} is displaying.  If
+@var{window} is omitted or @code{nil} it defaults to the selected
+window.  If @var{window} is an internal window, this function returns
 @code{nil}.
 @end defun
 
-The basic, low-level function to associate a window with a buffer is
-@code{set-window-buffer}.  Higher-level functions like
-@code{switch-to-buffer} and @code{display-buffer} try to obey a number
-of user customizations regulating which windows are supposed to
-display which buffers.  @xref{Switching Buffers}.  When writing an
-application, you should avoid using @code{set-window-buffer} unless
-you are sure you need it.
-
 @defun set-window-buffer window buffer-or-name &optional keep-margins
-This function makes @var{window} display @var{buffer-or-name} and
-returns @code{nil}.  The argument @var{window} has to denote a live
-window and defaults to the selected one.  The argument
-@var{buffer-or-name} must specify a buffer or the name of an existing
-buffer.  An error is signaled when @var{window} is @dfn{strongly}
-dedicated to its buffer (@pxref{Dedicated Windows}) and does not already
-display @var{buffer-or-name}.
-
-Normally, displaying @var{buffer-or-name} in @var{window} resets the
-window's position, display margins, fringe widths, and scroll bar
-settings based on the local variables of the specified buffer.  However,
-if the optional argument @var{keep-margins} is non-@code{nil}, display
-margins and fringe widths of @var{window} remain unchanged.
-@xref{Fringes}.
-
-This function is the fundamental primitive for changing which buffer is
-displayed in a window, and all ways of doing that call this function.
-Neither the selected window nor the current buffer are changed by this
-function.
+This function makes @var{window} display @var{buffer-or-name}.
+@var{window} should be a live window; if @code{nil}, it defaults to
+the selected window.  @var{buffer-or-name} should be a buffer, or the
+name of an existing buffer.  This function does not change which
+window is selected, nor does it directly change which buffer is
+current (@pxref{Current Buffer}).  Its return value is @code{nil}.
 
-This function runs @code{window-scroll-functions} before running
-@code{window-configuration-change-hook}, see @ref{Window Hooks}.
+If @var{window} is @dfn{strongly dedicated} to a buffer and
+@var{buffer-or-name} does not specify that buffer, this function
+signals an error.  @xref{Dedicated Windows}.
+
+By default, this function resets @var{window}'s position, display
+margins, fringe widths, and scroll bar settings, based on the local
+variables in the specified buffer.  However, if the optional argument
+@var{keep-margins} is non-@code{nil}, it leaves the display margins
+and fringe widths unchanged.
+
+When writing an application, you should normally use the higher-level
+functions described in @ref{Switching Buffers}, instead of calling
+@code{set-window-buffer} directly.
+
+This function runs @code{window-scroll-functions}, followed by
+@code{window-configuration-change-hook}.  @xref{Window Hooks}.
 @end defun
 
 @defvar buffer-display-count
@@ -1589,28 +1463,26 @@ displayed in a window.  It is incremented each time
 @end defvar
 
 @defvar buffer-display-time
-This variable records the time at which a buffer was last made visible
-in a window.  It is always local in each buffer; each time
-@code{set-window-buffer} is called, it sets this variable to
-@code{(current-time)} in the specified buffer (@pxref{Time of Day}).
-When a buffer is first created, @code{buffer-display-time} starts out
-with the value @code{nil}.
+This buffer-local variable records the time at which a buffer was last
+displayed in a window.  The value is @code{nil} if the buffer has
+never been displayed.  It is updated each time
+@code{set-window-buffer} is called for the buffer, with the value
+returned by @code{current-time} (@pxref{Time of Day}).
 @end defvar
 
 @defun get-buffer-window &optional buffer-or-name all-frames
-This function returns a window displaying @var{buffer-or-name}, or
-@code{nil} if there is none.  If there are several such windows, then
-the function returns the first one in the cyclic ordering of windows,
-starting from the selected window, @xref{Cyclic Window Ordering}.
+This function returns the first window displaying @var{buffer-or-name}
+in the cyclic ordering of windows, starting from the selected window
+(@pxref{Cyclic Window Ordering}).  If no such window exists, the
+return value is @code{nil}.
 
-The argument @var{buffer-or-name} may be a buffer or a buffer name and
-defaults to the current buffer.  The optional argument @var{all-frames}
-specifies which windows to consider:
+@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.  The
+optional argument @var{all-frames} specifies which windows to
+consider:
 
 @itemize @bullet
 @item
-@code{nil} means consider windows on the selected frame.
-@item
 @code{t} means consider windows on all existing frames.
 @item
 @code{visible} means consider windows on all visible frames.
@@ -1618,44 +1490,45 @@ specifies which windows to consider:
 0 means consider windows on all visible or iconified frames.
 @item
 A frame means consider windows on that frame only.
+@item
+Any other value means consider windows on the selected frame.
 @end itemize
 
-Observe that the behavior of @code{get-buffer-window} may differ from
-that of @code{next-window} (@pxref{Cyclic Window Ordering}) when
-@var{all-frames} equals @code{nil} or any value not listed here.
-Perhaps we will change @code{get-buffer-window} in the future to make it
-compatible with the other functions.
+Note that these meanings differ slightly from those of the
+@var{all-frames} argument to @code{next-window} (@pxref{Cyclic Window
+Ordering}).  This function may be changed in a future version of Emacs
+to eliminate this discrepancy.
 @end defun
 
 @defun get-buffer-window-list &optional buffer-or-name minibuf all-frames
 This function returns a list of all windows currently displaying
-@var{buffer-or-name}.  The argument @var{buffer-or-name} may be a buffer
-or the name of an existing buffer and defaults to the current buffer.
+@var{buffer-or-name}.  @var{buffer-or-name} should be a buffer or the
+name of an existing buffer.  If omitted or @code{nil}, it defaults to
+the current buffer.
 
-The two remaining arguments work like the same-named arguments of
-@code{next-window} (@pxref{Cyclic Window Ordering}); they are @emph{not}
-like the optional arguments of @code{get-buffer-window}.
+The arguments @var{minibuf} and @var{all-frames} have the same
+meanings as in the function @code{next-window} (@pxref{Cyclic Window
+Ordering}).  Note that the @var{all-frames} argument does @emph{not}
+behave exactly like in @code{get-buffer-window}.
 @end defun
 
 @deffn Command replace-buffer-in-windows &optional buffer-or-name
 This command replaces @var{buffer-or-name} with some other buffer, in
-all windows displaying it.  For each such window, it choose another
-buffer using @code{switch-to-prev-buffer} (@pxref{Window History}).
-
-The argument @var{buffer-or-name} may be a buffer, or the name of an
-existing buffer; it defaults to the current buffer.
-
-If a window displaying @var{buffer-or-name} is dedicated
-(@pxref{Dedicated Windows}) and is not the only window on its frame,
-that window is deleted.  If that window is the only window on its frame
-and there are other frames on the frame's terminal, that frame is dealt
-with by the function specified by @code{frame-auto-hide-function}
-(@pxref{Quitting Windows}).  Otherwise, the buffer provided by the
-function @code{switch-to-prev-buffer} (@pxref{Window History}) is
-displayed in the window instead.
+all windows displaying it.  @var{buffer-or-name} should be a buffer,
+or the name of an existing buffer; if omitted or @code{nil}, it
+defaults to the current buffer.
+
+The replacement buffer in each window is chosen via
+@code{switch-to-prev-buffer} (@pxref{Window History}).  Any dedicated
+window displaying @var{buffer-or-name} is deleted (@pxref{Dedicated
+Windows}), unless it is the only window on its frame---if it is the
+only window, and that frame is not the only frame on its terminal, the
+frame is ``dismissed'' by calling the function specified by
+@code{frame-auto-hide-function} (@pxref{Quitting Windows}).  If the
+dedicated window is the only window on the only frame on its terminal,
+the buffer is replaced anyway.
 @end deffn
 
-
 @node Switching Buffers
 @section Switching to a Buffer in a Window
 @cindex switching to a buffer
@@ -1731,9 +1604,12 @@ The @var{buffer-or-name} and @var{norecord} arguments have the same
 meanings as in @code{switch-to-buffer}.
 @end deffn
 
-The above commands use @code{pop-to-buffer}, which is the function
-used by Lisp programs to flexibly display a buffer in some window and
-select that window for editing:
+The above commands use the function @code{pop-to-buffer}, which
+flexibly displays a buffer in some window and selects that window for
+editing.  In turn, @code{pop-to-buffer} uses @code{display-buffer} for
+displaying the buffer.  Hence, all the variables affecting
+@code{display-buffer} will affect it as well.  @xref{Choosing Window},
+for the documentation of @code{display-buffer}.
 
 @defun pop-to-buffer buffer-or-name &optional action norecord
 This function makes @var{buffer-or-name} the current buffer and
@@ -1743,10 +1619,6 @@ on a different graphical frame, that frame is given input focus if
 possible (@pxref{Input Focus}).  The return value is the buffer that
 was switched to.
 
-This function uses @code{display-buffer} to display the buffer, so all
-the variables affecting @code{display-buffer} will affect it as well.
-@xref{Choosing Window}.
-
 If @var{buffer-or-name} is @code{nil}, it defaults to the buffer
 returned by @code{other-buffer} (@pxref{The Buffer List}).  If
 @var{buffer-or-name} is a string that is not the name of any existing
@@ -1775,8 +1647,8 @@ used as a subroutine by many functions and commands, including
 Buffers}).
 
 @cindex display action
-@cindex action function, for display-buffer
-@cindex action alist, for display-buffer
+@cindex action function, for @code{display-buffer}
+@cindex action alist, for @code{display-buffer}
   This command performs several complex steps to find a window to
 display in.  These steps are described by means of @dfn{display
 actions}, which have the form @code{(@var{function} . @var{alist})}.
@@ -1815,6 +1687,11 @@ The variable @code{display-buffer-overriding-action}.
 The user option @code{display-buffer-alist}.
 
 @item
+A special action for handling @code{special-display-buffer-names} and
+@code{special-display-regexps}, if either of those variables is
+non-@code{nil}.  @xref{Choosing Window Options}.
+
+@item
 The @var{action} argument.
 
 @item
@@ -1886,10 +1763,9 @@ This function tries to ``display'' @var{buffer} by finding a window
 that is already displaying 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 reusable window:
+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 reusable window:
 
 @itemize @bullet
 @item
@@ -1910,17 +1786,28 @@ normally searches just the selected frame; however, if either the
 variable @code{display-buffer-reuse-frames} or the variable
 @code{pop-up-frames} is non-@code{nil}, it searches all frames on the
 current terminal.  @xref{Choosing Window Options}.
+
+If this function chooses a window on another frame, it makes that
+frame visible and raises it if necessary.
 @end defun
 
 @defun display-buffer-pop-up-frame buffer alist
 This function creates a new frame, and displays the buffer in that
-frame's window.
+frame's window.  It actually performs the frame creation by calling
+the function specified in @code{pop-up-frame-function}
+(@pxref{Choosing Window Options}).
 @end defun
 
 @defun display-buffer-pop-up-window buffer alist
 This function tries to display @var{buffer} by splitting the largest
-or least recently-used window.  It uses @code{split-window-sensibly}
-as a subroutine (@pxref{Choosing Window Options}).
+or least recently-used window (typically one on the selected frame).
+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}).
 @end defun
 
 @defun display-buffer-use-some-window buffer alist
@@ -1937,142 +1824,108 @@ The behavior of the standard display actions of @code{display-buffer}
 options.
 
 @defopt display-buffer-reuse-frames
-If this variable is non-@code{nil}, @code{display-buffer} searches
-visible and iconified frames for a window displaying
-@var{buffer-or-name}.  If there is such a window, @code{display-buffer}
-makes that window's frame visible and raises it if necessary, and
-returns the window.  If there is no such window or
-@code{display-buffer-reuse-frames} is @code{nil}, the behavior of
-@code{display-buffer} is determined by the variables described next.
+If the value of this variable is non-@code{nil}, @code{display-buffer}
+may search all frames on the current terminal when looking for a
+window already displaying the specified buffer.  The default is
+@code{nil}.  This variable is consulted by the action function
+@code{display-buffer-reuse-window} (@pxref{Display Action Functions}).
 @end defopt
 
 @defopt pop-up-windows
-This variable specifies whether @code{display-buffer} is allowed to
-split (@pxref{Splitting Windows}) an existing window.  If this variable
-is non-@code{nil}, @code{display-buffer} tries to split the largest or
-least recently used window on the selected frame.  (If the selected
-frame is a minibuffer-only frame, @code{display-buffer} tries to split a
-window on another frame instead.)  If this variable is @code{nil} or the
-variable @code{pop-up-frames} (see below) is non-@code{nil},
-@code{display-buffer} does not split any window.
+If the value of this variable is non-@code{nil}, @code{display-buffer}
+is allowed to split an existing window to make a new window for
+displaying in.  This is the default.
+
+This variable is provided mainly for backward compatibility.  It is
+obeyed by @code{display-buffer} via a special mechanism in
+@code{display-buffer-fallback-action}, which only calls the action
+function @code{display-buffer-pop-up-window} (@pxref{Display Action
+Functions}) when the value is @code{nil}.  It is not consulted by
+@code{display-buffer-pop-up-window} itself, which the user may specify
+directly in @code{display-buffer-alist} etc.
 @end defopt
 
 @defopt split-window-preferred-function
-This variable must specify a function with one argument, which is a
-window.  The @code{display-buffer} routines will call this function with
-one or more candidate windows when they look for a window to split.  The
-function is expected to split that window and return the new window.  If
-the function returns @code{nil}, this means that the argument window
-cannot (or shall not) be split.
-
-The default value of @code{split-window-preferred-function} is the
-function @code{split-window-sensibly} described below.  If you
-customize this option, bear in mind that the @code{display-buffer}
-routines may call your function up to two times when trying to split a
-window.  The argument of the first call is the largest window on the
-chosen frame (as returned by @code{get-largest-window}).  If that call
-fails to return a live window, your function is called a second time
-with the least recently used window on that frame (as returned by
-@code{get-lru-window}).
-
-The function specified by this option may try to split any other window
-instead of the argument window.  Note that the window selected at the
-time @code{display-buffer} was invoked is still selected when your
-function is called.  Hence, you can split the selected window (instead
-of the largest or least recently used one) by simply ignoring the window
-argument in the body of your function.  You can even choose to not split
-any window as long as the return value of your function specifies a live
-window or @code{nil}, but you are not encouraged to do so
-unconditionally.  If you want @code{display-buffer} to never split any
-windows, set @code{pop-up-windows} to @code{nil}.
+This variable specifies a function for splitting a window, in order to
+make a new window for displaying a buffer.  It is used by the
+@code{display-buffer-pop-up-window} action function to actually split
+the window (@pxref{Display Action Functions}).
+
+The default value is @code{split-window-sensibly}, which is documented
+below.  The value must be a function that takes one argument, a
+window, and return either a new window (which is used to display the
+desired buffer) or @code{nil} (which means the splitting failed).
 @end defopt
 
 @defun split-window-sensibly window
-This function takes a window as argument and tries to split that window
-in a suitable way.  The two variables described next are useful for
-tuning the behavior of this function.
+This function tries to split @code{window}, and return the newly
+created window.  If @code{window} cannot be split, it returns
+@code{nil}.
+
+This function obeys the usual rules that determine when a window may
+be split (@pxref{Splitting Windows}).  It first tries to split by
+placing the new window below, subject to the restriction imposed by
+@code{split-height-threshold} (see below) in addition to any other
+restrictions.  If that fails, it tries to split by placing the new
+window to the right, subject to @code{split-width-threshold} (see
+below).  If that fails, and the window is the only window on its
+frame, this function again tries to split and place the new window
+below, disregarding @code{split-height-threshold}.  If this fails as
+well, this function gives up and returns @code{nil}.
 @end defun
 
 @defopt split-height-threshold
-This variable specifies whether @code{split-window-sensibly} may split
-windows vertically.  If it is an integer, @code{split-window-sensibly}
-tries to vertically split a window only if it has at least this many
-lines.  If the window has less lines, splitting fails, or the value of
-this variable is @code{nil}, @code{split-window-sensibly} will try to
-split the window horizontally, subject to restrictions of
-@code{split-width-threshold} (see below).  If splitting horizontally
-fails too and the window is the only window on its frame,
-@code{split-window-sensibly} will try to split the window vertically
-disregarding the value of @code{split-height-threshold}.  If this fails
-as well, @code{split-window-sensibly} returns @code{nil}.
-
-@code{split-window-sensibly} does not split vertically a window whose
-height is fixed (@pxref{Resizing Windows}).  Also, it vertically splits
-a window only if the space taken up by that window can accommodate two
-windows one above the other that are both at least
-@code{window-min-height} lines tall.  Moreover, if the window that shall
-be split has a mode line, @code{split-window-sensibly} does not split
-the window unless the new window can accommodate a mode line too.
+This variable, used by @code{split-window-sensibly}, specifies whether
+to split the window placing the new window below.  If it is an
+integer, that means to split only if the original window has at least
+that many lines.  If it is @code{nil}, that means not to split this
+way.
 @end defopt
 
 @defopt split-width-threshold
-This variable specifies whether @code{split-window-sensibly} may split
-windows horizontally.  If it is an integer, @code{split-window-sensibly}
-tries to horizontally split a window only if it has at least this many
-columns.  If it is @code{nil}, @code{split-window-sensibly} will not
-split the window horizontally.  (It still might split the window
-vertically, though, see above.)
-
-@code{split-window-sensibly} does not split horizontally a window if
-that window's width is fixed (@pxref{Resizing Windows}).  Also, it
-horizontally splits a window only if the space that window takes up can
-accommodate two windows side by side that are both at least
-@code{window-min-width} columns wide.
+This variable, used by @code{split-window-sensibly}, specifies whether
+to split the window placing the new window to the right.  If the value
+is an integer, that means to split only if the original window has at
+least that many columns.  If the value is @code{nil}, that means not
+to split this way.
 @end defopt
 
-@defopt even-window-heights
-This variable specifies whether @code{display-buffer} should even out
-window heights if the buffer gets displayed in an existing window, above
-or beneath another window.  If @code{even-window-heights} is
-non-@code{nil}, the default, window heights will be evened out.  If
-either of the involved window has fixed height (@pxref{Resizing
-Windows}) or @code{even-window-heights} is @code{nil}, the original
-window heights will be left alone.
-@end defopt
-
-@c Emacs 19 feature
 @defopt pop-up-frames
-This variable specifies whether @code{display-buffer} should make new
-frames.  If it is non-@code{nil}, @code{display-buffer} looks for a
-window already displaying @var{buffer-or-name} on any visible or
-iconified frame.  If it finds such a window, it makes that window's
-frame visible and raises it if necessary, and returns the window.
-Otherwise it makes a new frame, unless the variable's value is
-@code{graphic-only} and the selected frame is not on a graphic display.
-@xref{Frames}, for more information.
-
-Note that the value of @code{pop-up-windows} does not matter if
-@code{pop-up-frames} is non-@code{nil}.  If @code{pop-up-frames} is
-@code{nil}, then @code{display-buffer} either splits a window or reuses
-one.
+If the value of this variable is non-@code{nil}, that means
+@code{display-buffer} may display buffers by making new frames.  The
+default is @code{nil}.
+
+A non-@code{nil} value also means that when @code{display-buffer} is
+looking for a window already displaying @var{buffer-or-name}, it can
+search any visible or iconified frame, not just the selected frame.
+
+This variable is provided mainly for backward compatibility.  It is
+obeyed by @code{display-buffer} via a special mechanism in
+@code{display-buffer-fallback-action}, which calls the action function
+@code{display-buffer-pop-up-frame} (@pxref{Display Action Functions})
+if the value is non-@code{nil}.  (This is done before attempting to
+split a window.)  This variable is not consulted by
+@code{display-buffer-pop-up-frame} itself, which the user may specify
+directly in @code{display-buffer-alist} etc.
 @end defopt
 
-@c Emacs 19 feature
 @defopt pop-up-frame-function
-This variable specifies how to make a new frame if @code{pop-up-frames}
-is non-@code{nil}.
-
-The value of this variable must be a function of no arguments.  When
-@code{display-buffer} makes a new frame, it does so by calling that
-function, which should return a frame.  The default value of this
-variable is a function that creates a frame using the parameters
-specified by @code{pop-up-frame-alist} described next.
+This variable specifies a function for creating a new frame, in order
+to make a new window for displaying a buffer.  It is used by the
+@code{display-buffer-pop-up-frame} action function (@pxref{Display
+Action Functions}).
+
+The value should be a function that takes no arguments and returns a
+frame, or @code{nil} if no frame could be created.  The default value
+is a function that creates a frame using the parameters specified by
+@code{pop-up-frame-alist} (see below).
 @end defopt
 
 @defopt pop-up-frame-alist
-This variable holds an alist specifying frame parameters used by the
-default value of @code{pop-up-frame-function} for making new frames.
-@xref{Frame Parameters}, for more information about frame parameters.
+This variable holds an alist of frame parameters (@pxref{Frame
+Parameters}), which is used by the default function in
+@code{pop-up-frame-function} to make a new frame.  The default is
+@code{nil}.
 @end defopt
 
 @defopt special-display-buffer-names
@@ -2193,12 +2046,6 @@ This variable takes precedence over all the other options described
 above.
 @end defopt
 
-If all options described above fail to produce a suitable window,
-@code{display-buffer} tries to reuse an existing window.  As a last
-resort, it will try to display @var{buffer-or-name} on a separate frame.
-In that case, the value of @code{pop-up-frames} is disregarded.
-
-
 @node Window History
 @section Window History
 @cindex window history