Re: Unbalanced change hooks (part 2) [Documentation fix still remaining]

[Eli Zaretskii]

> Cc: address@hidden, address@hidden, address@hidden
> From: Daniel Colascione <address@hidden>
> Date: Tue, 30 Aug 2016 10:46:44 -0700
> 
> >> -  Do @emph{not} expect the before-change hooks and the after-change
> >> -hooks be called in balanced pairs around each buffer change.  Also
> >> -don't expect the before-change hooks to be called for every chunk of
> >> -text Emacs is about to delete.  These hooks are provided on the
> >> -assumption that Lisp programs will use either before- or the
> >> -after-change hooks, but not both, and the boundaries of the region
> >> -where the changes happen might include more than just the actual
> >> -changed text, or even lump together several changes done piecemeal.
> >> +   Do @emph{not} expect the before-change hooks and the after-change
> >> +hooks be called in balanced pairs around each buffer change.
> >> +The before-change-functions region is a conservative bound on the zero
> >> +or more fine-grained changes to follow.  Emacs informs user code about
> >> +the actual changes to the buffer through calls to
> >> +after-change-functions; these fine-grained changes will always fall
> >> +inside the broad change region Emacs describes by calling
> >> +before-change-functions.
> >
> > You removed the part about text deletion, which is not specific to
> > revert-buffer, so that information is now lost.  I don't want to lose
> > it.
> 
> The text deletion part is a real and serious bug. As Stefan points out, 
> it makes it impossible to use b-c-f to invalidate caches.

You misunderstand what Stefan says.  He says not calling the
before-change hook _at_all_ is a bug.  Not calling it for every chunk
of deleted text is not necessarily a bug, if there's a previous less
fine-grained call to the hook.  And that's what the text above
conveys: that note every chunk to be deleted will have its own call to
a hook.

> > Other than that, I don't see how your text is more accurate, it's just
> > a different wording dancing around the same issues trying to side-step
> > them by replacing one vague description by another.
> 
> My proposed description highlights how the b-c-f region contains the 
> a-c-f regions. I understand that you believe that the existing 
> documentation communicates this fact, but I strongly disagree. The 
> relationship between the b-c-f region and the a-c-f regions needs to be 
> spelled out explicitly.

They cannot be spelled out explicitly without going into a lot more
internal details that are inappropriate for the Lisp-level manual.

> > If all you want is to remove this part:
> >
> >   These hooks are provided on the assumption that Lisp programs will
> >   use either before- or the after-change hooks, but not both
> >
> > then I don't necessarily mind, although I do believe it is true, and
> > the readers should be aware of that.
> 
> I strongly disagree. b-c-f is a perfectly good way to invalidate caches.

So the readers need to know they cannot rely on that.