window-buffer-change-functions

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

I tried to fix the documentation of `window-buffer-change-functions'
to avoid passive voice, then discovered it was unclear in other ways.
So I decided to rewrite it to make it clear.

In that attempt, I found it was so unclear that I could not be sure
what the variable actually does.  I concluded ultimately that the
problem was in the variable's meaning, not just in the documentation
text.  If I understand it right, it uses the default (global?) value
in one way and buffer-local values in another way.

This messes up the general rule for the meaning of buffer-local
bindings, undermining the clarity of the Emacs Lisp language.  We
should try hard to avoid ever doing that.  In this case I think it
will not be hard.

I propose we replace it with two variables, each with a simple
meaning.  They could be `buffer-window-change-functions' and
`frame-buffer-change-functions'.

`frame-buffer-change-functions' would do what is documented for the
default value of `window-buffer-change-functions', and the
`buffer-window-change-functions' would do the job documented for the
buffer-local values.  (If I understand that documention correctly.)

We could retain `window-buffer-change-functions' for compatibility,
marked obsolete, if it has existed with its current meaning for long
enough to make that desirable.  Or, if that variable used to be
limited to frames, we could make `frame-buffer-change-functions'
an alias for it.

@defvar frame-buffer-change-functions
A list of functions for redisplay to call to indicate changes
in the displayed buffers in a frame.  Each function should accept
one argument, a frame.

Redisplay, when necessary, calls each of these functions once for each
frame, with the frame as argument, @emph{if} at least one window on
that frame has been added, deleted or made to display a different
buffer since the last time redisplay called these functions.
@end defvar

@defvar buffer-window-change-functions
A list of functions for redisplay to call (when necessary) to indicate
changes in the displayed buffers in a frame.  Each function should
accept one argument, a window.

For each window, @emph{if} the window has been created, or made to
display that buffer, since the last time redisplay called these
functions, redisplay checks the value of this variable in the window's
displayed buffer.  That value should be a list of functions of one
argument.  Redisplay calls each function on the list, giving the
window as argument.

Most buffers don't need this special treatment, so normally programs
will give `buffer-window-change-functions' a buffer-local value in
those buffers that do need it.
@end defvar

This is still complicated, but much less so.

Did I guess right about what the existing variable does?

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