Fix description of 'display-buffer-in-previous-window' again (Bug#36161)

* lisp/window.el (display-buffer-in-previous-window): Make
doc-string more explicit (Bug#36161).
* doc/lispref/windows.texi (Buffer Display Action Functions):
Make description of 'display-buffer-in-previous-window' more
explicit.
(Buffer Display Action Alists): Mention
'display-buffer-in-previous-window' in description of
'reusable-frames' entry.

1 files changed, 37 insertions, 13 deletions

diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index 3116659cd03..ea9329e0517 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -2581,25 +2581,47 @@ operations (@pxref{Preserving Window Sizes}).
 This function fails if no window can be split.  More often than not,
 this happens because no window is large enough to allow splitting.
 Setting @code{split-height-threshold} or @code{split-width-threshold}
-to lower values may help in this regard.  Spliting also fails when the
-selected frame has an @code{unsplittable} frame parameter;
+to lower values may help in this regard.  Splitting also fails when
+the selected frame has an @code{unsplittable} frame parameter;
 @pxref{Buffer Parameters}.
 @end defun
 
 @defun display-buffer-in-previous-window buffer alist
 This function tries to display @var{buffer} in a window where it was
-previously displayed.  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 suitable window.
-
-If @var{alist} has a @code{previous-window} entry and the window
-specified by that entry is live and not dedicated to another buffer,
-that window will be preferred, even if it never showed @var{buffer}
+displayed previously.
+
+If @var{alist} contains a non-@code{nil} @code{inhibit-same-window}
+entry, the selected window is not eligible for use.  A dedicated
+window is usable only if it already shows @var{buffer}.  If
+@var{alist} contains a @code{previous-window} entry, the window
+specified by that entry is usable even if it never showed @var{buffer}
 before.
 
-This function will not choose the selected window if it finds another
-eligible window that has shown @var{buffer} previously.
+If @var{alist} contains a @code{reusable-frames} entry (@pxref{Buffer
+Display Action Alists}), its value determines which frames to search
+for a suitable window.  If @var{alist} contains no
+@code{reusable-frames} entry, this function searches just the selected
+frame if @code{display-buffer-reuse-frames} and @code{pop-up-frames}
+are both @code{nil}; it searches all frames on the current terminal if
+either of those variables is non-@code{nil}.
+
+If more than one window qualifies as usable according to these rules,
+this function makes a choice in the following order of preference:
+
+@itemize @bullet
+@item
+The window specified by any @code{previous-window} @var{alist} entry,
+provided it is not the selected window.
+
+@item
+A window that showed @var{buffer} before, provided it is not the
+selected window.
+
+@item
+The selected window if it is either specified by a
+@code{previous-window} @var{alist} entry or showed @var{buffer}
+before.
+@end itemize
 @end defun
 
 @defun display-buffer-use-some-window buffer alist
@@ -2786,7 +2808,9 @@ Ordering}).
 
 A major client of this is @code{display-buffer-reuse-window}, but all
 other action functions that try to reuse a window are affected as
-well.
+well.  @code{display-buffer-in-previous-window} consults it when
+searching for a window that previosuly displayed the buffer on another
+frame.
 
 @vindex inhibit-switch-frame@r{, a buffer display action alist entry}
 @item inhibit-switch-frame