Merge from origin/emacs-26

070e82b ; * src/window.c (window_scroll): Improve commentary.
60457d7 Improve documentation of the window tree
ea1a014 Fix window scrolling on TTY frames when there's no mode line
df7ed10 Fix decoding XML files encoded in ISO-8859
7851ae8 (tag: emacs-26.1.90) ; ChangeLog.3 update
1958808 * etc/AUTHORS: Update.
7252507 Fix description of some window hooks
88762b4 Run 'window--adjust-process-windows' when frame size changes ...
d6542ea Avoid errors in zone.el when there's overlay at EOB

1 files changed, 22 insertions, 23 deletions

diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index af497cf6af9..b86bccab202 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -198,12 +198,13 @@ relationships between live windows.  The root node of a window tree is
 called the @dfn{root window}.  It can be either a live window (if the
 frame has just one window), or an internal window.
 
-  A minibuffer window (@pxref{Minibuffer Windows}) is not part of its
-frame's window tree unless the frame is a minibuffer-only frame.
-Nonetheless, most of the functions in this section accept the
-minibuffer window as an argument.  Also, the function
-@code{window-tree} described at the end of this section lists the
-minibuffer window alongside the actual window tree.
+  A minibuffer window (@pxref{Minibuffer Windows}) that is not alone
+on its frame does not have a parent window, so it strictly speaking is
+not part of its frame's window tree.  Nonetheless, it is a sibling
+window of the frame's root window, and thus can be reached via
+@code{window-next-sibling}.  Also, the function @code{window-tree}
+described at the end of this section lists the minibuffer window
+alongside the actual window tree.
 
 @defun frame-root-window &optional frame-or-window
 This function returns the root window for @var{frame-or-window}.  The
@@ -6037,26 +6038,24 @@ size and has to check out these windows by using the method described
 in the previous paragraph.
 
 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