@c ??? for `write-region-annotate-functions', below? --ttn
In contrast, when reading, the annotations intermixed with the text
-are handled immediately. @code{insert-file-contents} sets point to the
-beginning of some text to be converted, then calls the conversion
+are handled immediately. @code{insert-file-contents} sets point to
+the beginning of some text to be converted, then calls the conversion
functions with the length of that text. These functions should always
-return with point at the beginning of the inserted text. This approach
-makes sense for reading because annotations removed by the first
-converter can't be mistakenly processed by a later converter.
-
- Each conversion function should scan for the annotations it
-recognizes, remove the annotation, modify the buffer text (to set a text
-property, for example), and return the updated length of the text, as it
-stands after those changes. The value returned by one function becomes
-the argument to the next function.
+return with point at the beginning of the inserted text. This
+approach makes sense for reading because annotations removed by the
+first converter can't be mistakenly processed by a later converter.
+Each conversion function should scan for the annotations it
+recognizes, remove the annotation, modify the buffer text (to set a
+text property, for example), and return the updated length of the
+text, as it stands after those changes. The value returned by one
+function becomes the argument to the next function.
@defvar write-region-annotate-functions
A list of functions for @code{write-region} to call. Each function in
to be written. These functions should not alter the contents of the
buffer. Instead, they should return annotations.
-@c ??? Following adapted from comment in `build_annotations' (fileio.c).
-@c ??? Perhaps this is intended for internal use only?
-@c ??? Someone who understands this, please reword it. --ttn
-As a special case, if a function returns with a different buffer
-current, Emacs takes it to mean the current buffer contains altered text
-to be output, and discards all previous annotations because they should
-have been dealt with by this function.
+As a special case, a function may return with a different buffer
+current. Emacs takes this to mean that the current buffer contains
+altered text to be output. It therefore changes the @var{start} and
+@var{end} arguments of the @code{write-region} call, giving them the
+values of @code{point-min} and @code{point-max} in the new buffer,
+respectively. It also discards all previous annotations, because they
+should have been dealt with by this function.
+@end defvar
+
+@defvar write-region-post-annotation-function
+The value of this variable, if non-@code{nil}, should be a function.
+This function is called, with no arguments, after @code{write-region}
+has completed.
+
+If any function in @code{write-region-annotate-functions} returns with
+a different buffer current, Emacs calls
+@code{write-region-post-annotation-function} more than once. Emacs
+calls it with the last buffer that was current, and again with the
+buffer before that, and so on back to the original buffer.
+
+Thus, a function in @code{write-region-annotate-functions} can create
+a buffer, give this variable the local value of @code{kill-buffer} in
+that buffer, set up the buffer with altered text, and make the buffer
+current. The buffer will be killed after @code{write-region} is done.
@end defvar
@defvar after-insert-file-functions