From: Eli Zaretskii <eliz@gnu.org>
Date: Sat, 6 Jul 2024 10:44:57 +0000 (+0300)
Subject: Fix documentation of 'balance-windows'
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=7688809dd7d7be42a715f0875f6eef751656af6f;p=emacs.git

Fix documentation of 'balance-windows'

* lisp/window.el (balance-windows): Doc fix.

* doc/emacs/windows.texi (Change Window): Make the description of
'balance-windows' more accurate.  (Bug#71915)

(cherry picked from commit de3fa00a6140b19e6d62a47be721b5ca9b58438b)
---

diff --git a/doc/emacs/windows.texi b/doc/emacs/windows.texi
index bdf2fe9aa0d..7a973e6b4a7 100644
--- a/doc/emacs/windows.texi
+++ b/doc/emacs/windows.texi
@@ -300,7 +300,8 @@ Make selected window narrower (@code{shrink-window-horizontally}).
 Shrink this window if its buffer doesn't need so many lines
 (@code{shrink-window-if-larger-than-buffer}).
 @item C-x +
-Make all windows the same height (@code{balance-windows}).
+Balance the sizes of all the windows of the selected frame
+(@code{balance-windows}).
 @end table
 
 @kindex C-x 0
@@ -373,8 +374,11 @@ lines to other windows in the frame.
 
 @kindex C-x +
 @findex balance-windows
-  You can also use @kbd{C-x +} (@code{balance-windows}) to even out the
-heights of all the windows in the selected frame.
+  You can also use @kbd{C-x +} (@code{balance-windows}) to balance the
+sizes of all the windows of the selected frame (with the exception of
+the minibuffer window, @pxref{Minibuffer}).  This command makes each
+horizontal pair of adjacent windows the same height, and each vertical
+pair of adjacent windows the same width.
 
 @node Displaying Buffers
 @section Displaying a Buffer in a Window
diff --git a/lisp/window.el b/lisp/window.el
index 27833c4e4cd..decb98ff501 100644
--- a/lisp/window.el
+++ b/lisp/window.el
@@ -5893,12 +5893,13 @@ is non-nil)."
 	      (setq sub (window-right sub))))))))
 
 (defun balance-windows (&optional window-or-frame)
-  "Balance the sizes of windows of WINDOW-OR-FRAME.
-WINDOW-OR-FRAME is optional and defaults to the selected frame.
+  "Balance the sizes of windows shown on the selected frame.
+When called from Lisp, WINDOW-OR-FRAME is optional and defaults to the
+selected frame.
 If WINDOW-OR-FRAME denotes a frame, balance the sizes of all
-windows of that frame.  If WINDOW-OR-FRAME denotes a window,
-recursively balance the sizes of all child windows of that
-window."
+windows of that frame's root window (which excludes the mini-window).
+If WINDOW-OR-FRAME denotes a window, recursively balance the sizes
+of all child windows of that window."
   (interactive)
   (let* ((window
 	  (cond