annotate man/arevert-xtra.texi @ 70440:5e1c038e4afa

New file, a portion of emacs-xtra.texi.

@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).