Mercurial > emacs

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/emacs/arevert-xtra.texi	Thu Sep 06 04:44:05 2007 +0000
@@ -0,0 +1,191 @@
+@c This is part of the Emacs manual.
+@c Copyright (C) 2004, 2005, 2006, 2007 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
+
+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.
+
+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
+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
+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.
+
+At the other extreme, certain buffers automatically auto-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
+non-@code{nil}.
+
+The details depend on the particular types of buffers and are
+explained in the corresponding sections.
+
+@menu
+* Auto Reverting the Buffer Menu::
+* Auto Reverting Dired::
+* Supporting additional buffers::
+@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.)
+
+If the Buffer Menu inappropriately gets marked modified, just revert
+it manually using @kbd{g} and auto-reverting will resume.  However, if
+you marked certain buffers to get deleted or to be displayed, you have
+to be careful, because reverting erases all marks.  The fact that
+adding marks sets the buffer's modified flag prevents Auto Revert from
+automatically erasing the marks.
+
+@node Auto Reverting Dired
+@subsection Auto Reverting Dired buffers
+
+Auto-reverting Dired buffers currently works on GNU or Unix style
+operating systems.  It may not work satisfactorily on some other
+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
+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
+instance, through backup files or auto-save files.  However, this is
+not guaranteed.
+
+If the Dired buffer is marked modified and there are no changes you
+want to protect, then most of the time you can make auto-reverting
+resume by manually reverting the buffer using @kbd{g}.  There is one
+exception.  If you flag or mark files, you can safely revert the
+buffer.  This will not erase the flags or marks (unless the marked
+file has been deleted, of course).  However, the buffer will stay
+modified, even after reverting, and auto-reverting will not resume.
+This is because, if you flag or mark files, you may be working on the
+buffer and you might not want the buffer to change without warning.
+If you want auto-reverting to resume in the presence of marks and
+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.
+
+@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
+@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}.
+
+@defvar buffer-stale-function
+The value of this variable is a function to check whether a non-file
+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
+function is called.
+
+While this function is mainly intended for use in auto-reverting, it
+could be used for other purposes as well.  For instance, if
+auto-reverting is not enabled, it could be used to warn the user that
+the buffer needs reverting.  The idea behind the @var{noconfirm}
+argument is that it should be @code{t} if the buffer is going to be
+reverted without asking the user and @code{nil} if the function is
+just going to be used to warn the user that the buffer is out of date.
+In particular, for use in auto-reverting, @var{noconfirm} is @code{t}.
+If the function is only going to be used for auto-reverting, you can
+ignore the @var{noconfirm} argument.
+
+If you just want to automatically auto-revert every
+@code{auto-revert-interval} seconds, use:
+
+@example
+(set (make-local-variable 'buffer-stale-function)
+     #'(lambda (&optional noconfirm) 'fast))
+@end example
+
+@noindent
+in the buffer's mode function.
+
+The special return value @samp{fast} tells the caller that the need
+for reverting was not checked, but that reverting the buffer is fast.
+It also tells Auto Revert not to print any revert messages, even if
+@code{auto-revert-verbose} is non-@code{nil}.  This is important, as
+getting revert messages every @code{auto-revert-interval} seconds can
+be very annoying.  The information provided by this return value could
+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
+@code{buffer-stale-function}, several problems usually remain.
+
+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 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
+the @code{revert-buffer-function} on a buffer that is marked
+unmodified should always keep the buffer marked unmodified.
+
+It is important to assure that point does not continuously jump around
+as a consequence of auto-reverting.  Of course, moving point might be
+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.
+
+Also, you may want to update 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
+@end ifinfo
+@ifnotinfo
+Finally, 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