Rewrite documentation of buffer display

* doc/emacs/windows.texi (Window Choice): Rewrite, replacing
references to older buffer display options with references to
and examples of buffer display actions.
(Temporary Displays): Rewrite display of *Completions*
example.

* doc/lispref/elisp.texi (Top): New Windows section
'Displaying Buffers'.
* doc/lispref/frames.texi (Child Frames): Adjust cross
reference.
* doc/lispref/windows.texi (Windows): New section 'Displaying
Buffers'.  Move sections 'Choosing Window', 'Display Action
Functions' and 'Choosing Window Options' there and adjust
namings.  Preferably write 'Buffer Display Action' instead of
'Display Action'.  More consistently use @w{} to make key
binding specifications unsplittable.
(Displaying Buffers): New section.
(Choosing Window): Make it a subsection of 'Displaying
Buffers'.  More explicitly describe how 'display-buffer'
compiles its list of action functions and the action alist.
(Buffer Display Action Functions): Rename from 'Display Action
Functions', make it a subsection of 'Displaying Buffers' and
rewrite it.  Elide more detailed descriptions of action alist
entries; these are now in the new section 'Buffer Display
Action Functions'.  Remove example.
(Buffer Display Action Alists): New subsection of 'Displaying
Buffers' giving a comprehensive description of recognized
action alist entries with appropriate indexing.  Contents were
partially moved here from the old 'Display Action Functions'
section.
(Choosing Window Options): Make it a subsection of 'Displaying
Buffers'.  Add examples of how to rewrite old buffer display
options with the help of buffer display actions.
(Precedence of Action Functions): New subsection of
'Displaying Buffers' explaining the execution order of action
functions with the help of a detailed example.
(The Zen of Buffer Display): New subsection of 'Displaying
Buffers' supplying guidelines on how to write and use buffer
display actions with examples.
(Side Windows, Displaying Buffers in Side Windows)
(Frame Layouts with Side Windows, Atomic Windows): Update
references to the 'Displaying Buffers' subsections.

doc/emacs/windows.texi

@@ -48,8 +48,8 @@ other windows at all.  However, there are other commands such as
 @kbd{C-x 4 b} that select a different window and switch buffers in it.
 Also, all commands that display information in a window, including
 (for example) @kbd{C-h f} (@code{describe-function}) and @kbd{C-x C-b}
-(@code{list-buffers}), work by switching buffers in a nonselected
-window without affecting the selected window.
+(@code{list-buffers}), usually work by displaying buffers in a
+nonselected window without affecting the selected window.
 
   When multiple windows show the same buffer, they can have different
 regions, because they can have different values of point.  However,
@@ -340,11 +340,9 @@ heights of all the windows in the selected frame.
 in response to a user command.  There are several different ways in
 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}).
+  Many commands, like @kbd{C-x C-f} (@code{find-file}), by default
+display the buffer by ``taking over'' the selected window, expecting
+that the user's attention will be diverted to that buffer.
 
   Some commands try to display intelligently, trying not to take
 over the selected window, e.g., by splitting off a new window and
@@ -367,10 +365,9 @@ 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.
+selected window and (ii) prefer to either create a new frame or use a
+window on some other frame to display the desired buffer.  Several of
+these commands are bound in the @kbd{C-x 5} prefix key.
 
 @menu
 * Window Choice::   How @code{display-buffer} works.
@@ -383,33 +380,61 @@ Several of these commands are bound in the @kbd{C-x 5} prefix key.
 
 The @code{display-buffer} command (as well as commands that call it
 internally) chooses a window to display by following the steps given
-below.  @xref{Choosing Window,,Choosing a Window for Display, elisp,
-The Emacs Lisp Reference Manual}, for details about how to alter this
-sequence of steps.
+below.  @xref{Choosing Window,,Choosing a Window for Displaying a
+Buffer, elisp, The Emacs Lisp Reference Manual}, for details about how
+to alter this sequence of 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.
+adding a regular expression matching the buffer's name together with a
+reference to the @code{display-buffer-same-window} action function
+(@pxref{Buffer Display Action Functions,,Action Functions for Buffer
+Display, elisp, The Emacs Lisp Reference Manual}) to the option
+@code{display-buffer-alist} (@pxref{Choosing Window,,Choosing a Window
+for Displaying a Buffer, elisp, The Emacs Lisp Reference Manual}).
+For example, to display the buffer @file{*scratch*} preferably in the
+selected window write:
+
+@example
+@group
+(customize-set-variable
+ 'display-buffer-alist
+ '("\\*scratch\\*" (display-buffer-same-window)))
+@end group
+@end example
+
+By default, @code{display-buffer-alist} is @code{nil}, so this step is
+skipped.
 
 @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{pop-up-frames} (see below) to @code{t}.
+reuse that window.  Normally, only windows on the selected frame are
+considered, but windows on other frames are also reusable if a
+corresponding @code{reusable-frames} action alist entry (@pxref{Buffer
+Display Action Alists,,Action Alists for Buffer Display, elisp, The
+Emacs Lisp Reference Manual}) is used (see the next step for an
+example of how to do that).
 
-@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.
+By default, this step is skipped.  To enable it, change the value of
+the option @code{display-buffer-base-action} (@pxref{Choosing
+Window,,Choosing a Window for Displaying a Buffer, elisp, The Emacs
+Lisp Reference Manual}) as follows:
+
+@example
+@group
+(customize-set-variable
+ 'display-buffer-base-action
+ '((display-buffer-reuse-window display-buffer-pop-up-frame)
+   (reusable-frames . 0)))
+@end group
+@end example
+
+This customization will also try to make the preceding step search for
+a reusable window on all visible of iconified frames
 
 @item
 Otherwise, try to create a new window by splitting a window on the
