Window-related updates to NEWS and Emacs manual.

* etc/NEWS: Reorganize, placing user options in Changes section.

* doc/emacs/buffers.texi (Select Buffer): Clarify description of
buffer-switching commands.  Add xref to Window Display node.
Don't repeat confirm-nonexistent-file-or-buffer description from
Visiting node.  Remove even-window-heights.

* doc/emacs/frames.texi (Special Buffer Frames): Add xref to Window Choice.

* doc/emacs/windows.texi (Pop Up Window): Defer discussion of window
splitting to the Window Choice node.  Add index entries.
(Force Same Window): Node deleted.
(Displaying Buffers, Window Choice): New nodes.

6 files changed, 229 insertions, 141 deletions

diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog
index 163eabed2a6..ac913fc3264 100644
--- a/doc/emacs/ChangeLog
+++ b/doc/emacs/ChangeLog
@@ -1,3 +1,17 @@
+2011-09-24  Chong Yidong  <cyd@stupidchicken.com>
+
+        * windows.texi (Pop Up Window): Defer discussion of window
+        splitting to the Window Choice node.  Add index entries.
+        (Force Same Window): Node deleted.
+        (Displaying Buffers, Window Choice): New nodes.
+
+        * buffers.texi (Select Buffer): Clarify description of
+        buffer-switching commands.  Add xref to Window Display node.
+        Don't repeat confirm-nonexistent-file-or-buffer description from
+        Visiting node.  Remove even-window-heights.
+
+        * frames.texi (Special Buffer Frames): Add xref to Window Choice.
+
 2011-09-18  Chong Yidong  <cyd@stupidchicken.com>
 
         * cmdargs.texi (Icons X): Fix description of Emacs icon.
diff --git a/doc/emacs/buffers.texi b/doc/emacs/buffers.texi
index c4880af2b5d..b82f3fac7d4 100644
--- a/doc/emacs/buffers.texi
+++ b/doc/emacs/buffers.texi
@@ -91,9 +91,9 @@ selected buffer other than the current buffer.
 @var{bufname} @key{RET}}.  This runs the command
 @code{switch-to-buffer} with argument @var{bufname}.  While entering
 the buffer name, you can use the usual minibuffer completion and
-history commands (@pxref{Minibuffer}).  An empty argument to @kbd{C-x
-b} specifies the buffer that was current most recently among those not
-now displayed in any window.
+history commands (@pxref{Minibuffer}).  An empty input specifies the
+buffer that was current most recently among those not now displayed in
+any window.
 
 @cindex minibuffer confirmation
 @cindex confirming in the minibuffer
@@ -107,16 +107,8 @@ catches a common mistake, in which one types @key{RET} before
 realizing that @key{TAB} did not complete far enough to yield the
 desired buffer name (@pxref{Completion}).  Emacs asks for confirmation
 by putting the message @samp{[Confirm]} in the minibuffer; type
-@key{RET} again to confirm and visit the buffer.
-
-@vindex confirm-nonexistent-file-or-buffer
-  The variable @code{confirm-nonexistent-file-or-buffer} controls
-whether Emacs asks for confirmation before visiting a buffer that did
-not previously exist.  The default value, @code{after-completion},
-gives the behavior we have just described.  If the value is
-@code{nil}, Emacs never asks for confirmation; for any other
-non-@code{nil} value, Emacs always asks for confirmation.  This
-variable also affects the @code{find-file} command (@pxref{Visiting}).
+@key{RET} again to confirm and visit the buffer.  @xref{Visiting}, for
+information about modifying this behavior.
 
   One reason to create a new buffer is to use it for making temporary
 notes.  If you try to save it, Emacs asks for the file name to use.
@@ -136,36 +128,26 @@ of most recent selection in the current frame), while @kbd{C-x @key{LEFT}}
 
 @kindex C-x 4 b
 @findex switch-to-buffer-other-window
