Cc: address@hidden, address@hidden
From: Daniel Colascione <address@hidden>
Date: Tue, 30 Aug 2016 10:27:45 -0700
+The region given to each of these functions is a conservative
+approximation of the region about to changed. After running the
+before-change-functions, Emacs will make zero or more fine-grained
+buffer changes and run after-change-functions for each. Do not expect
+before-change-functions and after-change-functions to be called in
+balanced pairs.
The last sentence here is repeated afterwards, for no good reason.
(Also, the markup is missing, but that's just an aside.)
- Do @emph{not} expect the before-change hooks and the after-change
-hooks be called in balanced pairs around each buffer change. Also
-don't expect the before-change hooks to be called for every chunk of
-text Emacs is about to delete. These hooks are provided on the
-assumption that Lisp programs will use either before- or the
-after-change hooks, but not both, and the boundaries of the region
-where the changes happen might include more than just the actual
-changed text, or even lump together several changes done piecemeal.
+ Do @emph{not} expect the before-change hooks and the after-change
+hooks be called in balanced pairs around each buffer change.
+The before-change-functions region is a conservative bound on the zero
+or more fine-grained changes to follow. Emacs informs user code about
+the actual changes to the buffer through calls to
+after-change-functions; these fine-grained changes will always fall
+inside the broad change region Emacs describes by calling
+before-change-functions.
You removed the part about text deletion, which is not specific to
revert-buffer, so that information is now lost. I don't want to lose
it.
If all you want is to remove this part:
These hooks are provided on the assumption that Lisp programs will
use either before- or the after-change hooks, but not both
then I don't necessarily mind, although I do believe it is true, and
the readers should be aware of that.