@@ -429,9 +454,9 @@ window was not split before (to avoid excessive splitting).
 
 @item
 Otherwise, display the buffer in a window previously showing it.
-Normally, only windows on the selected frame are considered, but if
-@code{pop-up-frames} is non-@code{nil} the window may be also on another
-frame.
+Normally, only windows on the selected frame are considered, but with
+a suitable @code{reusable-frames} action alist entry (see above) the
+window may be also on another frame.
 
 @item
 Otherwise, display the buffer in an existing window on the selected
@@ -442,14 +467,9 @@ If all the above methods fail for whatever reason, create a new frame
 and display the buffer there.
 @end itemize
 
-A more advanced and flexible way to customize the behavior of
-@code{display-buffer} is by using the option @code{display-buffer-alist}
-mentioned in the next section.
-
 
 @node Temporary Displays
 @subsection Displaying non-editable buffers.
-@cindex pop-up windows
 @cindex temporary windows
 
 Some buffers are shown in windows for perusal rather than for editing.
@@ -459,24 +479,24 @@ buffer called @file{*Completions*} instead.  Such buffers are usually
 displayed only for a short period of time.
 
   Normally, Emacs chooses the window for such temporary displays via
-@code{display-buffer} as described above.  The @file{*Completions*}
-buffer, on the other hand, is normally displayed in a window at the
-bottom of the selected frame, regardless of the number of windows
-already shown on that frame.
+@code{display-buffer} as described in the previous subsection.  The
+@file{*Completions*} buffer, on the other hand, is normally displayed
+in a window at the bottom of the selected frame, regardless of the
+number of windows already shown on that frame.
 
   If you prefer Emacs to display a temporary buffer in a different
 fashion, we recommend customizing the variable
 @code{display-buffer-alist} (@pxref{Choosing Window,,Choosing a Window
-for Display, elisp, The Emacs Lisp Reference Manual}).  For example,
-to display @file{*Completions*} by splitting a window as described in
-the previous section, use the following form in your initialization
-file (@pxref{Init File}):
+for Displaying a Buffer, elisp, The Emacs Lisp Reference Manual}).
+For example, to display @file{*Completions*} always below the selected
+window, use the following form in your initialization file
+(@pxref{Init File}):
 
 @example
 @group
 (customize-set-variable
  'display-buffer-alist
- '(("\\*Completions\\*" display-buffer-pop-up-window)))
+ '(("\\*Completions\\*" display-buffer-below-selected)))
 @end group
 @end example
 

doc/lispref/elisp.texi

@@ -1043,9 +1043,7 @@ Windows
 * Cyclic Window Ordering::  Moving around the existing windows.
 * Buffers and Windows::     Each window displays the contents of a buffer.
 * Switching Buffers::       Higher-level functions for switching to a buffer.
-* Choosing Window::         How to choose a window for displaying a buffer.
-* Display Action Functions:: Subroutines for @code{display-buffer}.
-* Choosing Window Options:: Extra options affecting how buffers are displayed.
+* Displaying Buffers::      Displaying a buffer in a suitable window.
 * Window History::          Each window remembers the buffers displayed in it.
 * Dedicated Windows::       How to avoid displaying another buffer in
                               a specific window.
@@ -1067,6 +1065,18 @@ Windows
                               redisplay going past a certain point,
                               or window configuration changes.
 
+Displaying Buffers
+
+* Choosing Window::         How to choose a window for displaying a buffer.
+* Buffer Display Action Functions:: Support functions for buffer display.
+* Buffer Display Action Alists:: Alists for fine-tuning buffer display
+                              action functions.
+* Choosing Window Options:: Extra options affecting how buffers are displayed.
+* Precedence of Action Functions:: A tutorial explaining the precedence of
+                              buffer display action functions.
+* The Zen of Buffer Display:: How to avoid that buffers get lost in between
+                              windows.
+
 Side Windows
 
 * Displaying Buffers in Side Windows:: An action function for displaying

doc/lispref/frames.texi

@@ -3198,11 +3198,11 @@ and should be preferred when specifying a non-@code{nil}
 @code{drag-with-mode-line} parameter.
 
   When a child frame is used for displaying a buffer via
-@code{display-buffer-in-child-frame} (@pxref{Display Action Functions}),
-the frame's @code{auto-hide-function} parameter (@pxref{Frame
-Interaction Parameters}) can be set to a function, in order to
-appropriately deal with the frame when the window displaying the buffer
-shall be quit.
+@code{display-buffer-in-child-frame} (@pxref{Buffer Display Action
+Functions}), the frame's @code{auto-hide-function} parameter
+(@pxref{Frame Interaction Parameters}) can be set to a function, in
+order to appropriately deal with the frame when the window displaying
+the buffer shall be quit.
 
   When a child frame is used during minibuffer interaction, for example,
 to display completions in a separate window, the @code{minibuffer-exit}