-@vindex even-window-heights
   To select a buffer in a window other than the current one, type
 @kbd{C-x 4 b} (@code{switch-to-buffer-other-window}).  This prompts
 for a buffer name using the minibuffer, displays that buffer in
-another window, and selects that window.  By default, if displaying
-the buffer causes two vertically adjacent windows to be displayed, the
-heights of those windows are evened out; to countermand that and
-preserve the window configuration, set the variable
-@code{even-window-heights} to @code{nil}.
+another window, and selects that window.
 
 @kindex C-x 5 b
 @findex switch-to-buffer-other-frame
   Similarly, @kbd{C-x 5 b} (@code{switch-to-buffer-other-frame})
 prompts for a buffer name, displays that buffer in another frame, and
-selects that frame.
+selects that frame.  If the buffer is already being shown in a window
+on another frame, Emacs selects that window and frame instead of
+creating a new frame.
+
+  @xref{Displaying Buffers}, for how the @kbd{C-x 4 b} and @kbd{C-x 5
+b} commands get the window and/or frame to display in.
 
   In addition, @kbd{C-x C-f}, and any other command for visiting a
 file, can also be used to switch to an existing file-visiting buffer.
 @xref{Visiting}.
 
-@vindex display-buffer-reuse-frames
-  You can control how certain buffers are handled by these commands by
-customizing the variables @code{special-display-buffer-names},
-@code{special-display-regexps}, @code{same-window-buffer-names}, and
-@code{same-window-regexps}.  See @ref{Force Same Window}, and
-@ref{Special Buffer Frames}, for more about these variables.  In
-addition, if the value of @code{display-buffer-reuse-frames} is
-non-@code{nil}, and the buffer you want to switch to is already
-displayed in some frame, Emacs will just raise that frame.
-
 @findex goto-line
   @kbd{C-u M-g M-g}, that is @code{goto-line} with a plain prefix
 argument, reads a number @var{n} using the minibuffer, selects the
diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi
index 2ba4af712af..bb675b61cff 100644
--- a/doc/emacs/emacs.texi
+++ b/doc/emacs/emacs.texi
@@ -488,9 +488,8 @@ Multiple Windows
 * Split Window::        New windows are made by splitting existing windows.
 * Other Window::        Moving to another window or doing something to it.
 * Pop Up Window::       Finding a file or buffer in another window.
-* Force Same Window::   Forcing certain buffers to appear in the selected
-                          window rather than in another window.
 * Change Window::       Deleting windows and changing their sizes.
+* Displaying Buffers::  How Emacs picks a window for displaying a buffer.
 * Window Convenience::  Convenience functions for window handling.
 
 Frames and Graphical Displays
diff --git a/doc/emacs/frames.texi b/doc/emacs/frames.texi
index 8ca598c3348..619252503a9 100644
--- a/doc/emacs/frames.texi
+++ b/doc/emacs/frames.texi
@@ -850,11 +850,12 @@ each others' edits if they are not careful.
 
 @vindex special-display-buffer-names
   You can make certain chosen buffers, which Emacs normally displays
-in ``another window,'' appear in special frames of their own.  To do
-this, set the variable @code{special-display-buffer-names} to a list
-of buffer names; any buffer whose name is in that list automatically
-gets a special frame, when an Emacs command wants to display it ``in
-another window.''
+in ``some other window'' (@pxref{Displaying Buffers}), appear in
+special frames of their own.  To do this, set the variable
+@code{special-display-buffer-names} to a list of buffer names; any
+buffer whose name is in that list automatically gets a special frame.
+@xref{Window Choice}, for how this fits in with the other ways for
+Emacs to choose a window to display in.
 
   For example, if you set the variable this way,
 
@@ -906,13 +907,6 @@ where @var{function} is a symbol.  Then the frame is constructed by
 calling @var{function}; its first argument is the buffer, and its
 remaining arguments are @var{args}.
 
