X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/7951ad77ddb6351312bd5c88af082af80787612e..106e6894f2e5473d56b9ac865cd4c3f3b6ed884b:/doc/lispref/files.texi

diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index 17d439725d..cd1ee68f56 100644
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -1269,6 +1269,17 @@ is on file system number -32252.
 @end table
 @end defun
 
+@cindex MS-DOS and file modes
+@cindex file modes and MS-DOS
+  On MS-DOS, there is no such thing as an ``executable'' file mode bit.
+So Emacs considers a file executable if its name ends in one of the
+standard executable extensions, such as @file{.com}, @file{.bat},
+@file{.exe}, and some others.  Files that begin with the Unix-standard
+@samp{#!} signature, such as shell and Perl scripts, are also considered
+as executable files.  This is reflected in the values returned by
+@code{file-modes} and @code{file-attributes}.  Directories are also
+reported with executable bit set, for compatibility with Unix.
+
 @node Locating Files
 @subsection How to Locate Files in Standard Places
 @cindex locate file in path
@@ -1570,17 +1581,6 @@ time and must be in the format returned by @code{current-time}
 (@pxref{Time of Day}).
 @end defun
 
-@cindex MS-DOS and file modes
-@cindex file modes and MS-DOS
-  On MS-DOS, there is no such thing as an ``executable'' file mode bit.
-So Emacs considers a file executable if its name ends in one of the
-standard executable extensions, such as @file{.com}, @file{.bat},
-@file{.exe}, and some others.  Files that begin with the Unix-standard
-@samp{#!} signature, such as shell and Perl scripts, are also considered
-as executable files.  This is reflected in the values returned by
-@code{file-modes} and @code{file-attributes}.  Directories are also
-reported with executable bit set, for compatibility with Unix.
-
 @node File Names
 @section File Names
 @cindex file names
@@ -2491,22 +2491,25 @@ files that are directories.  For example, you cannot delete a directory
 with @code{delete-file}.  These special functions exist to create and
 delete directories.
 
-@defun make-directory dirname &optional parents
-This function creates a directory named @var{dirname}.
-If @var{parents} is non-@code{nil}, as is always the case in an
+@findex mkdir
+@deffn Command make-directory dirname &optional parents
+This command creates a directory named @var{dirname}.  If
+@var{parents} is non-@code{nil}, as is always the case in an
 interactive call, that means to create the parent directories first,
 if they don't already exist.
-@end defun
 
-@defun delete-directory dirname
-This function deletes the directory named @var{dirname}.  The function
+@code{mkdir} is an alias for this.
+@end deffn
+
+@deffn Command delete-directory dirname
+This command deletes the directory named @var{dirname}.  The function
 @code{delete-file} does not work for files that are directories; you
 must use @code{delete-directory} for them.  If the directory contains
 any files, @code{delete-directory} signals an error.
 
-This function only follows symbolic links at the level of parent
-directories.
-@end defun
+@code{delete-directory} only follows symbolic links at the level of
+parent directories.
+@end deffn
 
 @node Magic File Names
 @section Making Certain File Names ``Magic''
@@ -3070,18 +3073,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 +3091,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