(Format Conversion Round-Trip): Mention `preserve' element of `format-alist'.

2 files changed, 15 insertions, 3 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index e488b0020aa..3f400bc5899 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,8 @@
+2008-11-20  Glenn Morris  <rgm@gnu.org>
+
+        * files.texi (Format Conversion Round-Trip): Mention `preserve'
+        element of `format-alist'.
+
 2008-11-19  Glenn Morris  <rgm@gnu.org>
 
         * doclicense.texi: Update to FDL 1.3.
diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index 58cc61108e7..3ffc2967311 100644
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -2877,7 +2877,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 +2950,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 +2983,11 @@ 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, the buffer-local value of
+@code{buffer-file-format} is set to @var{format}, and any original
+elements (except any with a non-nil @var{preserve} flag; see above) are
+replaced.  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}.