From 7f6453596b7753af7704eaac7f27ebba8d03cfc4 Mon Sep 17 00:00:00 2001 From: Alan Mackenzie Date: Sun, 19 May 2019 20:31:19 +0000 Subject: [PATCH] Clarify elisp ref for inhibit-modification-hooks (Bug#25111) * doc/lispref/display.texi (Overlay Properties): * doc/lispref/text.texi (Change Hooks): Explain that inhibit-modification-hooks is bound to t while executing change hooks, and suggest binding to nil with suitable precautions when modifying buffer from a change hook. (Special Properties): Emphasize that inhibit-modification-hooks is left set to nil when executing text property change hooks. Co-authored-by: Noam Postavsky --- doc/lispref/display.texi | 6 +++--- doc/lispref/text.texi | 12 ++++++++---- 2 files changed, 11 insertions(+), 7 deletions(-) diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index b07999432c..59d02d540a 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -1708,9 +1708,9 @@ Overlay Properties 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. +Similar to change hooks, when these functions are called, +@code{inhibit-modification-hooks} is bound to @code{t}. @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 f3d222b708..c935cfe49b 100644 --- a/doc/lispref/text.texi +++ b/doc/lispref/text.texi @@ -3514,9 +3514,10 @@ Special Properties 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. +When Emacs calls these functions, @code{inhibit-modification-hooks} is +set to @code{nil}, unlike for change hooks. When writing a function +which modifies the buffer, consider binding it @code{t}, to avoid +recursive calls. @xref{Change Hooks}. Overlays also support the @code{modification-hooks} property, but the details are somewhat different (@pxref{Overlay Properties}). @@ -5093,5 +5094,8 @@ Change Hooks 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.11.0