@c This is part of the Emacs manual.
-@c Copyright (C) 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011
-@c Free Software Foundation, Inc.
+@c Copyright (C) 2004-2016 Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@c
@c This file is included either in emacs-xtra.texi (when producing the
@section Auto Reverting Non-File Buffers
Global Auto Revert Mode normally only reverts file buffers. There are
-two ways to auto-revert certain non-file buffers: enabling Auto Revert
-Mode in those buffers (using @kbd{M-x auto-revert-mode}); and setting
-@code{global-auto-revert-non-file-buffers} non-@code{nil}. The latter
-enables Auto Reverting for all types of buffers for which it is
-implemented (listed in the menu below).
+two ways to auto-revert certain non-file buffers: by enabling Auto
+Revert Mode in those buffers (using @kbd{M-x auto-revert-mode}); and
+by setting @code{global-auto-revert-non-file-buffers} to a
+non-@code{nil} value. The latter enables Auto Reverting for all types
+of buffers for which it is implemented (listed in the menu below).
Like file buffers, non-file buffers should normally not revert while
you are working on them, or while they contain information that might
get lost after reverting. Therefore, they do not revert if they are
-``modified''. This can get tricky, because deciding when a non-file
+modified. This can get tricky, because deciding when a non-file
buffer should be marked modified is usually more difficult than for
file buffers.
Another tricky detail is that, for efficiency reasons, Auto Revert
often does not try to detect all possible changes in the buffer, only
-changes that are ``major'' or easy to detect. Hence, enabling
+changes that are major or easy to detect. Hence, enabling
auto-reverting for a non-file buffer does not always guarantee that
all information in the buffer is up-to-date, and does not necessarily
make manual reverts useless.
@menu
* Auto Reverting the Buffer Menu:: Auto Revert of the Buffer Menu.
* Auto Reverting Dired:: Auto Revert of Dired buffers.
-* Supporting additional buffers:: How to add more Auto Revert support.
+* Supporting additional buffers:: How to add more Auto Revert support.
@end menu
@node Auto Reverting the Buffer Menu
@subsection Auto Reverting the Buffer Menu
If auto-reverting of non-file buffers is enabled, the Buffer Menu
-automatically reverts every @code{auto-revert-interval} seconds,
-whether there is a need for it or not. (It would probably take longer
-to check whether there is a need than to actually revert.)
+(@pxref{Several Buffers}) automatically reverts every
+@code{auto-revert-interval} seconds, whether there is a need for it or
+not. (It would probably take longer to check whether there is a need
+than to actually revert.)
If the Buffer Menu inappropriately gets marked modified, just revert
it manually using @kbd{g} and auto-reverting will resume. However, if
systems.
Dired buffers only auto-revert when the file list of the buffer's main
-directory changes (e.g. when a new file is added). They do not
+directory changes (e.g., when a new file is added). They do not
auto-revert when information about a particular file changes
-(e.g. when the size changes) or when inserted subdirectories change.
+(e.g., when the size changes) or when inserted subdirectories change.
To be sure that @emph{all} listed information is up to date, you have
to manually revert using @kbd{g}, @emph{even} if auto-reverting is
enabled in the Dired buffer. Sometimes, you might get the impression
Remote Dired buffers are not auto-reverted (because it may be slow).
Neither are Dired buffers for which you used shell wildcards or file
-arguments to list only some of the files. @samp{*Find*} and
-@samp{*Locate*} buffers do not auto-revert either.
+arguments to list only some of the files. @file{*Find*} and
+@file{*Locate*} buffers do not auto-revert either.
+@c FIXME? This should be in the elisp manual?
@node Supporting additional buffers
@subsection Adding Support for Auto-Reverting additional Buffers.
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 suitable @code{buffer-stale-function}.
+@c FIXME only defvar in all of doc/emacs!
@defvar buffer-stale-function
-The value of this variable is a function to check whether a non-file
+The value of this variable is a function to check whether a
buffer needs reverting. This should be a function with one optional
argument @var{noconfirm}. The function should return non-@code{nil}
if the buffer should be reverted. The buffer is current when this
@code{auto-revert-interval} seconds (like the Buffer Menu), use:
@example
-(set (make-local-variable 'buffer-stale-function)
+(setq-local buffer-stale-function
#'(lambda (&optional noconfirm) 'fast))
@end example
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,
for the buffer reliably assures that all information in the buffer is
completely up to date (or will be after @code{auto-revert-interval}
seconds).
-
-@ignore
- arch-tag: 2983e613-a272-45f6-9593-3010ad7f865e
-@end ignore