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

[Daniel Colascione]

On 08/30/2016 10:42 AM, Eli Zaretskii wrote:
> > Cc: address@hidden, address@hidden
> > From: Daniel Colascione <address@hidden>
> > Date: Tue, 30 Aug 2016 10:27:45 -0700
> >
> > +The region given to each of these functions is a conservative
> > +approximation of the region about to changed.  After running the
> > +before-change-functions, Emacs will make zero or more fine-grained
> > +buffer changes and run after-change-functions for each.  Do not expect
> > +before-change-functions and after-change-functions to be called in
> > +balanced pairs.
>
> The last sentence here is repeated afterwards, for no good reason.
> (Also, the markup is missing, but that's just an aside.)

I figured it was a good idea to highlight this fact directly in the 
variable documentation blob. I can add a "see below" link.

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

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


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