(Format Conversion Piecemeal): Clarify behavior of

write-region-annotate-functions.  Document
write-region-post-annotation-function.

1 files changed, 34 insertions, 18 deletions

diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index 17d439725d5..8d02831a7fb 100644
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -3070,18 +3070,17 @@ place without modifying the buffer.
 @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
@@ -3089,13 +3088,30 @@ the list is called with two arguments: the start and end of the region
 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