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

[Alan Mackenzie]

Hello, Eli.

On Tue, Aug 30, 2016 at 08:53:48PM +0300, Eli Zaretskii wrote:
> > Date: Tue, 30 Aug 2016 17:42:24 +0000
> > Cc: address@hidden, address@hidden, address@hidden
> > From: Alan Mackenzie <address@hidden>

> > > Your attempt didn't describe the current implementation.  It described
> > > what you thought it should be.

> > The text in question (intended for the Elisp manual) was:

> >   Normally the before-change-functions and the after-change-functions
> >   hooks are called in balanced pairs around each buffer change, enabling
> >   state to be determined in a before-change function and used in an
> >   after-change function.  However on rare occasions,
> >   before-change-functions is not called before a buffer change and
> >   after-change-functions is thus called twice in succession.  Your
> >   program should be ready to deal with such an occurrence.
 
> > The crucial part of that is the first sentence.  It is true.

> We use "normally" in the manual to mean "always, unless changed by
> customizations".  So the above use of that word is extremely confusing
> and thus a bad idea.

  The before-change-functions and after-change-functions hooks are
  almost always called in balanced pairs around each buffer change,
  enabling state to be determined in a before-change-function and used
  in an after-change-function.  However, on rare occasions, ....

> And the part about "balanced pairs" is simply false, if "balanced" is
> to be interpreted in its everyday's meaning.

I don't understand what you mean.  By balanced, I essentially mean that
(i) b-c-f and a-c-f alternate,
(ii) b-c-f's beg is the same as a-c-f's beg,
(iii) b-c-f's (- end beg) is equal to a-c-f's old-len.

In that sense b/a-c-f are balanced in the overwhelming majority of
cases.


> > The second sentence is true in essence, though it possibly needs to be
> > made more accurate to deal with other cases.

> The current text is even more "true in essence", though.

No it's not.  It describes the exceptional and rare case as though it
were common.  It implies that using b/a-c-f together is not a
practicable programming technique, whereas the opposite is true.

-- 
Alan Mackenzie (Nuremberg, Germany).