(Format Conversion Round-Trip): Improve previous change.

[bpt/emacs.git] / doc / lispref / files.texi

diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index 58cc611..45b911f 100644 (file)
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -1555,7 +1555,8 @@ This subroutine converts a symbolic specification of file mode bits in
 @var{modes} into the equivalent numeric value.  If the symbolic
 specification is based on an existing file, that file's mode bits are
 taken from the optional argument @var{base-modes}; if that argument is
-omitted or nil, it defaults to zero, i.e.@: no access rights at all.
+omitted or @code{nil}, it defaults to zero, i.e.@: no access rights at
+all.
 @end defun
 
 @defun set-file-times filename &optional time
@@ -2801,12 +2802,12 @@ making connections when they don't exist.
 @end defun
 
 @defun unhandled-file-name-directory filename
-This function returns the name of a directory that is not magic.
-It uses the directory part of @var{filename} if that is not magic.
-For a magic file name, it invokes the file name handler, which
-therefore decides what value to return.  If @var{filename} is not
-accessible from a local process, then the file name handler should
-indicate it by returning nil.
+This function returns the name of a directory that is not magic.  It
+uses the directory part of @var{filename} if that is not magic.  For a
+magic file name, it invokes the file name handler, which therefore
+decides what value to return.  If @var{filename} is not accessible
+from a local process, then the file name handler should indicate it by
+returning @code{nil}.
 
 This is useful for running a subprocess; every subprocess must have a
 non-magic directory to serve as its current directory, and this function
@@ -2877,7 +2878,7 @@ This list contains one format definition for each defined file format.
 Each format definition is a list of this form:
 
 @example
-(@var{name} @var{doc-string} @var{regexp} @var{from-fn} @var{to-fn} @var{modify} @var{mode-fn})
+(@var{name} @var{doc-string} @var{regexp} @var{from-fn} @var{to-fn} @var{modify} @var{mode-fn} @var{preserve})
 @end example
 @end defvar
 
@@ -2950,6 +2951,10 @@ A flag, @code{t} if the encoding function modifies the buffer, and
 A minor-mode function to call after visiting a file converted from this
 format.  The function is called with one argument, the integer 1;
 that tells a minor-mode function to enable the mode.
+
+@item preserve
+A flag, @code{t} if @code{format-write-file} should not remove this format
+from @code{buffer-file-format}.
 @end table
 
 The function @code{insert-file-contents} automatically recognizes file
@@ -2979,8 +2984,12 @@ in the order of appearance in the list.
 @deffn Command format-write-file file format &optional confirm
 This command writes the current buffer contents into the file
 @var{file} in format @var{format}, and makes that format the default
-for future saves of the buffer.  The argument @var{format} is a list
-of format names.  Except for the @var{format} argument, this command
+for future saves of the buffer.  That is, it sets the buffer-local value
+of @code{buffer-file-format} to @var{format}.  It then appends any
+elements of the previous value with a non-nil @var{preserve} flag (see
+above), if they are not already present in the new value.
+The argument @var{format} is a list of format names.
+Except for the @var{format} argument, this command
 is similar to @code{write-file}.  In particular, @var{confirm} has the
 same meaning and interactive treatment as the corresponding argument
 to @code{write-file}.  @xref{Definition of write-file}.