From e876f5f9fb090203b77c9cc2fa0208224ac2a1be Mon Sep 17 00:00:00 2001 From: Alan Mackenzie Date: Sat, 6 Jan 2018 18:55:08 +0000 Subject: [PATCH] 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. --- doc/lispref/text.texi | 23 +++++++++++++++-------- 1 file 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 -- 2.39.2