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 (Change Hooks):
* src/insdel.c (syms_of_insdel): Clarify the intended usage of
'inhibit-modification-hooks'.

diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index f027cdf8edee74d13f2c6634d9bf2a64dbf5f380..ffdf952b081faeec15421520b31baff93e54ffbb 100644 (file)
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -5776,4 +5776,11 @@ code that is itself run from a modification hook, then rebind locally
 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 21acf0e61db0fc6e3bb526f4d2e26639cf5b85b7..dfa1cc311cad59b5d8a24b619cb00969cd5e17a9 100644 (file)
--- a/src/insdel.c
+++ b/src/insdel.c
@@ -2397,7 +2397,13 @@ This affects `before-change-functions' and `after-change-functions',
 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");