bug#25111: (Inaccurate documentation of inhibit-modification-hooks)

[Eli Zaretskii <eliz@gnu.org>]

> Date: Tue, 04 Jun 2019 17:36:12 +0300
> From: Eli Zaretskii <eliz@gnu.org>
> Cc: phillip.lord@russet.org.uk, 25111@debbugs.gnu.org, npostavs@gmail.com
> 
> > Date: Tue, 4 Jun 2019 09:32:41 +0000
> > Cc: Eli Zaretskii <eliz@gnu.org>, Phillip Lord <phillip.lord@russet.org.uk>,
> >   25111@debbugs.gnu.org
> > From: Alan Mackenzie <acm@muc.de>
> > 
> > > > This is difficult to document coherently.
> > 
> > > And confusing, as evidenced by the fact that we both got confused about
> > > it in this very thread :)
> > 
> > > > My proposal of last week was to fix the code, also to bind
> > > > inhibit-modification-hooks to t for the modification-hooks overlay
> > > > property, even though this would be an incompatibility in Lisp.
> > 
> > How about this?
> 
> Please wait with this for a few days.

OK, after re-reading the discussions and the code, I don't think we
should make the incompatible change suggested by Alan.  We haven't
bound inhibit-modification-hooks to t in the text-property hooks since
the day the code was written, 24 years ago, so it makes no sense to me
to do that now.  Let's document the exception and move on.

Noam's last patch LGTM, with the single minor gotcha:

> +When Emacs calls these functions, @code{inhibit-modification-hooks} is
> +set to @code{nil}, unlike for change hooks.

This is from the part that changes the "Special Properties" node, and
it's inaccurate: we don't bind inhibit-modification-hooks to nil, we
just leave it at its previous binding.  This distinction is important
in recursive calls, when the caller caused inhibit-modification-hooks
to be bound to non-nil.

Another minor comment, although not to the proposed text, is that the
fact that inhibit-modification-hooks is bound to t when the hook
specified by the overlay properties are called is because those hooks
are called from within signal_before_change and signal_after_change,
which perform these bindings, and the bindings stay in effect both for
before/after-change-functions and for hooks specified by overlay
properties.  By contrast, the hooks specified by text properties are
called before that binding becomes in effect (which is why we need a
separate check whether inhibit_modification_hooks are non-nil inside
verify_interval_modification, which calls the text-property hooks).

Thanks.