[Emacs-diffs] emacs/doc/lispref files.texi

[Chong Yidong]

CVSROOT:        /sources/emacs
Module name:    emacs
Changes by:     Chong Yidong <cyd>      09/01/22 04:53:41

Modified files:
        doc/lispref    : files.texi 

Log message:
        (Format Conversion Piecemeal): Clarify behavior of
        write-region-annotate-functions.  Document
        write-region-post-annotation-function.

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/emacs/doc/lispref/files.texi?cvsroot=emacs&r1=1.17&r2=1.18

Patches:
Index: files.texi
===================================================================
RCS file: /sources/emacs/emacs/doc/lispref/files.texi,v
retrieving revision 1.17
retrieving revision 1.18
diff -u -b -r1.17 -r1.18
--- files.texi  10 Jan 2009 12:42:58 -0000      1.17
+++ files.texi  22 Jan 2009 04:53:41 -0000      1.18
@@ -3070,18 +3070,17 @@
 @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 @@
 to be written.  These functions should not alter the contents of the
 buffer.  Instead, they should return annotations.
 
address@hidden ??? Following adapted from comment in `build_annotations' 
(fileio.c).
address@hidden ??? Perhaps this is intended for internal use only?
address@hidden ??? 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
address@hidden 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.
address@hidden defvar
+
address@hidden write-region-post-annotation-function
+The value of this variable, if address@hidden, 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
address@hidden 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