master eb71446de5: ; Improve documentation of 'display-buffer-avoid-small-windows'

[Eli Zaretskii]

branch: master
commit eb71446de5352f6735e8a778ab4f71a04d90f76e
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    ; 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)
---
 doc/lispref/windows.texi | 4 +++-
 etc/NEWS                 | 4 ++--
 lisp/window.el           | 9 +++++----
 3 files changed, 10 insertions(+), 7 deletions(-)

diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index bc3857b136..03d0f28867 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 85413b0d38..9321b4c079 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 a0c51600dc..3fe48e2522 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)