diff options
author | Alan Mackenzie <acm@muc.de> | 2018-01-06 18:55:08 +0000 |
---|---|---|
committer | Alan Mackenzie <acm@muc.de> | 2018-01-06 18:55:08 +0000 |
commit | e876f5f9fb090203b77c9cc2fa0208224ac2a1be (patch) | |
tree | 5b24ab303829acecab0e1002c259f898e96d6f7f | |
parent | 3a22097cf68761aa106a5455409b7eec689efd88 (diff) | |
download | emacs-e876f5f9fb090203b77c9cc2fa0208224ac2a1be.tar.gz |
Describe the precise interaction of complex primitives with the change hooks
* doc/lispref/text.texi (Change Hooks): Document that most buffer changing
primitives call before- and after-change-functions in balanced pairs, but that
some complex primitives call b-c-f once, and a-c-f zero, one, or several
times.
-rw-r--r-- | doc/lispref/text.texi | 23 |
1 files changed, 15 insertions, 8 deletions
diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi index f590a20896f..cd644478d4b 100644 --- a/doc/lispref/text.texi +++ b/doc/lispref/text.texi @@ -5023,14 +5023,21 @@ these functions, and neither do certain internal buffer changes, such as changes in buffers created by Emacs internally for certain jobs, that should not be visible to Lisp programs. - 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. +The vast bulk of buffer changing primitives will call +@code{before-change-functions} and @code{after-change-functions} in +balanced pairs, once for each change, where the arguments to these +hooks exactly delimit the change being made. Yet, hook functions +should not rely on this always being the case: + +Other, complex primitives call @code{before-change-functions} once +before making changes, and then call @code{after-change-functions} +zero, one, or several times, depending on how many individual changes +the primitive is making. The arguments to +@code{before-change-functions} will enclose a region in which the +individual changes are made, but won't necessarily be the minimal such +region. The arguments to each successive call of +@code{after-change-functions} will then delimit the current part of +the change exactly. @defmac combine-after-change-calls body@dots{} The macro executes @var{body} normally, but arranges to call the |