A few further fixes of window internals description

* doc/lispref/internals.texi (Window Internals): Add a few
more items and clarify description of some others.

1 files changed, 82 insertions, 60 deletions

diff --git a/src/window.h b/src/window.h
index c7f525e2704..96e9a9f30ea 100644
--- a/src/window.h
+++ b/src/window.h
@@ -24,57 +24,69 @@ along with GNU Emacs.  If not, see <https://www.gnu.org/licenses/>.  */
 
 INLINE_HEADER_BEGIN
 
-/* Windows are allocated as if they were vectors, but then the
-Lisp data type is changed to Lisp_Window.  They are garbage
-collected along with the vectors.
+/* Windows are allocated as if they were vectors, but then the Lisp
+data type is changed to Lisp_Window.  They are garbage collected along
+with the vectors.
 
 All windows in use are arranged into a tree, with pointers up and down.
 
-Windows that are leaves of the tree are actually displayed
-and show the contents of buffers.  Windows that are not leaves
-are used for representing the way groups of leaf windows are
-arranged on the frame.  Leaf windows never become non-leaves.
-They are deleted only by calling delete-window on them (but
-this can be done implicitly).  Combination windows can be created
-and deleted at any time.
-
-A leaf window has a buffer stored in contents field and markers in its start
-and pointm fields.  Non-leaf windows have nil in the latter two fields.
-
-Non-leaf windows are either vertical or horizontal combinations.
-
-A vertical combination window has children that are arranged on the frame
-one above the next.  Its contents field points to the uppermost child.
-The parent field of each of the children points to the vertical
-combination window.  The next field of each child points to the
-child below it, or is nil for the lowest child.  The prev field
-of each child points to the child above it, or is nil for the
-highest child.
-
-A horizontal combination window has children that are side by side.
-Its contents field points to the leftmost child.  In each child
-the next field points to the child to the right and the prev field
-points to the child to the left.
-
-The children of a vertical combination window may be leaf windows
-or horizontal combination windows.  The children of a horizontal
-combination window may be leaf windows or vertical combination windows.
-
-At the top of the tree are two windows which have nil as parent.
-The second of these is minibuf_window.  The first one manages all
-the frame area that is not minibuffer, and is called the root window.
-Different windows can be the root at different times;
-initially the root window is a leaf window, but if more windows
-are created then that leaf window ceases to be root and a newly
-made combination window becomes root instead.
-
-In any case, on screens which have an ordinary window and a
-minibuffer, prev of the minibuf window is the root window and next of
-the root window is the minibuf window.  On minibufferless screens or
-minibuffer-only screens, the root window and the minibuffer window are
-one and the same, so its prev and next members are nil.
-
-A dead window has its contents field set to nil.  */
+Windows that are leaves of the tree are actually displayed and show
+the contents of buffers.  Windows that are not leaves are used for
+representing the way groups of leaf windows are arranged on the frame.
+Leaf windows never become non-leaves.  They are deleted only by
+calling `delete-window' on them (but this can be done implicitly).
+Non-leaf windows never become leaf windows and can be created and
+deleted at any time by the window management code.  Non-leaf windows
+can be seen but not directly manipulated by Lisp functions.
+
+A leaf window has a buffer stored in its contents field and markers in
+its 'start' and 'pointm' fields.  Non-leaf windows have nil in the
+latter two fields.  Non-leaf windows are either vertical or horizontal
+combinations.
+
+A vertical combination window has children that are arranged on the
+frame one above the next.  Its 'contents' field points to the
+uppermost child.  The 'parent' field of each of the children points to
+the vertical combination window.  The 'next' field of each child
+points to the child below it, or is nil for the lowest child.  The
+'prev' field of each child points to the child above it, or is nil for
+the highest child.
+
+A horizontal combination window has children that are arranged side by
+side.  Its 'contents' field points to the leftmost child.  In each
+child the 'next' field points to the child to the right and the 'prev'
+field points to the child to the left.
+
+On each frame there are at least one and at most two windows which
+have nil as parent.  The second of these, if present, is the frame's
+minibuffer window and shows the minibuffer or the echo area.  The
+first one manages the remaining frame area and is called the frame's
+root window.  Different windows can be the root at different times;
+initially the root window is a leaf window, but if more windows are
+created, then that leaf window ceases to be root and a newly made
+combination window becomes the root instead.
+
+On frames which have an ordinary window and a minibuffer window,
+'prev' of the minibuffer window is the root window and 'next' of the
+root window is the minibuffer window.  On minibuffer-less frames there
+is only a root window and 'next' of the root window is nil.  On
+minibuffer-only frames, the root window and the minibuffer window are
+one and the same, so its 'prev' and 'next' members are nil.  In any
+case, 'prev' of a root window and 'next' of a minibuffer window are
+always nil.
+
+In Lisp parlance, leaf windows are called "live windows" and non-leaf
+windows are called "internal windows".  Together, live and internal
+windows form the set of "valid windows".  A window that has been
+deleted is considered "dead" regardless of whether it formerly was a
+leaf or a non-leaf window.  A dead window has its 'contents' field set
+to nil.
+
+Frames may also contain pseudo windows, windows that are not exposed
+directly to Lisp code.  Pseudo windows are currently either used to
+display the menu bar or the tool bar (when Emacs uses toolkits that
+don't display their own menu bar and tool bar) or a tooltip in a
+tooltip frame (when tooltips are not display by the toolkit).  */
 
 struct cursor_pos
 {
@@ -95,29 +107,39 @@ struct window
 
     /* Following (to right or down) and preceding (to left or up)
        child at same level of tree.  Whether this is left/right or
-       up/down is determined by the 'horizontal' flag, see below.
-       A minibuffer window has the frame's root window pointed by 'prev'.  */
+       up/down is determined by the parent window's 'horizontal' flag,
+       see below.  On a frame that is neither a minibuffer-only nor a
+       minibuffer-less frame, 'next' of the root window points to the
+       frame's minibuffer window and 'prev' of the minibuffer window
+       points to the frame's root window.  In all other cases, 'next'
+       of the root window and 'prev' of the minibuffer window, if
+       present, are nil.  'prev' of the root window and 'next' of the
+       minibuffer window are always nil.  */
     Lisp_Object next;
     Lisp_Object prev;
 
-    /* The window this one is a child of.  For a minibuffer window: nil.  */
+    /* The window this one is a child of.  For the root and a
+       minibuffer window this is always nil.  */
     Lisp_Object parent;
 
-    /* The normal size of the window.  These are fractions, but we do
-       not use C doubles to avoid creating new Lisp_Float objects while
-       interfacing Lisp in Fwindow_normal_size.  */
+    /* The "normal" size of the window.  These are fractions, but we
+       do not use C doubles to avoid creating new Lisp_Float objects
+       while interfacing Lisp in Fwindow_normal_size.  */
     Lisp_Object normal_lines;
     Lisp_Object normal_cols;
 
-    /* New sizes of the window.  Note that Lisp code may set new_normal
-       to something beyond an integer, so C int can't be used here.  */
+    /* The new sizes of the window as proposed by the window resizing
+       functions.  Note that Lisp code may set new_normal to something
+       beyond an integer, so C int can't be used here.  */
     Lisp_Object new_total;
     Lisp_Object new_normal;
     Lisp_Object new_pixel;
 
-    /* For a leaf window: a buffer; for an internal window: a window;
-       for a pseudo-window (such as menu bar or tool bar): nil.  It is
-       a buffer for a minibuffer window as well.  */
+    /* For a leaf window or a tooltip window this is the buffer shown
+       in the window; for a combination window this is the first of
+       its child windows; for a pseudo window showing the menu bar or
+       tool bar this is nil.  It is a buffer for a minibuffer window
+       as well.  */
     Lisp_Object contents;
 
     /* A marker pointing to where in the text to start displaying.
@@ -192,7 +214,7 @@ struct window
 
     /* The two Lisp_Object fields below are marked in a special way,
        which is why they're placed after `current_matrix'.  */
-    /* Alist of <buffer, window-start, window-point> triples listing
+    /* A list of <buffer, window-start, window-point> triples listing
        buffers previously shown in this window.  */
     Lisp_Object prev_buffers;
     /* List of buffers re-shown in this window.  */