bug#51862: after-focus-change-function: hard to understand documentation

[Lars Ingebrigtsen]

Stefan Kangas <stefan@marxist.se> writes:

> This for me comes off as pretty scary.  It sounds to me like I would
> need to invest couple of hours at least into understanding all this,
> when all I really want to do call a very simple function whenever focus
> leaves a frame.

I think the reason is to be found in the doc string of the obsoleted
variables.  That is:

---
This hook is obsolete.  Despite its name, this hook may be run in
situations other than when a frame obtains input focus: for
example, we also run this hook when switching the selected frame
internally to handle certain input events (like mouse wheel
scrolling) even when the user's notion of input focus
hasn't changed.
---

So it's not reliable (any more?), and that's why the new variable is the
way it is.  Probably (but it'd be helpful if Daniel could chime in).

But looking at the code, I don't understand these caveats at all.  In
addition to the calls from xterm.el, the only place
after-focus-change-function is called is from
handle-focus-in/handle-focus-out -- which also call the old, obsolete
hooks.

So it doesn't seem to be more reliable, but just more incomprehensible.

In addition, handle-focus-in/out know which frame they got the event
for, but that's discarded.

I guess the idea here might be that since you can get more than one
focus-in event per real event, you should write your code to ensure that
you don't trigger it more than once per frame?  I.e., since this is all
apparently probabilistic, we leave the hard stuff to the user.

So I've tried to make the documentation here clearer and less scary, and
I've added a really un-scary example.