Various small changes in addition to:

(Making Backups): Mention return value of `backup-buffer'.
(Auto-Saving): Mention optional FORCE argument to
`delete-auto-save-file-if-necessary'.
(Reverting): Mention optional PRESERVE-MODES argument to `revert-buffer'.
Correct description of `revert-buffer-function'.

1 files changed, 46 insertions, 25 deletions

diff --git a/lispref/backups.texi b/lispref/backups.texi
index 097d358d61a..89edc6d99cf 100644
--- a/lispref/backups.texi
+++ b/lispref/backups.texi
@@ -55,6 +55,14 @@ don't want them any more, or Emacs can delete them automatically.
   This function makes a backup of the file visited by the current
 buffer, if appropriate.  It is called by @code{save-buffer} before
 saving the buffer the first time.
+
+If a backup was made by renaming, the return value is a cons cell of
+the form (@var{modes} . @var{backupname}), where @var{modes} are the
+mode bits of the original file, as returned by @code{file-modes}
+(@pxref{File Attributes,, Other Information about Files}), and
+@var{backupname} is the name of the backup.  In all other cases, that
+is, if a backup was made by copying or if no backup was made, this
+function returns @code{nil}.
 @end defun
 
 @defvar buffer-backed-up
@@ -90,7 +98,7 @@ save disk space.  (You would put this code in your init file.)
 @defvar backup-enable-predicate
 This variable's value is a function to be called on certain occasions to
 decide whether a file should have backup files.  The function receives
-one argument, a file name to consider.  If the function returns
+one argument, an absolute file name to consider.  If the function returns
 @code{nil}, backups are disabled for that file.  Otherwise, the other
 variables in this section say whether and how to make backups.
 
@@ -146,6 +154,7 @@ ignored.
 This variable's value is a function to use for making backups instead
 of the default @code{make-backup-file-name}.  A value of @code{nil}
 gives the default @code{make-backup-file-name} behaviour.
+@xref{Backup Names,, Naming Backup Files}.
 
 This could be buffer-local to do something special for specific
 files.  If you define it, you may need to change
@@ -184,25 +193,25 @@ with the new buffer contents.  The variable @code{file-precious-flag},
 if non-@code{nil}, also has this effect (as a sideline of its main
 significance).  @xref{Saving Buffers}.
 
-@defvar backup-by-copying
+@defopt backup-by-copying
 If this variable is non-@code{nil}, Emacs always makes backup files by
 copying.
-@end defvar
+@end defopt
 
   The following two variables, when non-@code{nil}, cause the second
 method to be used in certain special cases.  They have no effect on the
 treatment of files that don't fall into the special cases.
 
-@defvar backup-by-copying-when-linked
+@defopt backup-by-copying-when-linked
 If this variable is non-@code{nil}, Emacs makes backups by copying for
 files with multiple names (hard links).
 
 This variable is significant only if @code{backup-by-copying} is
 @code{nil}, since copying is always used when that variable is
 non-@code{nil}.
-@end defvar
+@end defopt
 
-@defvar backup-by-copying-when-mismatch
+@defopt backup-by-copying-when-mismatch
 If this variable is non-@code{nil}, Emacs makes backups by copying in cases
 where renaming would change either the owner or the group of the file.
 
@@ -214,9 +223,9 @@ user.
 This variable is significant only if @code{backup-by-copying} is
 @code{nil}, since copying is always used when that variable is
 non-@code{nil}.
-@end defvar
+@end defopt
 
-@defvar backup-by-copying-when-privileged-mismatch
+@defopt backup-by-copying-when-privileged-mismatch
 This variable, if non-@code{nil}, specifies the same behavior as
 @code{backup-by-copying-when-mismatch}, but only for certain user-id
 values: namely, those less than or equal to a certain number.  You set
@@ -227,7 +236,7 @@ to 0, backup by copying is done for the superuser only,
 when necessary to prevent a change in the owner of the file.
 
 The default is 200.
-@end defvar
+@end defopt
 
 @node Numbered Backups
 @subsection Making and Deleting Numbered Backup Files
@@ -379,7 +388,8 @@ This function computes the file name for a new backup file for
 @var{filename}.  It may also propose certain existing backup files for
 deletion.  @code{find-backup-file-name} returns a list whose @sc{car} is
 the name for the new backup file and whose @sc{cdr} is a list of backup
-files whose deletion is proposed.
+files whose deletion is proposed.  The value can also be @code{nil},
+which means not to make a backup.
 
 Two variables, @code{kept-old-versions} and @code{kept-new-versions},
 determine which backup versions should be kept.  This function keeps
@@ -518,7 +528,7 @@ customize the naming convention for auto-save files.  Be sure to
 change @code{auto-save-file-name-p} in a corresponding way.
 @end defun
 
