# HG changeset patch
# User Stefan Monnier <monnier@iro.umontreal.ca>
# Date 1284825006 -7200
# Node ID 0abc226eaa6642c83de66131fa7edf9d2e88018d
# Parent  5bbd74302c45ea22df07ae9cd5f198db1d02e3c6
* lispref/text.texi (Special Properties): Clarify when modification-hooks run.

diff -r 5bbd74302c45 -r 0abc226eaa66 doc/lispref/ChangeLog
--- a/doc/lispref/ChangeLog	Sat Sep 18 16:23:29 2010 +0200
+++ b/doc/lispref/ChangeLog	Sat Sep 18 17:50:06 2010 +0200
@@ -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 -r 5bbd74302c45 -r 0abc226eaa66 doc/lispref/text.texi
--- a/doc/lispref/text.texi	Sat Sep 18 16:23:29 2010 +0200
+++ b/doc/lispref/text.texi	Sat Sep 18 17:50:06 2010 +0200
@@ -3230,12 +3230,16 @@
 @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