From eca2677b1db94a126b6d2871526a1d6fce98353d Mon Sep 17 00:00:00 2001 From: Martin Rudalics Date: Wed, 12 Jun 2019 11:02:02 +0200 Subject: [PATCH] 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. --- doc/lispref/windows.texi | 50 +++++++++++++++++++++++++++++----------- lisp/window.el | 22 ++++++++++++------ 2 files changed, 52 insertions(+), 20 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 diff --git a/lisp/window.el b/lisp/window.el index c2d5b02be05..de110111b5a 100644 --- a/lisp/window.el +++ b/lisp/window.el @@ -7457,10 +7457,13 @@ selected frame." (defun display-buffer-in-previous-window (buffer alist) "Display BUFFER in a window previously showing it. If ALIST has a non-nil `inhibit-same-window' entry, the selected -window is not eligible for reuse. +window is not usable. A dedicated window is usable only if it +already shows BUFFER. If ALIST contains a `previous-window' +entry, the window specified by that entry is usable even if it +never showed BUFFER before. If ALIST contains a `reusable-frames' entry, its value determines -which frames to search for a reusable window: +which frames to search for a usable window: nil -- the selected frame (actually the last non-minibuffer frame) A frame -- just that frame `visible' -- all visible frames @@ -7472,12 +7475,17 @@ selected frame if `display-buffer-reuse-frames' and `pop-up-frames' are both nil; search all frames on the current terminal if either of those variables is non-nil. -If ALIST has a `previous-window' entry, the window specified by -that entry may override any other window found by the methods -above, even if that window never showed BUFFER before. +If more than one window is usable according to these rules, +apply the following order of preference: + +- Use the window specified by any 'previous-window' ALIST entry, + provided it is not the selected window. + +- Use a window that showed BUFFER before, provided it is not the + selected window. -Avoid using the selected window if another eligible window has -shown BUFFER before." +- Use the selected window if it is either specified by a + 'previous-window' ALIST entry or showed BUFFER before." (let* ((alist-entry (assq 'reusable-frames alist)) (inhibit-same-window (cdr (assq 'inhibit-same-window alist))) -- 2.39.2