-   An analogous feature lets you specify buffers which should be
-displayed in the selected window.  @xref{Force Same Window}.  The
-same-window feature takes precedence over the special-frame feature;
-therefore, if you add a buffer name to
-@code{special-display-buffer-names} and it has no effect, check to see
-whether that feature is also in use for the same buffer name.
-
 @node Frame Parameters
 @section Setting Frame Parameters
 @cindex Auto-Raise mode
diff --git a/doc/emacs/windows.texi b/doc/emacs/windows.texi
index 6aa8a06778b..dc92e4a519c 100644
--- a/doc/emacs/windows.texi
+++ b/doc/emacs/windows.texi
@@ -18,9 +18,8 @@ one frame.
 * Split Window::        New windows are made by splitting existing windows.
 * Other Window::        Moving to another window or doing something to it.
 * Pop Up Window::       Finding a file or buffer in another window.
-* Force Same Window::   Forcing certain buffers to appear in the selected
-                          window rather than in another window.
 * Change Window::       Deleting windows and changing their sizes.
+* Displaying Buffers::  How Emacs picks a window for displaying a buffer.
 * Window Convenience::  Convenience functions for window handling.
 @end menu
 
@@ -191,84 +190,47 @@ feature is off by default.
 
 @cindex selecting buffers in other windows
 @kindex C-x 4
-  @kbd{C-x 4} is a prefix key for commands that select another window
-(splitting the window if there is only one) and select a buffer in that
-window.  Different @kbd{C-x 4} commands have different ways of finding the
-buffer to select.
+  @kbd{C-x 4} is a prefix key for a variety of commands that switch to
+a buffer in a different window---either another existing window, or a
+new window created by splitting the selected window.  @xref{Window
+Choice}, for how Emacs picks or creates the window to use.
 
 @table @kbd
+@findex switch-to-buffer-other-window
 @item C-x 4 b @var{bufname} @key{RET}
-Select buffer @var{bufname} in another window.  This runs
-@code{switch-to-buffer-other-window}.
+Select buffer @var{bufname} in another window
+(@code{switch-to-buffer-other-window}).
+
+@findex display-buffer
 @item C-x 4 C-o @var{bufname} @key{RET}
-Display buffer @var{bufname} in another window, but
-don't select that buffer or that window.  This runs
-@code{display-buffer}.
+Display buffer @var{bufname} in some window, without trying to select
+it (@code{display-buffer}).  @xref{Displaying Buffers}, for details
+about how the window is chosen.
+
+@findex find-file-other-window
 @item C-x 4 f @var{filename} @key{RET}
-Visit file @var{filename} and select its buffer in another window.  This
-runs @code{find-file-other-window}.  @xref{Visiting}.
+Visit file @var{filename} and select its buffer in another window
+(@code{find-file-other-window}).  @xref{Visiting}.
+
+@findex dired-other-window
 @item C-x 4 d @var{directory} @key{RET}
-Select a Dired buffer for directory @var{directory} in another window.
-This runs @code{dired-other-window}.  @xref{Dired}.
+Select a Dired buffer for directory @var{directory} in another window
+(@code{dired-other-window}).  @xref{Dired}.
+
+@findex mail-other-window
 @item C-x 4 m
-Start composing a mail message in another window.  This runs
-@code{mail-other-window}; its same-window analogue is @kbd{C-x m}
-(@pxref{Sending Mail}).
+Start composing a mail message, similar to @kbd{C-x m} (@pxref{Sending
+Mail}), but in another window (@code{mail-other-window}).
+
+@findex find-tag-other-window
 @item C-x 4 .
-Find a tag in the current tags table, in another window.  This runs
-@code{find-tag-other-window}, the multiple-window variant of @kbd{M-.}
-(@pxref{Tags}).
+Find a tag in the current tags table, similar to @kbd{M-.}
+(@pxref{Tags}), but in another window (@code{find-tag-other-window}).
 @item C-x 4 r @var{filename} @key{RET}
 Visit file @var{filename} read-only, and select its buffer in another
