From 8c17995f7f948955c765562f32526d0a3b87398e Mon Sep 17 00:00:00 2001 From: Alan Mackenzie Date: Tue, 25 Jun 2019 08:52:38 +0000 Subject: [PATCH] Fix documentation of inhibit-modification-hooks in overlays + text properties This fixes bug #25111. * doc/lispref/display.text (Overlay Properties): For the hook property modification-hooks, state that inhibit-modification-hooks is bound to non-nil when calling its functions. This also applies to insert-in-front-hooks and insert-behind-hooks, which refer to modification-hooks. * doc/lispref/text.texi (Special Properties): For the hook property modification-hooks, state that inhibit-modification-hooks is NOT bound to non-nil when calling its functions. For the hooks insert-in-fron-hooks and insert-behind-hooks, state that that variable does get bound to non-nil. --- doc/lispref/display.texi | 9 ++++++--- doc/lispref/text.texi | 21 +++++++++++++++++---- 2 files changed, 23 insertions(+), 7 deletions(-) diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index 7e8abb04400..217df3b2cc2 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -1752,9 +1752,12 @@ modified, and the length of the pre-change text replaced by that range. length is the number of characters deleted, and the post-change beginning and end are equal.) -If these functions modify the buffer, they should bind -@code{inhibit-modification-hooks} to @code{t} around doing so, to -avoid confusing the internal mechanism that calls these hooks. +When these functions are called, @code{inhibit-modification-hooks} is +bound to non-@code{nil}. If the functions modify the buffer, you +might want to bind @code{inhibit-modification-hooks} to @code{nil}, so +as to cause the change hooks to run for these modifications. However, +doing this may call your own change hook recursively, so be sure to +prepare for that. @xref{Change Hooks}. Text properties also support the @code{modification-hooks} property, but the details are somewhat different (@pxref{Special Properties}). diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi index 2e7c497f577..c4fc5247a11 100644 --- a/doc/lispref/text.texi +++ b/doc/lispref/text.texi @@ -3621,9 +3621,12 @@ Furthermore, insertion will not modify any existing character, so this hook will only be run when removing some characters, replacing them with others, or changing their text-properties. -If these functions modify the buffer, they should bind -@code{inhibit-modification-hooks} to @code{t} around doing so, to -avoid confusing the internal mechanism that calls these hooks. +Unlike with other similar hooks, when Emacs calls these functions, +@code{inhibit-modification-hooks} does @emph{not} get bound to +non-@code{nil}. If the functions modify the buffer, you should +consider binding this variable to non-@code{nil} to prevent any buffer +changes running the change hooks. Otherwise, you must be prepared for +recursive calls. @xref{Change Hooks}. Overlays also support the @code{modification-hooks} property, but the details are somewhat different (@pxref{Overlay Properties}). @@ -3639,6 +3642,13 @@ preceding character. These functions receive two arguments, the beginning and end of the inserted text. The functions are called @emph{after} the actual insertion takes place. +When these functions are called, @code{inhibit-modification-hooks} is +bound to non-@code{nil}. If the functions modify the buffer, you +might want to bind @code{inhibit-modification-hooks} to @code{nil}, so +as to cause the change hooks to run for these modifications. However, +doing this may call your own change hook recursively, so be sure to +prepare for that. + See also @ref{Change Hooks}, for other hooks that are called when you change text in a buffer. @@ -5650,5 +5660,8 @@ same hook variables, so that by default modifying the buffer from a modification hook does not cause other modification hooks to be run. If you do want modification hooks to be run in a particular piece of code that is itself run from a modification hook, then rebind locally -@code{inhibit-modification-hooks} to @code{nil}. +@code{inhibit-modification-hooks} to @code{nil}. However, doing this +may cause recursive calls to the modification hooks, so be sure to +prepare for that (for example, by binding some variable which tells +your hook to do nothing). @end defvar -- 2.39.5