Fix docs on `display-buffer-below-selected' (Bug#24213)

* lisp/window.el (display-buffer-below-selected): Fix
doc-string (Bug#24213).
* doc/lispref/windows.texi (Display Action Functions): Fix
documentation of `display-buffer-below-selected'.

2 files changed, 15 insertions, 6 deletions

diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index ad0c3237e69..7a5d1bbf166 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -2524,10 +2524,17 @@ parameter; @pxref{Buffer Parameters}).
 
 @defun display-buffer-below-selected buffer alist
 This function tries to display @var{buffer} in a window below the
-selected window.  This means to either split the selected window or use
-the window below the selected one.  If it does create a new window, it
-will also adjust its size provided @var{alist} contains a suitable
+selected window.  If there is a window below the selected one and that
+window already displays @var{buffer}, it reuses that window.
+
+If there is no such window, this function tries to create a new window
+by splitting the selected one and display @var{buffer} there.  It will
+also adjust that window's size provided @var{alist} contains a suitable
 @code{window-height} or @code{window-width} entry, see above.
+
+If splitting the selected window fails and there is a non-dedicated
+window below the selected one showing some other buffer, it uses that
+window for showing @var{buffer}.
 @end defun
 
 @defun display-buffer-in-previous-window buffer alist
diff --git a/lisp/window.el b/lisp/window.el
index bf1f13e7766..11d7a4e90d4 100644
--- a/lisp/window.el
+++ b/lisp/window.el
@@ -6879,7 +6879,6 @@ raising the frame."
 
 (defun display-buffer--maybe-pop-up-frame-or-window (buffer alist)
   "Try displaying BUFFER based on `pop-up-frames' or `pop-up-windows'.
-
 If `pop-up-frames' is non-nil (and not `graphic-only' on a
 text-only terminal), try with `display-buffer-pop-up-frame'.
 
@@ -6894,8 +6893,11 @@ again with `display-buffer-pop-up-window'."
 
 (defun display-buffer-below-selected (buffer alist)
   "Try displaying BUFFER in a window below the selected window.
-This either splits the selected window or reuses the window below
-the selected one."
+If there is a window below the selected one and that window
+already displays BUFFER, use that window.  Otherwise, try to
+create a new window below the selected one and show BUFFER there.
+If that attempt fails as well and there is a non-dedicated window
+below the selected one, use that window."
   (let (window)
     (or (and (setq window (window-in-direction 'below))
              (eq buffer (window-buffer window))