bug#51590: follow-mode is broken with header-line and tab-line

[Alan Mackenzie <acm@muc.de>]

Hello, Eli and Martin.

On Sat, Nov 06, 2021 at 14:12:50 +0200, Eli Zaretskii wrote:
> > Date: Sat, 6 Nov 2021 11:50:48 +0000
> > Cc: juri@linkov.net, 51590@debbugs.gnu.org
> > From: Alan Mackenzie <acm@muc.de>

[ .... ]

> > OK.  But I think there's confusion in the manual and doc strings, and
> > even the code, and that it's not just me.

This confusion being the meanings of "window body" and "window text
area", in particular as to whether or not they include any header line or
tab line.

> _After_ my today's changes?  If so, please show where is the confusing
> text.

I've done a survey of window.c, keyboard.c, window.el for all occurrences
of "text area" and "body" in function names, doc strings, some comments,
and parameter names.  The source I've grepped is an almost up to date
copy of the emacs-28 branch.  The function name is at the left, followed
by annotations for text area and body.  "BIG" means the term includes the
header and tab lines, "small" means it does not, "?" means it is not
immediately clear, blank means it is irrelevant or not mentioned.

Function                       Text Area            Body
--------                       ---------            ----
Fwindow_body_width
Fwindow_body_height                small         (small)
Fwindow_old_body_pixel_width
Fwindow_old_body_pixel_height          ?
Fwindow_lines_pixel_dimensions                  confused.

Fwindow_text_height                small
Fset_window_fringes
window_body_height                                 small
window_body_width
window_change_record_windows                           ?

run_window_change_functions
Vwindow_size_change_functions
Vwindow_state_change_functions
Vwindow_state_change_hook
Vwindow_configuration_change_hook


make_lispy_position		  small
make_lispy_event                                       ?
read_key_sequence                 small
Fposn_at_x_y                        BIG


window-body-size                      ?
window-edges                          ?                ?
window-absolute-body-pixel-edges      ?                ?
window-largest-empty-rectangle        ?
window-preserve-size                                   ?

window-body-edges                                      ?
window-body-pixel-edges                                ?


It seems clear that, at least in the places where the meaning of "text
area" and "body" are clear, that they refer to the area which doesn't
include the header line and tab line.

Fposn_at_x_y stands out as the only function with BIG.  Maybe the picture
would change on examining the elisp manual.  Maybe some of the unclear
annotations would resolve to BIG, but that doesn't seem all that likely.

Given this, it seems it would be better to amend the documentation of
Fposn_at_x_y to refer to the "text area _plus_ any header line or tab
line".

-- 
Alan Mackenzie (Nuremberg, Germany).