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

[Eli Zaretskii]

> Date: Fri, 19 Aug 2016 08:45:26 +0000
> Cc: Stefan Monnier <address@hidden>, address@hidden
> From: Alan Mackenzie <address@hidden>
> 
> > 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.

The arguments are not inaccurate: what insert-file-contents does in
that case is really replace the text between point-min and point-max
with what's in the file on disk.  That it includes internal
optimizations which actually try to make minimal changes is just that
-- an optimization.  Modes that hook the changes cannot depend on
internal optimizations like that.

More generally, since CC mode already knows how to recalculate
everything when a buffer is reverted, this should no longer be an
issue.

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

You are reading the manual too literally.

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

Then they will be wrong, because the text doesn't say so.

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

By using terminology that is not rigorously defined.  Like "buffer
modification", for example.  You yourself say that
set-buffer-multibyte shouldn't call the modification hooks, but that
function surely does perform "buffer modifications" in some sense of
that term.