-@defvar auto-save-visited-file-name
+@defopt auto-save-visited-file-name
 If this variable is non-@code{nil}, Emacs auto-saves buffers in
 the files they are visiting.  That is, the auto-save is done in the same
 file that you are editing.  Normally, this variable is @code{nil}, so
@@ -530,7 +540,7 @@ effect in an existing buffer until the next time auto-save mode is
 reenabled in it.  If auto-save mode is already enabled, auto-saves
 continue to go in the same file name until @code{auto-save-mode} is
 called again.
-@end defvar
+@end defopt
 
 @defun recent-auto-save-p
 This function returns @code{t} if the current buffer has been
@@ -547,7 +557,8 @@ function returns @code{nil}.
 The value of this variable specifies how often to do auto-saving, in
 terms of number of input events.  Each time this many additional input
 events are read, Emacs does auto-saving for all buffers in which that is
-enabled.
+enabled.  Setting this to zero disables autosaving based on the
+number of characters typed.
 @end defopt
 
 @defopt auto-save-timeout
@@ -586,24 +597,28 @@ If @var{current-only} is non-@code{nil}, only the current buffer
 is auto-saved.
 @end deffn
 
-@defun delete-auto-save-file-if-necessary
+@defun delete-auto-save-file-if-necessary &optional force
 This function deletes the current buffer's auto-save file if
 @code{delete-auto-save-files} is non-@code{nil}.  It is called every
 time a buffer is saved.
+
+Unless @var{force} is non-@code{nil}, this function only deletes the
+file if it was written by the current Emacs session since the last
+true save.
 @end defun
 
-@defvar delete-auto-save-files
+@defopt delete-auto-save-files
 This variable is used by the function
 @code{delete-auto-save-file-if-necessary}.  If it is non-@code{nil},
 Emacs deletes auto-save files when a true save is done (in the visited
 file).  This saves disk space and unclutters your directory.
-@end defvar
+@end defopt
 
 @defun rename-auto-save-file
 This function adjusts the current buffer's auto-save file name if the
 visited file name has changed.  It also renames an existing auto-save
-file.  If the visited file name has not changed, this function does
-nothing.
+file, if it was made in the current Emacs session.  If the visited
+file name has not changed, this function does nothing.
 @end defun
 
 @defvar buffer-saved-size
@@ -654,7 +669,7 @@ about them, you can get rid of them by reading in the previous version
 of the file with the @code{revert-buffer} command.  @xref{Reverting, ,
 Reverting a Buffer, emacs, The GNU Emacs Manual}.
 
-@deffn Command revert-buffer &optional ignore-auto noconfirm
+@deffn Command revert-buffer &optional ignore-auto noconfirm preserve-modes
 This command replaces the buffer text with the text of the visited
 file on disk.  This action undoes all changes since the file was visited
 or saved.
@@ -670,6 +685,10 @@ Normally, @code{revert-buffer} asks for confirmation before it changes
 the buffer; but if the argument @var{noconfirm} is non-@code{nil},
 @code{revert-buffer} does not ask for confirmation.
 
+Normally, this command reinitializes the file's major and minor modes
+using @code{normal-mode}.  But if @var{preserve-modes} is
+non-@code{nil}, the modes remain unchanged.
+
 Reverting tries to preserve marker positions in the buffer by using the
 replacement feature of @code{insert-file-contents}.  If the buffer
 contents and the file contents are identical before the revert
@@ -682,22 +701,24 @@ the buffer.  Preserving any additional markers would be problematical.
 You can customize how @code{revert-buffer} does its work by setting
 the variables described in the rest of this section.
 
-@defvar revert-without-query
+@defopt revert-without-query
 This variable holds a list of files that should be reverted without
 query.  The value is a list of regular expressions.  If the visited file
 name matches one of these regular expressions, and the file has changed
 on disk but the buffer is not modified, then @code{revert-buffer}
 reverts the file without asking the user for confirmation.
-@end defvar
+@end defopt
 
   Some major modes customize @code{revert-buffer} by making
 buffer-local bindings for these variables:
 
 @defvar revert-buffer-function
-The value of this variable is the function to use to revert this buffer.
-If non-@code{nil}, it is called as a function with no arguments to do
-the work of reverting.  If the value is @code{nil}, reverting works the
-usual way.
+The value of this variable is the function to use to revert this
+buffer.  If non-@code{nil}, it should be a function with two optional
+arguments to do the work of reverting.  The two optional arguments,
+@var{ignore-auto} and @var{noconfirm}, are the arguments that
+@code{revert-buffer} received.  If the value is @code{nil}, reverting
+works the usual way.
 
 Modes such as Dired mode, in which the text being edited does not
 consist of a file's contents but can be regenerated in some other