emacs-28 c2e3cd6: Clarify "text area of a window" in the documentation

[Eli Zaretskii]

branch: emacs-28
commit c2e3cd6694a15441d25e85b88e8c80194f32d848
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    Clarify "text area of a window" in the documentation
    
    * src/keyboard.c (Fposn_at_x_y): Clarify that the Y coordinate
    includes the header-line and the tab-line.  (Bug#51590)
    
    * doc/lispref/windows.texi (Window Sizes, Splitting Windows)
    (Textual Scrolling, Coordinates and Windows): Fix/remove improper
    or confusing uses of "text area" of a window.
---
 doc/lispref/windows.texi | 54 +++++++++++++++++++++++++-----------------------
 src/keyboard.c           |  2 ++
 2 files changed, 30 insertions(+), 26 deletions(-)

diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index 0ae26b2..57cd227 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -131,8 +131,8 @@ including for the case where @var{object} is a deleted 
window.
        |______________ Header Line ______________|  | |
      ^ |LS|LM|LF|                       |RF|RM|RS|  | |
      | |  |  |  |                       |  |  |  |  | |
-Window |  |  |  |       Text Area       |  |  |  |  | Window
-Body | |  |  |  |     (Window Body)     |  |  |  |  | Total
+Window |  |  |  |                       |  |  |  |  | Window
+Body | |  |  |  |      Window Body      |  |  |  |  | Total
 Height |  |  |  |                       |  |  |  |  | Height
      | |  |  |  |<- Window Body Width ->|  |  |  |  | |
      v |__|__|__|_______________________|__|__|__|  | |
@@ -145,27 +145,29 @@ Height |  |  |  |                       |  |  |  |  | 
Height
 @end smallexample
 
 @cindex window body
-@cindex text area of a window
 @cindex body of a window
 @cindex window decorations
 @cindex left and right window decorations
 @cindex top and bottom window decorations
-  At the center of that window is the @dfn{text area}, or @dfn{body},
-where the buffer text is displayed.  The text area can be surrounded by
-a series of optional areas which we will call @dfn{window decorations}.
-On the left and right, from innermost to outermost, these are the left
-and right fringes, denoted by LF and RF (@pxref{Fringes}); the left and
-right margins, denoted by LM and RM in the schematic (@pxref{Display
+  At the center of that window is the @dfn{body}, where the buffer
+text is displayed.  The body can be surrounded by a series of optional
+areas which we will call @dfn{window decorations}.  On the left and
+right, from innermost to outermost, these are the left and right
+fringes, denoted by LF and RF (@pxref{Fringes}); the left and right
+margins, denoted by LM and RM in the schematic (@pxref{Display
 Margins}); the left or right vertical scroll bar, only one of which is
-present at any time, denoted by LS and RS (@pxref{Scroll Bars}); and the
-right divider, denoted by RD (@pxref{Window Dividers}).  Together these
-are the window's @dfn{left and right decorations}.
+present at any time, denoted by LS and RS (@pxref{Scroll Bars}); and
+the right divider, denoted by RD (@pxref{Window Dividers}).  Together
+these are the window's @dfn{left and right decorations}.
 
+@cindex text area of a window
   At the top of the window are the tab line and the header line
-(@pxref{Header Lines}).  At the bottom of the window are the horizontal
-scroll bar (@pxref{Scroll Bars}); the mode line (@pxref{Mode Line
-Format}); and the bottom divider (@pxref{Window Dividers}).  Together
-these form the window's @dfn{top and bottom decorations}.
+(@pxref{Header Lines}).  The @dfn{text area} of the window includes
+the header line and the tab line, if they are present in the window.
+At the bottom of the window are the horizontal scroll bar
+(@pxref{Scroll Bars}); the mode line (@pxref{Mode Line Format}); and
+the bottom divider (@pxref{Window Dividers}).  Together these form the
+window's @dfn{top and bottom decorations}.
 
   There are two special areas omitted in the schematic:
 
@@ -818,7 +820,7 @@ that of the root window on that frame.  If @var{window} is 
omitted or
 
 @cindex window body height
 @cindex body height of a window
-The @dfn{body height} of a window is the height of its text area, which
+The @dfn{body height} of a window is the height of its body, which
 does not include any of its top or bottom decorations (@pxref{Basic
 Windows}).
 
@@ -839,9 +841,9 @@ exceed its total height as returned by 
@code{window-total-height}.
 
 @cindex window body width
 @cindex body width of a window
-The @dfn{body width} of a window is the width of its text area, which
-does not include any of its left or right decorations (@pxref{Basic
-Windows}).
+The @dfn{body width} of a window is the width of its body and of the
+text area, which does not include any of its left or right decorations
+(@pxref{Basic Windows}).
 
 Note that when one or both fringes are removed (by setting their width
 to zero), the display engine reserves two character cells, one on each
@@ -1014,8 +1016,8 @@ Normally, the variables @code{window-min-height} and
 is non-@code{nil}, this function ignores @code{window-min-height} and
 @code{window-min-width}, as well as @code{window-size-fixed}.  Instead,
 it considers the minimum height of a window as the sum of its top and
-bottom decorations plus a text area of one line; and its minimum width
-as the sum of its left and right decorations plus a text area of two
+bottom decorations plus the text of one line; and its minimum width
+as the sum of its left and right decorations plus text that takes two
 columns.
 
 If the optional argument @var{pixelwise} is non-@code{nil},
@@ -1355,7 +1357,7 @@ Sizes}).  Thus, it signals an error if splitting would 
result in making
 a window smaller than those variables specify.  However, a
 non-@code{nil} value for @var{size} causes those variables to be
 ignored; in that case, the smallest allowable window is considered to be
-one that has space for a text area one line tall and/or two columns
+one that has space for a text that is one line tall and/or two columns
 wide.
 
 Hence, if @var{size} is specified, it's the caller's responsibility to
@@ -5157,7 +5159,7 @@ window.
 If @var{count} is negative, it scrolls backward instead.  If
 @var{count} is @code{nil} (or omitted), the distance scrolled is
 @code{next-screen-context-lines} lines less than the height of the
-window's text area.
+window's body.
 
 If the selected window cannot be scrolled any further, this function
 signals an error.  Otherwise, it returns @code{nil}.
@@ -5657,8 +5659,8 @@ and its neighbor.
 If the optional argument @var{body} is @code{nil}, this means to
 return the edges corresponding to the total size of @var{window}.
 @var{body} non-@code{nil} means to return the edges of @var{window}'s
-body (aka text area).  If @var{body} is non-@code{nil}, @var{window}
-must specify a live window.
+body.  If @var{body} is non-@code{nil}, @var{window} must specify a
+live window.
 
 If the optional argument @var{absolute} is @code{nil}, this means to
 return edges relative to the native position of @var{window}'s frame.
diff --git a/src/keyboard.c b/src/keyboard.c
index a99d14c..c608c07 100644
--- a/src/keyboard.c
+++ b/src/keyboard.c
@@ -11348,6 +11348,8 @@ The elements of this list correspond to the arguments of
 DEFUN ("posn-at-x-y", Fposn_at_x_y, Sposn_at_x_y, 2, 4, 0,
        doc: /* Return position information for pixel coordinates X and Y.
 By default, X and Y are relative to text area of the selected window.
+Note that the text area includes the header-line and the tab-line of
+the window, if any of them are present.
 Optional third arg FRAME-OR-WINDOW non-nil specifies frame or window.
 If optional fourth arg WHOLE is non-nil, X is relative to the left
 edge of the window.