@c This is part of the Emacs manual.
-@c Copyright (C) 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
+@c Copyright (C) 2004-2012 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
@c printed version) or in the main Emacs manual (for the on-line version).
@node Autorevert
-@section Auto Reverting non-file Buffers
+@section Auto Reverting Non-File Buffers
-Normally Global Auto Revert Mode 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} to @code{t}. The latter
-enables Auto Reverting for all types of buffers for which it is
-implemented, that is, for the types of buffers listed in the menu
-below.
+Global Auto Revert Mode normally only reverts file buffers. There are
+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
often does not try to detect all possible changes in the buffer, only
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
+all information in the buffer is up-to-date, and does not necessarily
make manual reverts useless.
-At the other extreme, certain buffers automatically auto-revert every
+At the other extreme, certain buffers automatically revert every
@code{auto-revert-interval} seconds. (This currently only applies to
the Buffer Menu.) In this case, Auto Revert does not print any
messages while reverting, even when @code{auto-revert-verbose} is
explained in the corresponding sections.
@menu
-* Auto Reverting the Buffer Menu::
-* Auto Reverting Dired::
-* Supporting additional buffers::
+* 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.
@end menu
@node Auto Reverting the Buffer Menu
systems.
Dired buffers only auto-revert when the file list of the buffer's main
-directory changes. They do not auto-revert when information about a
-particular file 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
+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.
+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
that modifying or saving files listed in the main directory actually
does cause auto-reverting. This is because making changes to a file,
-or saving it, very often causes changes in the directory itself, for
+or saving it, very often causes changes in the directory itself; for
instance, through backup files or auto-save files. However, this is
not guaranteed.
flags, mark the buffer non-modified using @kbd{M-~}. However, adding,
deleting or changing marks or flags will mark it modified again.
-Remote Dired buffers are not auto-reverted. 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.
+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. @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.
ignore the @var{noconfirm} argument.
If you just want to automatically auto-revert every
-@code{auto-revert-interval} seconds, use:
+@code{auto-revert-interval} seconds (like the Buffer Menu), use:
@example
(set (make-local-variable 'buffer-stale-function)
The buffer will only auto-revert if it is marked unmodified. Hence,
you will have to make sure that various functions mark the buffer
modified if and only if either the buffer contains information that
-might be lost by reverting or there is reason to believe that the user
+might be lost by reverting, or there is reason to believe that the user
might be inconvenienced by auto-reverting, because he is actively
working on the buffer. The user can always override this by manually
adjusting the modified status of the buffer. To support this, calling
inevitable if the buffer radically changes.
You should make sure that the @code{revert-buffer-function} does not
-print messages that unnecessarily duplicate Auto Revert's own messages
-if @code{auto-revert-verbose} is @code{t} and effectively override a
-@code{nil} value for @code{auto-revert-verbose}. Hence, adapting a
-mode for auto-reverting often involves getting rid of such messages.
-This is especially important for buffers that automatically
-auto-revert every @code{auto-revert-interval} seconds.
+print messages that unnecessarily duplicate Auto Revert's own messages,
+displayed if @code{auto-revert-verbose} is @code{t}, and effectively
+override a @code{nil} value for @code{auto-revert-verbose}. Hence,
+adapting a mode for auto-reverting often involves getting rid of such
+messages. This is especially important for buffers that automatically
+revert every @code{auto-revert-interval} seconds.
-Also, you may want to update the documentation string of
-@code{global-auto-revert-non-file-buffers}.
+If the new auto-reverting is part of Emacs, you should mention it
+in the documentation string of @code{global-auto-revert-non-file-buffers}.
@ifinfo
-Finally, you should add a node to this chapter's menu. This node
+Similarly, you should add a node to this chapter's menu. This node
@end ifinfo
@ifnotinfo
-Finally, you should add a section to this chapter. This section
+Similarly, you should add a section to this chapter. This section
@end ifnotinfo
should at the very least make clear whether enabling auto-reverting
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
HCoop / bpt / emacs.git / blobdiff