@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
(@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
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''
@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