From 8e2a5a8c8381c85d138f34d37931c52c289da2ba Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=A0t=C4=9Bp=C3=A1n=20N=C4=9Bmec?= Date: Tue, 31 Mar 2020 05:38:50 +0200 Subject: [PATCH] Clarify documentation on inhibit-modification-hooks intended usage Cf. bug#40332 and the discussion at https://lists.gnu.org/archive/html/emacs-devel/2020-03/msg00921.html --- doc/lispref/text.texi | 7 +++++++ src/insdel.c | 8 +++++++- 2 files changed, 14 insertions(+), 1 deletion(-) diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi index 3bb055a68d..0d32c571b7 100644 --- a/doc/lispref/text.texi +++ b/doc/lispref/text.texi @@ -5776,4 +5776,11 @@ Change Hooks 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). + +We recommend that you only bind this variable for modifications that +do not result in lasting changes to buffer text contents (for example +face changes or temporary modifications). If you need to delay change +hooks during a series of changes (typically for performance reasons), +use @code{combine-change-calls} or @code{combine-after-change-calls} +instead. @end defvar diff --git a/src/insdel.c b/src/insdel.c index 21acf0e61d..dfa1cc311c 100644 --- a/src/insdel.c +++ b/src/insdel.c @@ -2397,7 +2397,13 @@ syms_of_insdel (void) as well as hooks attached to text properties and overlays. Setting this variable non-nil also inhibits file locks and checks whether files are locked by another Emacs session, as well as -handling of the active region per `select-active-regions'. */); +handling of the active region per `select-active-regions'. + +To delay change hooks during a series of changes, use +`combine-change-calls' or `combine-after-change-calls' instead of +binding this variable. + +See also the info node `(elisp) Change Hooks'. */); inhibit_modification_hooks = 0; DEFSYM (Qinhibit_modification_hooks, "inhibit-modification-hooks"); -- 2.26.0