Commit d738ebdc authored by Glenn Morris's avatar Glenn Morris

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.
parent 062e286b
......@@ -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
......
2014-04-03 Glenn Morris <rgm@gnu.org>
* 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 <monnier@iro.umontreal.ca>
* progmodes/perl-mode.el (perl-syntax-propertize-function): Handle $'
......
......@@ -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
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment