(Format Conversion Round-Trip): Rewrite format-write-file section yet again.

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

diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index 45b911f..9bd882f 100644 (file)
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -2982,17 +2982,17 @@ encoding functions for the formats listed in @code{buffer-file-format},
 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.  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}.
+This command writes the current buffer contents into the file @var{file}
+in a format based on @var{format}, which is a list of format names.  It
+constructs the actual format starting from @var{format}, then appending
+any elements from the value of @code{buffer-file-format} with a non-nil
+@var{preserve} flag (see above), if they are not already present in
+@var{format}.  It then updates @code{buffer-file-format} with this
+format, making it the default for future saves.  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}.
 @end deffn
 
 @deffn Command format-find-file file format