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

[Alan Mackenzie <acm@muc.de>]

Hello, Eli.

On Thu, Aug 18, 2016 at 05:26:03PM +0300, Eli Zaretskii wrote:
> > From: Stefan Monnier <monnier@iro.umontreal.ca>
> > Cc: emacs-devel@gnu.org
> > Date: Wed, 10 Aug 2016 12:11:21 -0400

> > >> > except that the call to before-change-functions in some cases does not
> > >> > precede the first modification of the series.  IOW, by the time the
> > >> > hook is called, some modifications were already done.
> > >> Sounds like a bug.
> > > I'm not convinced it's a bug.

> > before-change-functions should be called *before* a
> > change occurs.  If there is a call to b-c-f before the first
> > modification, and then another call before the second modification in
> > that series, then it's OK (assuming the BEG/END values are sufficiently
> > large in each call to cover the changes that occur before the next call).

> > But if a change occurs without having been "announced" by an earlier
> > b-c-f then it's a bug.

> I've reviewed all the places where we may not call the before- and the
> after-change hooks.  They are just a few.

Thanks!

> One questionable place is insert-file-contents: it deliberately never
> calls the before-change-functions when it deletes portions of the
> text, only when it inserts text.  I don't really understand the
> reasons behind your insisting on before-change-functions being called
> before any changes in this case, but maybe a simple way out would be
> to announce at the beginning of the function that the entire range
> between point-min and point-max is about to be changed, when REPLACE
> is non-nil.

That might create difficulties for CC Mode.  CC Mode now recognises when
b-c-f isn't called at all, but isn't, as far as I've thought it through,
prepared to deal with b-c-f with inaccurate arguments.

> Another place where before-change-functions is not called, but
> after-change-functions are is set-buffer-multibyte.  Moreover, if the
> function is called with a nil argument, we don't call
> after-change-functions as well.  Is that supposed to be handled as a
> buffer change or not?

Possibly not - only the lowest levels of code would notice any
difference.

> In the low levels of encoding and decoding routines, we sometimes call
> the hooks and sometimes don't, depending on what is the source and the
> destination of the en/decoding, and whether there are pre-write or
> pre-write conversions.  But the buffer in question is a temporary
> conversion buffer, so do we care?

> In message_dolog, which is called by any code which logs a message in
> *Messages*, we never call the before-change-functions for the
> *Messages* buffer, but we do call the after-change-functions for it.
> Problem or not?

"Change Hooks" in the Elisp manual states that b-c-f and a-c-f are not
called for the *Messages* buffer.  So I would say calling a-c-f here is a
bug.

> That's all I found.

> > >> In any case, my point is that the doc should still say "before any
> > >> modification" because that's really what the code *should* do.  We could
> > >> add a blurb in the doc saying that the before and after hooks may not be
> > >> properly paired (neither in number of calls nor in the specific value of
> > >> BEG/END), but we should still claim that they're both called for any and
> > >> all modifications
> > > Which is inaccurate when modifications are done in several separate
> > > parts, and you already agreed it's okay to call the hooks only once.
> > > So "for any and all modifications" is bound to draw fire from people
> > > who take that at face value.

> > They're free to misunderstand it, I'm fine with it.

> Then what is the value of such a misleading documentation?

> The current text says:

>   This variable holds a list of functions to call when Emacs is about
>   to modify a buffer.

Somebody wanting to use b-c-f and reading that text is likely to conclude
that b-c-f is called for _every_ change, just as I did ~10 years ago.

> It intentionally refrains from saying "any and all modifications", and
> instead tries to be more vague.  Do you still think this is not good
> enough?  Because if you do, I don't see how we can say anything more
> accurate and yet avoid misleading the reader.

How can accurate documentation mislead?

-- 
Alan Mackenzie (Nuremberg, Germany).