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'.

1 files changed, 7 insertions, 0 deletions

diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index f027cdf8ede..ffdf952b081 100644
--- 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