From 0360792967fa95567a9ec2d767f3a33563c1bbc5 Mon Sep 17 00:00:00 2001 From: Glenn Morris Date: Thu, 3 Apr 2014 21:49:28 -0400 Subject: [PATCH] Doc updates for default values of some -function vars no longer being nil * doc/emacs/files.texi (Backup Names): * doc/emacs/arevert-xtra.texi (Supporting additional buffers): * doc/lispref/backups.texi (Making Backups, Reverting): Update for default values of some -function vars no longer being nil. * etc/NEWS: Related edits. --- doc/emacs/ChangeLog | 6 ++++++ doc/emacs/arevert-xtra.texi | 6 +++--- doc/emacs/files.texi | 4 ++-- doc/lispref/ChangeLog | 5 +++++ doc/lispref/backups.texi | 39 +++++++++++++++++-------------------- etc/NEWS | 2 ++ 6 files changed, 36 insertions(+), 26 deletions(-) diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog index 34679b8ba1d..bd593f49db3 100644 --- a/doc/emacs/ChangeLog +++ b/doc/emacs/ChangeLog @@ -1,3 +1,9 @@ +2014-04-04 Glenn Morris + + * files.texi (Backup Names): + * arevert-xtra.texi (Supporting additional buffers): + Update for default values of some -function vars no longer being nil. + 2014-03-16 Dmitry Gutov * programs.texi (Matching): Update the missed spot. (Bug#17008) diff --git a/doc/emacs/arevert-xtra.texi b/doc/emacs/arevert-xtra.texi index a13f59b69bd..0f05d1db0e1 100644 --- a/doc/emacs/arevert-xtra.texi +++ b/doc/emacs/arevert-xtra.texi @@ -103,11 +103,11 @@ arguments to list only some of the files. @file{*Find*} and This section is intended for Elisp programmers who would like to add support for auto-reverting new types of buffers. -To support auto-reverting the buffer must first of all have a +To support auto-reverting the buffer must first of all have a suitable @code{revert-buffer-function}. @xref{Definition of revert-buffer-function,, Reverting, elisp, the Emacs Lisp Reference Manual}. -In addition, it @emph{must} have a @code{buffer-stale-function}. +In addition, it must have a @code{buffer-stale-function}. @c FIXME only defvar in all of doc/emacs! @defvar buffer-stale-function @@ -149,7 +149,7 @@ also be useful if the function is consulted for purposes other than auto-reverting. @end defvar -Once the buffer has a @code{revert-buffer-function} and a +Once the buffer has a suitable @code{revert-buffer-function} and @code{buffer-stale-function}, several problems usually remain. The buffer will only auto-revert if it is marked unmodified. Hence, diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi index 3b9aefa332b..9310c44f1e6 100644 --- a/doc/emacs/files.texi +++ b/doc/emacs/files.texi @@ -594,8 +594,8 @@ directory. Emacs creates the directory, if necessary, to make the backup. @vindex make-backup-file-name-function - If you define the variable @code{make-backup-file-name-function} to -a suitable Lisp function, that overrides the usual way Emacs + If you set the variable @code{make-backup-file-name-function} to +a suitable Lisp function, you can override the usual way Emacs constructs backup file names. @node Backup Deletion diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index bf3c6f170ea..456c2cbdc12 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,8 @@ +2014-04-04 Glenn Morris + + * backups.texi (Making Backups, Reverting): + Update for default values of some -function vars no longer being nil. + 2014-03-25 Eli Zaretskii * files.texi (Kinds of Files): Improve documentation of diff --git a/doc/lispref/backups.texi b/doc/lispref/backups.texi index 83ffb2f95e4..9fa97fc1300 100644 --- a/doc/lispref/backups.texi +++ b/doc/lispref/backups.texi @@ -90,8 +90,7 @@ save disk space. (You would put this code in your init file.) @smallexample @group (add-hook 'rmail-mode-hook - (lambda () - (set (make-local-variable 'make-backup-files) nil))) + (lambda () (setq-local make-backup-files nil))) @end group @end smallexample @end defopt @@ -150,13 +149,12 @@ ignored. @end defopt @defopt make-backup-file-name-function -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} behavior. +This variable's value is a function to use for making backup file names. +The function @code{make-backup-file-name} calls it. @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 +files. If you change it, you may need to change @code{backup-file-name-p} and @code{file-name-sans-versions} too. @end defopt @@ -727,25 +725,24 @@ buffer-local bindings for these variables: @defvar revert-buffer-function @anchor{Definition of revert-buffer-function} 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 +buffer. 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. +@code{revert-buffer} received. 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 -fashion, can give this variable a buffer-local value that is a function to -regenerate the contents. +fashion, can give this variable a buffer-local value that is a special +function to regenerate the contents. @end defvar @defvar revert-buffer-insert-file-contents-function -The value of this variable, if non-@code{nil}, specifies the function to use to +The value of this variable specifies the function to use to insert the updated contents when reverting this buffer. The function receives two arguments: first the file name to use; second, @code{t} if the user has asked to read the auto-save file. -The reason for a mode to set this variable instead of +The reason for a mode to change this variable instead of @code{revert-buffer-function} is to avoid duplicating or replacing the rest of what @code{revert-buffer} does: asking for confirmation, clearing the undo list, deciding the proper major mode, and running the @@ -753,21 +750,21 @@ hooks listed below. @end defvar @defvar before-revert-hook -This normal hook is run by @code{revert-buffer} before -inserting the modified contents---but only if -@code{revert-buffer-function} is @code{nil}. +This normal hook is run by the default @code{revert-buffer-function} +before inserting the modified contents. A custom @code{revert-buffer-function} +may or may not run this hook. @end defvar @defvar after-revert-hook -This normal hook is run by @code{revert-buffer} after inserting -the modified contents---but only if @code{revert-buffer-function} is -@code{nil}. +This normal hook is run by the default @code{revert-buffer-function} +after inserting the modified contents. A custom @code{revert-buffer-function} +may or may not run this hook. @end defvar @c FIXME? Move this section from arevert-xtra to here? @defvar buffer-stale-function -The value of this variable, if non-@code{nil}, specifies a function -to call to check whether a non-file buffer needs reverting +The value of this variable specifies a function to call to check +whether a non-file buffer needs reverting @iftex (@pxref{Supporting additional buffers,,, emacs-xtra, Specialized Emacs Features}). @end iftex diff --git a/etc/NEWS b/etc/NEWS index ea62be87bfb..c3998934b5e 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -159,6 +159,7 @@ You can change the default by customizing `blink-cursor-blinks'. ** In keymaps where SPC scrolls forward, S-SPC now scrolls backward. This affects View mode, etc. ++++ ** The default value of `make-backup-file-name-function' is no longer nil. Instead it defaults to a function that does what the nil value used to. @@ -1400,6 +1401,7 @@ argument, with the same interpretation as the returned value of ** Revert and Autorevert changes +FIXME buffer-stale-function no longer just for non-file buffers? *** The default values of `buffer-stale-function', `revert-buffer-function', and `revert-buffer-insert-file-contents-function' are no longer nil. Instead they default to functions that do what the nil value used to. -- 2.39.2