From d738ebdccfd2cdcac50f12d55a8c0c311edbc063 Mon Sep 17 00:00:00 2001 From: Glenn Morris Date: Thu, 3 Apr 2014 00:06:40 -0700 Subject: [PATCH] Doc updates related to changes in revert-buffer function variables * lisp/files.el (make-backup-file-name-function) (make-backup-file-name, make-backup-file-name--default-function) (make-backup-file-name-1, find-backup-file-name) (revert-buffer-function, revert-buffer-insert-file-contents-function) (buffer-stale--default-function, buffer-stale-function) (before-revert-hook, after-revert-hook, revert-buffer-in-progress-p) (revert-buffer, revert-buffer--default) (revert-buffer-insert-file-contents--default-function): Doc fixes related to defaults no longer being nil. (make-backup-file-name-function): Bump :version. Restore nil as a valid but deprecated custom type. * etc/NEWS: Related edit. --- etc/NEWS | 7 ++-- lisp/ChangeLog | 14 ++++++++ lisp/files.el | 96 ++++++++++++++++++++++++++++++++------------------ 3 files changed, 80 insertions(+), 37 deletions(-) diff --git a/etc/NEWS b/etc/NEWS index 81aebf09c37..32490aefd5c 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -1397,9 +1397,10 @@ argument, with the same interpretation as the returned value of ** Revert and Autorevert changes -*** The default value of `revert-buffer-function' is no longer nil. -Instead it defaults to a function that does what the nil value used to. -The same applies for `revert-buffer-insert-file-contents-function'. +*** The default values of `make-backup-file-name-function', +`revert-buffer-function', `revert-buffer-insert-file-contents-function', +and `buffer-stale-function' are no longer nil. Instead they default +to functions that do what the nil value used to. --- *** If Emacs is compiled with file notification support, it uses notifications diff --git a/lisp/ChangeLog b/lisp/ChangeLog index 5ea2d4483c4..ee7d61c7389 100644 --- a/lisp/ChangeLog +++ b/lisp/ChangeLog @@ -1,3 +1,17 @@ +2014-04-03 Glenn Morris + + * files.el (make-backup-file-name-function) + (make-backup-file-name, make-backup-file-name--default-function) + (make-backup-file-name-1, find-backup-file-name) + (revert-buffer-function, revert-buffer-insert-file-contents-function) + (buffer-stale--default-function, buffer-stale-function) + (before-revert-hook, after-revert-hook, revert-buffer-in-progress-p) + (revert-buffer, revert-buffer--default) + (revert-buffer-insert-file-contents--default-function): + Doc fixes related to defaults no longer being nil. + (make-backup-file-name-function): Bump :version. + Restore nil as a valid but deprecated custom type. + 2014-04-03 Stefan Monnier * progmodes/perl-mode.el (perl-syntax-propertize-function): Handle $' diff --git a/lisp/files.el b/lisp/files.el index 6d0be9234e6..d5c6028ff47 100644 --- a/lisp/files.el +++ b/lisp/files.el @@ -4215,15 +4215,22 @@ FILENAME defaults to `buffer-file-name'." (defcustom make-backup-file-name-function #'make-backup-file-name--default-function - "A function to use instead of the default `make-backup-file-name'. + "A function that `make-backup-file-name' uses to create backup file names. +The function receives a single argument, the original file name. -This could be buffer-local to do something special for specific -files. If you define it, you may need to change `backup-file-name-p' -and `file-name-sans-versions' too. +If you change this, you may need to change `backup-file-name-p' and +`file-name-sans-versions' too. + +You could make this buffer-local to do something special for specific files. + +For historical reasons, a value of nil means to use the default function. +This should not be relied upon. See also `backup-directory-alist'." + :version "24.4" ; nil -> make-backup-file-name--default-function :group 'backup - :type '(function :tag "Your function")) + :type '(choice (const :tag "Deprecated way to get the default function" nil) + (function :tag "Function"))) (defcustom backup-directory-alist nil "Alist of filename patterns and backup directory names. @@ -4280,20 +4287,17 @@ Checks for files in `temporary-file-directory', (defun make-backup-file-name (file) "Create the non-numeric backup file name for FILE. -Normally this will just be the file's name with `~' appended. -Customization hooks are provided as follows. - -The value of `make-backup-file-name-function' should be a function which -will be called with FILE as its argument; the resulting name is used. - -By default, a match for FILE is sought in `backup-directory-alist'; see -the documentation of that variable. If the directory for the backup -doesn't exist, it is created." +This calls the function that `make-backup-file-name-function' specifies, +with a single argument FILE." (funcall (or make-backup-file-name-function #'make-backup-file-name--default-function) file)) (defun make-backup-file-name--default-function (file) + "Default function for `make-backup-file-name'. +Normally this just returns FILE's name with `~' appended. +It searches for a match for FILE in `backup-directory-alist'. +If the directory for the backup doesn't exist, it is created." (if (and (eq system-type 'ms-dos) (not (msdos-long-file-names))) (let ((fn (file-name-nondirectory file))) @@ -4305,7 +4309,8 @@ doesn't exist, it is created." (concat (make-backup-file-name-1 file) "~"))) (defun make-backup-file-name-1 (file) - "Subroutine of `make-backup-file-name' and `find-backup-file-name'." + "Subroutine of `make-backup-file-name--default-function'. +The function `find-backup-file-name' also uses this." (let ((alist backup-directory-alist) elt backup-directory abs-backup-directory) (while alist @@ -4382,8 +4387,8 @@ the index in the name where the version number begins." Value is a list whose car is the name for the backup file and whose cdr is a list of old versions to consider deleting now. If the value is nil, don't make a backup. -Uses `backup-directory-alist' in the same way as does -`make-backup-file-name'." +Uses `backup-directory-alist' in the same way as +`make-backup-file-name--default-function' does." (let ((handler (find-file-name-handler fn 'find-backup-file-name))) ;; Run a handler for this function so that ange-ftp can refuse to do it. (if handler @@ -5319,22 +5324,32 @@ comparison." (put 'revert-buffer-function 'permanent-local t) (defvar revert-buffer-function #'revert-buffer--default - "Function to use to revert this buffer, or nil to do the default. + "Function to use to revert this buffer. The function receives two arguments IGNORE-AUTO and NOCONFIRM, which are the arguments that `revert-buffer' received. It also has access to the `preserve-modes' argument of `revert-buffer' -via the `revert-buffer-preserve-modes' dynamic variable.") +via the `revert-buffer-preserve-modes' dynamic variable. + +For historical reasons, a value of nil means to use the default function. +This should not be relied upon.") (put 'revert-buffer-insert-file-contents-function 'permanent-local t) (defvar revert-buffer-insert-file-contents-function #'revert-buffer-insert-file-contents--default-function "Function to use to insert contents when reverting this buffer. -Gets two args, first the nominal file name to use, -and second, t if reading the auto-save file. +The function receives two arguments: the first the nominal file name to use; +the second is t if reading the auto-save file. -The function you specify is responsible for updating (or preserving) point.") +The function is responsible for updating (or preserving) point. + +For historical reasons, a value of nil means to use the default function. +This should not be relied upon.") (defun buffer-stale--default-function (&optional _noconfirm) + "Default function to use for `buffer-stale-function'. +This function ignores its argument. +This returns non-nil if the current buffer is visiting a readable file +whose modification time does not match that of the buffer." (and buffer-file-name (file-readable-p buffer-file-name) (not (verify-visited-file-modtime (current-buffer))))) @@ -5353,13 +5368,16 @@ non-nil if the buffer is going to be reverted without asking the user. In such situations, one has to be careful with potentially time consuming operations. +For historical reasons, a value of nil means to use the default function. +This should not be relied upon. + For more information on how this variable is used by Auto Revert mode, see Info node `(emacs)Supporting additional buffers'.") (defvar before-revert-hook nil "Normal hook for `revert-buffer' to run before reverting. -If `revert-buffer-function' is used to override the normal revert -mechanism, this hook is not used.") +The function `revert-buffer--default' runs this. +A customized `revert-buffer-function' need not run this hook.") (defvar after-revert-hook nil "Normal hook for `revert-buffer' to run after reverting. @@ -5367,12 +5385,11 @@ Note that the hook value that it runs is the value that was in effect before reverting; that makes a difference if you have buffer-local hook functions. -If `revert-buffer-function' is used to override the normal revert -mechanism, this hook is not used.") +The function `revert-buffer--default' runs this. +A customized `revert-buffer-function' need not run this hook.") (defvar revert-buffer-in-progress-p nil - "Non-nil if a `revert-buffer' operation is in progress, nil otherwise. -This is true even if a `revert-buffer-function' is being used.") + "Non-nil if a `revert-buffer' operation is in progress, nil otherwise.") (defvar revert-buffer-internal-hook) @@ -5409,12 +5426,10 @@ the files modes. Normally we reinitialize them using `normal-mode'. This function binds `revert-buffer-in-progress-p' non-nil while it operates. -If the value of `revert-buffer-function' is non-nil, it is called to -do all the work for this command. Otherwise, the hooks -`before-revert-hook' and `after-revert-hook' are run at the beginning -and the end, and if `revert-buffer-insert-file-contents-function' is -non-nil, it is called instead of rereading visited file contents." - +This function calls the function that `revert-buffer-function' specifies +to do the work, with arguments IGNORE-AUTO and NOCONFIRM. +The default function runs the hooks `before-revert-hook' and +`after-revert-hook'." ;; I admit it's odd to reverse the sense of the prefix argument, but ;; there is a lot of code out there which assumes that the first ;; argument should be t to avoid consulting the auto-save file, and @@ -5426,7 +5441,16 @@ non-nil, it is called instead of rereading visited file contents." (revert-buffer-preserve-modes preserve-modes)) (funcall (or revert-buffer-function #'revert-buffer--default) ignore-auto noconfirm))) + (defun revert-buffer--default (ignore-auto noconfirm) + "Default function for `revert-buffer'. +The arguments IGNORE-AUTO and NOCONFIRM are as described for `revert-buffer'. +Runs the hooks `before-revert-hook' and `after-revert-hook' at the +start and end. + +Calls `revert-buffer-insert-file-contents-function' to reread the +contents of the visited file, with two arguments: the first is the file +name, the second is non-nil if reading an auto-save file." (with-current-buffer (or (buffer-base-buffer (current-buffer)) (current-buffer)) (let* ((auto-save-p (and (not ignore-auto) @@ -5480,6 +5504,10 @@ non-nil, it is called instead of rereading visited file contents." t))))) (defun revert-buffer-insert-file-contents--default-function (file-name auto-save-p) + "Default function for `revert-buffer-insert-file-contents-function'. +The function `revert-buffer--default' calls this. +FILE-NAME is the name of the file. AUTO-SAVE-P is non-nil if this is +an auto-save file." (cond ((not (file-exists-p file-name)) (error (if buffer-file-number -- 2.39.2