From ab19c39b45e8225b32a44ae2aa335c5870dd3e98 Mon Sep 17 00:00:00 2001 From: Luc Teirlinck Date: Mon, 5 Apr 2004 01:28:57 +0000 Subject: [PATCH] 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'. --- lispref/backups.texi | 71 ++++++++++++++++++++++++++++++++++------------------ 1 file 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 -- 2.11.4.GIT