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
+(@code{list-buffers}), usually work by displaying buffers in a
-window without affecting the selected window.
+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
+  Many commands, like @kbd{C-x C-f} (@code{find-file}), by default
-buffer by ``taking over'' the selected window, expecting that the
+display the buffer by ``taking over'' the selected window, expecting
-user's attention will be diverted to that buffer.  These commands
+that the user's attention will be diverted to that buffer.
-usually work by calling @code{switch-to-buffer} internally
-(@pxref{Select 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
+selected window and (ii) prefer to either create a new frame or use a
-desired buffer instead of splitting a window---as though the variable
+window on some other frame to display the desired buffer.  Several of
-@code{pop-up-frames} is set to @code{t} (@pxref{Window Choice}).
+these commands are bound in the @kbd{C-x 5} prefix key.
-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,
+below.  @xref{Choosing Window,,Choosing a Window for Displaying a
-The Emacs Lisp Reference Manual}, for details about how to alter this
+Buffer, elisp, The Emacs Lisp Reference Manual}, for details about how
-sequence of steps.
+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
+adding a regular expression matching the buffer's name together with a
-@code{same-window-buffer-names}, or adding a matching regular
+reference to the @code{display-buffer-same-window} action function
-expression to the list @code{same-window-regexps}.  By default, these
+(@pxref{Buffer Display Action Functions,,Action Functions for Buffer
-variables are @code{nil}, so this step is skipped.
+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
+reuse that window.  Normally, only windows on the selected frame are
-are considered, but windows on other frames are also reusable if you
+considered, but windows on other frames are also reusable if a
-change @code{pop-up-frames} (see below) to @code{t}.
+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
+By default, this step is skipped.  To enable it, change the value of
-@code{pop-up-frames} to a non-@code{nil} value.  The special value
+the option @code{display-buffer-base-action} (@pxref{Choosing
-@code{graphic-only} means to do this only on graphical displays.
+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
+Normally, only windows on the selected frame are considered, but with
-@code{pop-up-frames} is non-@code{nil} the window may be also on another
+a suitable @code{reusable-frames} action alist entry (see above) the
-frame.
+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*}
+@code{display-buffer} as described in the previous subsection.  The
-buffer, on the other hand, is normally displayed in a window at the
+@file{*Completions*} buffer, on the other hand, is normally displayed
-bottom of the selected frame, regardless of the number of windows
+in a window at the bottom of the selected frame, regardless of the
-already shown on that frame.
+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,
+for Displaying a Buffer, elisp, The Emacs Lisp Reference Manual}).
-to display @file{*Completions*} by splitting a window as described in
+For example, to display @file{*Completions*} always below the selected
-the previous section, use the following form in your initialization
+window, use the following form in your initialization file
-file (@pxref{Init 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.
+* Displaying Buffers::      Displaying a buffer in a suitable window.
-* Display Action Functions:: Subroutines for @code{display-buffer}.
-* Choosing Window Options:: Extra options affecting how buffers are displayed.
 * 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}),
+@code{display-buffer-in-child-frame} (@pxref{Buffer Display Action
-the frame's @code{auto-hide-function} parameter (@pxref{Frame
+Functions}), the frame's @code{auto-hide-function} parameter
-Interaction Parameters}) can be set to a function, in order to
+(@pxref{Frame Interaction Parameters}) can be set to a function, in
-appropriately deal with the frame when the window displaying the buffer
+order to appropriately deal with the frame when the window displaying
-shall be quit.
+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}