; 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 bc3857b1366fb8eba06041c7bc8f6810212ad0fd..03d0f28867aebe657e96aeff70f2cdec2d609bfb 100644 (file)
--- 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 85413b0d38d710ab44091629f854beed03b256f2..9321b4c079f72d530732b2d0151c3254e7ecfebd 100644 (file)
--- 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 a0c51600dc969db47818e557ff851c5000a1612a..3fe48e25228c9e4fc68f32e221daac885d10e553 100644 (file)
--- 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)