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

[martin rudalics <rudalics@gmx.at>]

 > 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.

Thanks.  Note that searching for "text area" alone is not sufficient.
In the past, the "thing" (the body of a window) we talk about here has
been described in various ways, usually according to the personal taste
of the author of a change.

You missed, for example, 'window-text-width' which uses the term "text
display area" for this.  I've usually tried to retain the nomenclature
originally used by the authors because it's hardly ever immediately
evident what they really had in mind and also in the hope that the use
of functions like 'window-text-width' would eventually fade out.

The greatest problem in this area is that Emacs traditionally uses the
terms 'window-height' to refer to the total height of a window and
'window-width' to refer to its body width.  Obviously, all occurrences
of these two terms should be replaced with 'window-total-height' and
'window-body-width' respectively but you can easily see for yourself the
progress I have made.

Hence, rather than caring about the (IMO) very minor "text area" issue,
fixing these occurrences should be our major aim if we want to remove
inconsistencies.  Sadly, people add new occurrences of these at a faster
pace than I'm able to remove the older ones.

 > Function                       Text Area            Body
 > --------                       ---------            ----
 > Fwindow_body_width

Any function that has "body" in its name is "safe" (and means "small" in
your nomenclature) so we can usually ignore them.  Their doc-strings,
however, may use some variant of "text area" since that was the term
commonly in use at the time the "body" functions were added.

 > Fwindow_body_height                small         (small)
 > Fwindow_old_body_pixel_width
 > Fwindow_old_body_pixel_height          ?
 > Fwindow_lines_pixel_dimensions                  confused.

'window-lines-pixel-dimensions' is like 'window-text-pixel-size' but
works line-wise.  More precisely, it can be used to walk the buffer text
shown in a window and get the number of pixels occupied by each
individual line.  The BODY argument serves to control the impact the
presence of a header or mode line could have on the return value.

 > Fwindow_text_height                small
 > Fset_window_fringes
 > window_body_height                                 small
 > window_body_width
 > window_change_record_windows                           ?

'window_change_record_windows' does not make any reference to the text
area so why the "?".

 > run_window_change_functions
 > Vwindow_size_change_functions
 > Vwindow_state_change_functions
 > Vwindow_state_change_hook
 > Vwindow_configuration_change_hook

I tried to very carefully distinguish between body and total sizes here
because, for example, a  change in the width of a fringe may or may not
change the body width of a window and leave the total width alone.  So
there should not be any problems with these.

 > make_lispy_position		  small
 > make_lispy_event                                       ?
 > read_key_sequence                 small
 > Fposn_at_x_y                        BIG

I never thoroughly checked the keyboard and mouse defined routines.
There anything is possible.

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

All of these are new and should be "small" although their docs may
still contain references to the "text area".

But the far greater problem is to find all occurrences of "text" in the
manuals, for example, where it stands for the width or height of the
buffer text shown in a window.  Often I read and re-read the manual a
couple of times in order to find out what is really meant and whether
what I read is not biased because I've read some different part of the
manual before.

These parts of the manual suffer most from the transition of Emacs from
TTYs to GUIs over time and the accompanying changes of its nomenclature.

 > 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".

Or _not use_ the term "text area" here in the first place.

martin