2 files changed, 14 insertions, 6 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index e3df5fab9e9..ec065e9ce76 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,7 @@
+2010-09-18  Stefan Monnier  <monnier@iro.umontreal.ca>
+
+        * text.texi (Special Properties): Clarify when modification-hooks run.
+
 2010-09-11  Stefan Monnier  <monnier@iro.umontreal.ca>
 
         * syntax.texi (Syntax Flags): Document new `c' flag.
diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index ff4e65d299f..04e1e714133 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -3230,12 +3230,16 @@ the @code{line-prefix} variable).  @xref{Truncation}.
 @cindex hooks for changing a character
 @kindex modification-hooks @r{(text property)}
 If a character has the property @code{modification-hooks}, then its
-value should be a list of functions; modifying that character calls all
-of those functions.  Each function receives two arguments: the beginning
-and end of the part of the buffer being modified.  Note that if a
-particular modification hook function appears on several characters
-being modified by a single primitive, you can't predict how many times
-the function will be called.
+value should be a list of functions; modifying that character calls
+all of those functions before the actual modification.  Each function
+receives two arguments: the beginning and end of the part of the
+buffer being modified.  Note that if a particular modification hook
+function appears on several characters being modified by a single
+primitive, you can't predict how many times the function will
+be called.
+Furthermore, insertion will not modify any existing character, so this
+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