Fix description of some window hooks

* doc/lispref/windows.texi (Window Hooks): Remove text that
warns against using 'save-window-excursion' while running
'window-size-change-functions', it's no more relevant.
Clarify description of 'window-configuration-change-hook'.

2 files changed, 21 insertions, 18 deletions

diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index e9bd0c7d83e..46f106838a5 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -6016,26 +6016,24 @@ whether a specific window has changed size, compare the return values of
 @code{window-pixel-height} for that window (@pxref{Window Sizes}).
 
 These function are usually only called when at least one window was
-added or has changed size since the last time this hook was run for the
-associated frame.  In some rare cases this hook also runs when a window
-that was added intermittently has been deleted afterwards.  In these
-cases none of the windows on the frame will appear to have changed its
-size.
-
-You may use @code{save-selected-window} in these functions
-(@pxref{Selecting Windows}).  However, do not use
-@code{save-window-excursion} (@pxref{Window Configurations}); exiting
-that macro counts as a size change, which would cause these functions to
-be called again.
+added or has changed size since the last time this hook was run for
+the associated frame.  In some rare cases this hook also runs when a
+window that was added intermittently has been deleted afterwards.  In
+these cases none of the windows on the frame will appear to have
+changed its size.
 @end defvar
 
 @defvar window-configuration-change-hook
-A normal hook that is run every time the window configuration of a frame
-changes.  Window configuration changes include splitting and deleting
-windows, and the display of a different buffer in a window.  Resizing the
-frame or individual windows do not count as configuration changes.  Use
-@code{window-size-change-functions}, see above, when you want to track
-size changes that are not caused by the deletion or creation of windows.
+A normal hook that is run every time the window configuration of a
+frame changes.  Window configuration changes include splitting and
+deleting windows, and the display of a different buffer in a window.
+
+The hook can be also used for tracking changes of window sizes.  It
+is, however, not run when the size of a frame changes or automatic
+resizing of a minibuffer window (@pxref{Minibuffer Windows}) changes
+the size of another window.  As a rule, adding a function to
+@code{window-size-change-functions}, see above, is the recommended way
+for reliably tracking size changes of any window.
 
 The buffer-local value of this hook is run once for each window on the
 affected frame, with the relevant window selected and its buffer
diff --git a/lisp/window.el b/lisp/window.el
index 94ac65cfc5b..f252b0e041a 100644
--- a/lisp/window.el
+++ b/lisp/window.el
@@ -9287,10 +9287,15 @@ displaying that processes's buffer."
               (when size
                 (set-process-window-size process (cdr size) (car size))))))))))
 
+;; Remove the following call in Emacs 27, running
+;; 'window-size-change-functions' should suffice.
 (add-hook 'window-configuration-change-hook 'window--adjust-process-windows)
+
+;; Catch any size changes not handled by
+;; 'window-configuration-change-hook' (Bug#32720, "another issue" in
+;; Bug#33230).
 (add-hook 'window-size-change-functions (lambda (_frame)
                                           (window--adjust-process-windows)))
-
 
 ;; Some of these are in tutorial--default-keys, so update that if you
 ;; change these.