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

[Daniel Colascione <dancol@dancol.org>]

On 08/30/2016 11:00 AM, Eli Zaretskii wrote:
>> Cc: acm@muc.de, monnier@iro.umontreal.ca, emacs-devel@gnu.org
>> From: Daniel Colascione <dancol@dancol.org>
>> 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.

So we're in agreement? True or false: b-c-f ought to be a conservative 
bound on subsequent a-c-f calls.

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

Not the case at all. That's the point of saying b-c-f is a conservative 
bound. The words "conservative bound" free you from having to describe 
the precise ways the b-c-f region and the a-c-f region can differ.

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

Why shouldn't they be able to rely on that? What *should* they use to 
invalidate caches? Your position is not very clear to me.