bug#25111:

[phillip.lord@russet.org.uk (Phillip Lord)]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: phillip.lord@russet.org.uk (Phillip Lord)
>> Cc: 25111@debbugs.gnu.org
>> Date: Fri, 09 Dec 2016 17:17:51 +0000
>>
>> My own feeling is that "inhibit-modification-hooks" should *only* be for
>> modifications that really should not be detected by anything else. I can
>> think of examples of this (I used to change the buffer to display a
>> completion string to the user for instance, although I now use an
>> "after-string" overlay property).
>> 
>> The simplest advice makes calls to the modification hooks consistent is
>> to say "You should not modify the buffer on these hooks". The potential
>> solution, for instance, for yasnippet is to record the changes on
>> after-change-function, and then change the buffer on
>> post-command-hook. I think this would work? Is this what the manual
>> should say?
>
> IMO, the manual should advise the safe practices, and then tell how to
> behave if the code really needs to play it less safe.  The former
> would be what you say above, I think.  But since we know there are
> packages out there that don't choose the safe approach, we should
> cover those as well.


So, instead of this:

     If these functions modify the buffer, they should bind
     ‘inhibit-modification-hooks’ to ‘t’ around doing so, to avoid
     confusing the internal mechanism that calls these hooks.


We could have:

    These functions should avoid unnecessarily modifying the buffer.
    Emacs binds 'inhibit-modification-hooks' to `t' during their
    evaluation, which means that any modifications will not be signalled
    to other hook functions listening for them.


Perhaps a better solution would be:


    These functions should avoid unnecessarily modifying the buffer; see
    Change Hooks for further details.


Then a new paragraph can be added to the Change Hooks section talking
about the complexity of modifying buffers on these hooks, with
alternatives.

I am happy to draft something if you wish.

Phil