From: Eli Zaretskii <eliz@gnu.org>
Date: Fri, 20 May 2022 11:35:03 +0000 (+0300)
Subject: ; Improve documentation of 'display-buffer-avoid-small-windows'
X-Git-Tag: emacs-29.0.90~1910^2~561
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=eb71446de5352f6735e8a778ab4f71a04d90f76e;p=emacs.git

; Improve documentation of 'display-buffer-avoid-small-windows'

* lisp/window.el (display-buffer-avoid-small-windows)
(get-lru-window):
* etc/NEWS:
* doc/lispref/windows.texi (Choosing Window Options): Improve
documentation of 'display-buffer-avoid-small-windows'.
(Bug#10186)
---

diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index bc3857b1366..03d0f28867a 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -3307,7 +3307,9 @@ that means not to split this way.
 
 @defopt display-buffer-avoid-small-windows
 If non-@code{nil}, this should be a number.  Windows that have fewer
-lines than this will be avoided when choosing an existing window.
+lines than that will be avoided when choosing an existing window.  The
+value is interpreted in units of the frame's canonical line height,
+like @code{window-total-height} does (@pxref{Window Sizes}).
 @end defopt
 
 @defopt even-window-sizes
diff --git a/etc/NEWS b/etc/NEWS
index 85413b0d38d..9321b4c079f 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -606,8 +606,8 @@ specifiers can now use ':type webp'.
 ** Windows
 
 *** New user option 'display-buffer-avoid-small-windows'.
-If non-nil, this should be a window height.  If windows smaller than
-this will be avoided by 'display-buffer', if possible.
+If non-nil, this should be a window height, a number.  Windows smaller
+than this will be avoided by 'display-buffer', if possible.
 
 +++
 *** New display action 'display-buffer-full-frame'.
diff --git a/lisp/window.el b/lisp/window.el
index a0c51600dc9..3fe48e25228 100644
--- a/lisp/window.el
+++ b/lisp/window.el
@@ -2490,7 +2490,8 @@ and no others."
 
 (defcustom display-buffer-avoid-small-windows nil
   "If non-nil, windows that have fewer lines than this are avoided.
-This is used by `get-lru-window'."
+This is used by `get-lru-window'.  The value is interpreted in units
+of the frame's canonical line height, like `window-total-height' does."
   :type '(choice nil number)
   :version "29.1"
   :group 'windows)
@@ -2522,9 +2523,9 @@ have special meanings:
 Any other value of ALL-FRAMES means consider all windows on the
 selected frame and no others.
 
-`display-buffer-avoid-small-windows' is also taken into
-consideration.  Windows smaller than this size will be avoided if
-there are larger windows available."
+`display-buffer-avoid-small-windows', if non-nil, is also taken into
+consideration.  Windows whose height is smaller that the value of that
+variable will be avoided if larger windows are available."
   (let ((windows (window-list-1 nil 'nomini all-frames))
         best-window best-time second-best-window second-best-time time)
     (dolist (window windows)