bug#51930: 27.2; Buffer-local functions? Buffers specified buffer-locally?

[Richard Stallman <rms@gnu.org>]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

        > For the buffer-local value, each function is called for any window
        > showing the corresponding buffer, if that window has been created
        > or assigned that buffer since the last time window change functions
        > were run.  In this case the window is passed as argument.

        > For the default value, each function is called for a frame if at
        > least one window on that frame has been added, deleted or assigned
        > another buffer since the last time window change functions were
        > run.  In this case the frame is passed as argument.

It is always better to avoid the passive tense entirely, unless that
is difficult somehow.  I wanted to do this, to provide an example.
In the process I found a much worse problem: the text is not clear at all.
I don't understand the behavior it tries to document.

But I tried anyway, and documented what appears to be a bizarre use of
both the variable's default value and its current value, in different ways.

======================================================================
A list of functions for redisplay to call when the assignment of
buffers to windows has changed.  Each function takes a single
argument.

This variable is peculiar in that its default value has one meaning
and its actual value (normally buffer-local) has a different meaning.
Redisplay uses both of these values, each in a different way.

For the actual (buffer-local) value, redisplay calls each function
once for each window, with the window as argument, if that window has
been created or assigned that buffer since the last time the window
change functions were called.

For the default value, redisplay calls each function once for each
frame, with the frame as argument, if at least one window on that
frame has been added, deleted or assigned another buffer since the
last time window change functions were called.
======================================================================

However, looking at the doc string of the variable seems to describe
a different behavior, more like this:

======================================================================
A list of functions for redisplay to call when the assignment of
buffers to windows has changed.  Each function takes a single
argument.

Redisplay examines the global value of this variable, and calls each
function once for each frame, with the frame as argument, if at least
one window on that frame has been added, deleted or made to display a
different buffer since the last time window change functions were
called.

Redisplay also checks a buffer-local value of this variable in each
buffer that's currenly displayed in a window.  If there is one,
redisplay calls each function listed there for each window that
displays the buffer in question, with the window as argument,
@emph{if} the window has been created, or made to display that buffer,
since the last time the window change functions were called.
======================================================================

Is this correct?  I can't tell from the text available.


-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)