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

[Eli Zaretskii <eliz@gnu.org>]

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

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.

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?

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?

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.

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.