18.5.3 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 suitable
revert-buffer-function. See Reverting in the Emacs Lisp Reference Manual.

In addition, it must have a suitable buffer-stale-function.

Variable: buffer-stale-function

The value of this variable is a function to check whether a
buffer needs reverting. This should be a function with one optional
argument noconfirm. The function should return non-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 noconfirm
argument is that it should be t if the buffer is going to be
reverted without asking the user and 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, noconfirm is t.
If the function is only going to be used for auto-reverting, you can
ignore the noconfirm argument.

If you just want to automatically auto-revert every
auto-revert-interval seconds (like the Buffer Menu), use:

The special return value ‘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
auto-revert-verbose is non-nil. This is important, as
getting revert messages every 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.

Once the buffer has a suitable revert-buffer-function and
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 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 revert-buffer-function does not
print messages that unnecessarily duplicate Auto Revert’s own messages,
displayed if auto-revert-verbose is t, and effectively
override a nil value for 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 auto-revert-interval seconds.

If the new auto-reverting is part of Emacs, you should mention it
in the documentation string of global-auto-revert-non-file-buffers.

Similarly, you should add a section to this chapter. This section
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 auto-revert-interval
seconds).