Re: window-buffer-change-functions

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Date: Wed, 21 Sep 2022 09:59:24 -0400
> 
> 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'.

I don't think this justifies splitting this variable (which exists
since Emacs 27) into two.  Such a split will cause a lot of problems
for existing code, because this hooks are used in a lot of Lisp
programs.  Keeping obsolete aliases is a PITA and a maintenance
burden, so it doesn't really eliminate this downside.

This hook is conceptually simple: it is called when the correspondence
between buffers and their windows changes.  The functions in the local
value are called for individual windows only when the corresponding
buffer is involved in the change, and the global value is called once
for any frame where the correspondence changed for any buffer.  This
shouldn't be hard to explain, and any not-100%-clean design shouldn't
get in the way of documenting it clearly and in a way that Lisp
programs could use, including elimination of passive tense.

So I don't agree with the need to introduce two separate new
variables.  The downsides of such a split aren't justified by the
minor conceptual problems you mention.

I added Martin, who made this change back in Emacs 27, to the
discussion, in the hope that he could comment on the issue.