3 files changed, 77 insertions, 11 deletions
diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi
index c8987c279c5..01f899f1c09 100644
--- a/doc/emacs/display.texi
+++ b/doc/emacs/display.texi
@@ -1601,7 +1601,6 @@ screen lines.  Setting the variable @code{truncate-lines} in any way
 makes it local to the current buffer; until that time, the default
 value, which is normally @code{nil}, is in effect.
 
-@vindex truncate-partial-width-windows
   If a split window becomes too narrow, Emacs may automatically enable
 line truncation.  @xref{Split Window}, for the variable
 @code{truncate-partial-width-windows} which controls this.
diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi
index dc99d493241..c23c96f0745 100644
--- a/doc/emacs/emacs.texi
+++ b/doc/emacs/emacs.texi
@@ -519,6 +519,7 @@ Multiple Windows
 * Pop Up Window::       Finding a file or buffer in another window.
 * Change Window::       Deleting windows and changing their sizes.
 * Displaying Buffers::  How Emacs picks a window for displaying a buffer.
+* Temporary Displays::  Displaying non-editable buffers.
 * Window Convenience::  Convenience functions for window handling.
 
 Displaying a Buffer in a Window
diff --git a/doc/emacs/windows.texi b/doc/emacs/windows.texi
index f99234b5c1b..702963f75c5 100644
--- a/doc/emacs/windows.texi
+++ b/doc/emacs/windows.texi
@@ -117,10 +117,14 @@ variable @code{truncate-lines} (@pxref{Line Truncation}); it is
 instead controlled by the variable
 @code{truncate-partial-width-windows}.  If the value of this variable
 is a positive integer (the default is 50), that specifies the minimum
-width for a partial-width window before automatic line truncation
-occurs; if the value is @code{nil}, automatic line truncation is
-disabled; and for any other non-@code{nil} value, Emacs truncates
-lines in every partial-width window regardless of its width.
+total width for a partial-width window before automatic line
+truncation occurs; if the value is @code{nil}, automatic line
+truncation is disabled; and for any other non-@code{nil} value, Emacs
+truncates lines in every partial-width window regardless of its width.
+The total width of a window is in column units as reported by
+@code{window-total-width} (@pxref{Window Sizes,,, elisp, The Emacs
+Lisp Reference Manual}), it includes the fringes, the continuation and
+truncation glyphs, the margins, and the scroll bar.
 
   On text terminals, side-by-side windows are separated by a vertical
 divider which is drawn using the @code{vertical-border} face.
@@ -206,7 +210,7 @@ Choice}, for how Emacs picks or creates the window to use.
 Select buffer @var{bufname} in another window
 (@code{switch-to-buffer-other-window}).
 
-@findex display-buffer
+@findex display-buffer @r{(command)}
 @item C-x 4 C-o @var{bufname} @key{RET}
 @kindex C-x 4 C-o
 Display buffer @var{bufname} in some window, without trying to select
@@ -345,7 +349,6 @@ 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 off a new window and
 displaying the desired buffer there.  Such commands, which include the
@@ -374,11 +377,12 @@ Several of these commands are bound in the @kbd{C-x 5} prefix key.
 
 @menu
 * Window Choice::   How @code{display-buffer} works.
+* Temporary Displays::   Displaying non-editable buffers.
 @end menu
 
 @node Window Choice
 @subsection How @code{display-buffer} works
-@findex display-buffer
+@findex display-buffer, detailed description
 
 The @code{display-buffer} command (as well as commands that call it
 internally) chooses a window to display by following the steps given
@@ -411,15 +415,15 @@ By default, this step is skipped.  To enable it, change the variable
 @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.
+Otherwise, try to create a new window by splitting a window on the
+selected frame, 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
+values.  If @code{split-height-threshold} is smaller than the chosen
 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,
@@ -427,6 +431,12 @@ 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 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.
+
+@item
 Otherwise, display the buffer in an existing window on the selected
 frame.
 
@@ -435,6 +445,62 @@ 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.
+Help commands (@pxref{Help}) typically use a buffer called @file{*Help*}
+for that purpose, minibuffer completion (@pxref{Completion}) uses a
+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.
+
+  If you prefer Emacs to display a temporary buffer in a different
+fashion, we recommend to customize 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}):
+
+@example
+@group
+(customize-set-variable
+ 'display-buffer-alist
+ '(("\\*Completions\\*" display-buffer-pop-up-window)))
+@end group
+@end example
+
+@findex temp-buffer-resize-mode
+  The @file{*Completions*} buffer is also special in the sense that
+Emacs usually tries to make its window just as large as necessary to
+display all of its contents.  To resize windows showing other
+temporary displays like, for example, the @file{*Help*} buffer
+accordingly, turn on the minor mode (@pxref{Minor Modes})
+@code{temp-buffer-resize-mode} (@pxref{Temporary Displays,,Temporary
+Displays, elisp, The Emacs Lisp Reference Manual}).
+
+@vindex temp-buffer-max-height
+@vindex temp-buffer-max-width
+  The maximum size of windows resized by @code{temp-buffer-resize-mode}
+can be controlled by customizing the options
+@code{temp-buffer-max-height} and @code{temp-buffer-max-width}
+(@pxref{Temporary Displays,,Temporary Displays, elisp, The Emacs Lisp
+Reference Manual}) and cannot exceed the size of the containing frame.
+
+
 @node Window Convenience
 @section Convenience Features for Window Handling