-window.  This runs @code{find-file-read-only-other-window}.
-@xref{Visiting}.
+window (@code{find-file-read-only-other-window}).  @xref{Visiting}.
 @end table
 
-@vindex split-height-threshold
-@vindex split-width-threshold
-  By default, these commands split the window vertically when there is
-only one.  You can customize the variables @code{split-height-threshold}
-and @code{split-width-threshold} to split the window horizontally
-instead.
-
-
-@node Force Same Window
-@section Forcing Display in the Same Window
-
-  Certain Emacs commands switch to a specific buffer with special
-contents.  For example, @kbd{M-x shell} switches to a buffer named
-@samp{*shell*}.  By convention, all these commands are written to pop up
-the buffer in a separate window.  But you can specify that certain of
-these buffers should appear in the selected window.
-
-@vindex same-window-buffer-names
-  If you add a buffer name to the list @code{same-window-buffer-names},
-the effect is that such commands display that particular buffer by
-switching to it in the selected window.  For example, if you add the
-element @code{"*grep*"} to the list, the @code{grep} command will
-display its output buffer in the selected window.
-
-  The default value of @code{same-window-buffer-names} is not
-@code{nil}: it specifies buffer names @samp{*info*}, @samp{*mail*} and
-@samp{*shell*} (as well as others used by more obscure Emacs packages).
-This is why @kbd{M-x shell} normally switches to the @samp{*shell*}
-buffer in the selected window.  If you delete this element from the
-value of @code{same-window-buffer-names}, the behavior of @kbd{M-x
-shell} will change---it will pop up the buffer in another window
-instead.
-
-@vindex same-window-regexps
-  You can specify these buffers more generally with the variable
-@code{same-window-regexps}.  Set it to a list of regular expressions;
-then any buffer whose name matches one of those regular expressions is
-displayed by switching to it in the selected window.  (Once again, this
-applies only to buffers that normally get displayed for you in a
-separate window.)  The default value of this variable specifies Telnet
-and rlogin buffers.
-
-  An analogous feature lets you specify buffers which should be
-displayed in their own individual frames.  @xref{Special Buffer Frames}.
-
 @node Change Window
 @section Deleting and Rearranging Windows
 
@@ -356,6 +318,113 @@ heights of all the windows in the selected frame.
   Mouse clicks on the mode line provide another way to change window
 heights and to delete windows.  @xref{Mode Line Mouse}.
 
