From 568e640f962cd9a59d695351ded11c4a8e781f06 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 (Special Properties) (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. Co-authored-by: Noam Postavsky --- doc/lispref/display.texi | 9 ++++++--- doc/lispref/text.texi | 12 ++++++++---- 2 files changed, 14 insertions(+), 7 deletions(-) diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index b07999432c..f7140f444e 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -1708,9 +1708,12 @@ 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. +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 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 f3d222b708..5954161fcf 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 non-@code{nil}. If the functions modify the buffer, you should +consider binding this variable to @code{nil}, but in that case 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}). @@ -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