+@node Displaying Buffers
+@section Displaying a Buffer in a Window
+
+  It is a common Emacs operation to display or ``pop up'' some buffer
+in response to a user command.  There are several different ways by
+which commands do this.
+
+  Many commands, like @kbd{C-x C-f} (@code{find-file}), display the
+buffer by ``taking over'' the selected window, expecting that the
+user's attention will be diverted to that buffer.  These commands
+usually work by calling @code{switch-to-buffer} internally
+(@pxref{Select Buffer}).
+
+@findex display-buffer
+  Some commands try to display ``intelligently'', trying not to take
+over the selected window, e.g. by splitting the selected window and
+displaying the desired buffer in the child window.  Such commands,
+which include the various help commands (@pxref{Help}), work by
+calling @code{display-buffer} internally.  @xref{Window Choice}, for
+details.
+
+  Other commands do the same as @code{display-buffer}, and
+additionally select the displaying window so that you can begin
+editing its buffer.  The command @kbd{C-x `} (@code{next-error}) is
+one example (@pxref{Compilation Mode}).  Such commands work by calling
+@code{pop-to-buffer} internally.  @xref{Displaying Buffers,,Displaying
+Buffers in Windows, elisp, The Emacs Lisp Reference Manual}.
+
+  Commands with names ending in @code{-other-window} behave like
+@code{display-buffer}, except that they never display in the selected
+window.  Several of these commands are bound in the @kbd{C-x 4} prefix
+key (@pxref{Pop Up Window}).
+
+  Commands with names ending in @code{-other-frame} behave like
+@code{display-buffer}, except that they (i) never display in the
+selected window and (ii) prefer to create a new frame to display the
+desired buffer instead of splitting a window---as though the variable
+@code{pop-up-frames} is set to @code{t} (@pxref{Window Choice}).
+Several of these commands are bound in the @kbd{C-x 5} prefix key.
+
+@menu
+* Window Choice::   How @code{display-buffer} works.
+@end menu
+
+@node Window Choice
+@subsection How @code{display-buffer} works
+@findex display-buffer
+
+The @code{display-buffer} command (as well as commands that call it
+internally) chooses a window to display using the following steps:
+
+@itemize
+@vindex same-window-buffer-names
+@vindex same-window-regexps
+@item
+First, check if the buffer should be displayed in the selected window
+regardless of other considerations.  You can tell Emacs to do this by
+adding the desired buffer's name to the list
+@code{same-window-buffer-names}, or adding a matching regular
+expression to the list @code{same-window-regexps}.  By default, these
+variables are @code{nil}, so this step is skipped.
+
+@vindex display-buffer-reuse-frames
+@item
+Otherwise, if the buffer is already displayed in an existing window,
+``reuse'' that window.  Normally, only windows on the selected frame
+are considered, but windows on other frames are also reusable if you
+change @code{display-buffer-reuse-frames} to @code{t}, or if you
+change @code{pop-up-frames} (see below) to @code{t}.
+
+@item
+Otherwise, if you specified that the buffer should be displayed in a
+special frame by customizing @code{special-display-buffer-names} or
+@code{special-display-regexps}, do so.  @xref{Special Buffer Frames}.
+
+@vindex pop-up-frames
+@item
+Otherwise, optionally create a new frame and display the buffer there.
+By default, this step is skipped.  To enable it, change the variable
+@code{pop-up-frames} to a non-@code{nil} value.  The special value
+@code{graphic-only} means to do this only on graphical displays.
+
+@item
+Otherwise, try to create a new window by splitting the selected
+window, and display the buffer in that new window.
+
+@vindex split-height-threshold
+@vindex split-width-threshold
+The split can be either vertical or horizontal, depending on the
+variables @code{split-height-threshold} and
+@code{split-width-threshold}.  These variables should have integer
+values.  If @code{split-height-threshold} is smaller than the selected
+window's height, the split puts the new window below.  Otherwise, if
+@code{split-width-threshold} is smaller than the window's width, the
+split puts the new window on the right.  If neither condition holds,
+Emacs tries to split so that the new window is below---but only if the
+window was not split before (to avoid excessive splitting).
+
+@item
+Otherwise, display the buffer in an existing window on the selected
+frame.
+
+@item
+If all the above methods fail for whatever reason, create a new frame
+and display the buffer there.
+@end itemize
+
 @node Window Convenience
 @section Window Handling Convenience Features and Customization
 
diff --git a/etc/NEWS b/etc/NEWS
index 71e5d9cd8be..75ff2081f00 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -386,6 +386,45 @@ by default.
 *** `menu-bar-select-buffer-function' lets you choose another operation
 instead of `switch-to-buffer' when selecting an item in the Buffers menu.
 
+** Window changes
+
++++
+*** Resizing an Emacs frame now preserves proportional window sizes,
+modulo restrictions like window minimum sizes and fixed-size windows.
+
+*** The behavior of `display-buffer' is now customizable in detail.
+
+**** New option `display-buffer-base-action' specifies a list of
+user-determined display "actions" (functions and optional arguments
+for choosing the displaying window).
+
+This takes precedence over the default display action, which is
+specified by `display-buffer-fallback-action'.
+
+**** New option `display-buffer-alist' maps buffer name regexps to
+display actions, taking precedence over `display-buffer-base-action'.
+
++++
+*** New option `window-nest'.
+The new option `window-nest' allows to return the space obtained for
+resizing or creating a window more reliably to the window from which
+such space was obtained.
+
++++
+*** New option `window-splits'.
+The new option `window-splits' allows to split a window that otherwise
+cannot be split because it's too small by stealing space from other
+windows in the same combination.
+
++++
+*** New commands `maximize-window' and `minimize-window'.
+These maximize and minize the size of a window within its frame.
+
++++
+*** New commands `switch-to-prev-buffer' and `switch-to-next-buffer'.
+These functions allow to navigate through the live buffers that have
+been shown in a specific window.
+
 ** The inactive minibuffer has its own major mode `minibuffer-inactive-mode'.
 This is handy for minibuffer-only frames, and is also used for the "mouse-1
 pops up *Messages*" feature, which can now easily be changed.
@@ -1003,18 +1042,6 @@ split.  Any other value of SIDE will cause `split-window' to split the
 window into two side-by-side windows as before.
 
 +++
-*** New option `window-nest'.
-The new option `window-nest' allows to return the space obtained for
-resizing or creating a window more reliably to the window from which
-such space was obtained.
-
-+++
-*** New option `window-splits'.
-The new option `window-splits' allows to split a window that otherwise
-cannot be split because it's too small by stealing space from other
-windows in the same combination.
-
-+++
 *** `split-window-above-each-other' and `split-window-side-by-side'.
 The commands `split-window-vertically' and `split-window-horizontally'
 have been renamed to `split-window-above-each-other' and
@@ -1028,12 +1055,6 @@ been introduced.  This and all other functions for resizing windows no
 longer delete any windows when they become too small.
 
 +++
-*** Frame/window resizing.
-Resizing an Emacs frame now preserves the proportional sizes of
-subwindows modulo restrictions imposed by window minimum sizes and
-fixed-size windows.
-
-+++
 *** `adjust-window-trailing-edge' adjustments.
 `adjust-window-trailing-edge' can now deal with fixed-size windows and
 is able to resize other windows if a window adjacent to the trailing
@@ -1042,11 +1063,6 @@ that of Emacs 21 without compromising, however, its inability to delete
 windows which was introduced in Emacs 22.
 
 +++
-*** Commands for maximizing and minimizing windows.
-New functions to maximize and minimize a window within its frame are
-provided, namely `maximize-window' and `minimize-window'.
-
-+++
 *** Window-local buffer lists.
 Windows now have local buffer lists.  This means that removing a buffer
 from display in a window will preferably show the buffer previously
@@ -1054,17 +1070,31 @@ shown in that window with its previous window-start and window-point
 positions.  This also means that the same buffer may be automatically
 shown twice even if it already appears in another window.
 
-+++
-*** New commands `switch-to-prev-buffer' and `switch-to-next-buffer'.
-These functions allow to navigate through the live buffers that have
-been shown in a specific window.
-
 *** `switch-to-buffer' has a new optional argument FORCE-SAME-WINDOW,
 which if non-nil requires the buffer to be displayed in the currently
 selected window, signaling an error otherwise.  If nil, another window
 can be used, e.g. if the selected one is strongly dedicated.
 
-*** FIXME: buffer-display-alist changes
+*** `split-window-vertically' and `split-window-horizontally' renamed
+to `split-window-above-each-other' and `split-window-side-by-side'
+respectively.  The old names are kept as aliases.
+
+*** Display actions
+
+**** The second arg to `display-buffer' and `pop-to-buffer' is now
+named ACTION, and takes a display action of the same form as
+`display-buffer-base-action' (see Changes, above).  A non-nil,
+non-list value is treated specially, as the old meaning.
+
+**** New variable `display-buffer-overriding-action'.
+
+**** The procedure of `display-buffer' etc. to choose a window is
+determined by combining `display-buffer-overriding-action',
+`display-buffer-alist', the ACTION arg, `display-buffer-base-action',
+and `display-buffer-fallback-action'.  The second and fourth of these
+are user-customizable variables.
+
+See the docstring of `display-buffer' for details.
 
 ** Completion