doc/emacs/arevert-xtra.texi

   1 @c This is part of the Emacs manual.
   2 @c Copyright (C) 2004, 2005, 2006, 2007, 2008, 2009, 2010
   3 @c   Free Software Foundation, Inc.
   4 @c See file emacs.texi for copying conditions.
   5 @c
   6 @c This file is included either in emacs-xtra.texi (when producing the
   7 @c printed version) or in the main Emacs manual (for the on-line version).
   8 @node Autorevert
   9 @section Auto Reverting Non-File Buffers
  10
  11 Global Auto Revert Mode normally only reverts file buffers.  There are
  12 two ways to auto-revert certain non-file buffers: enabling Auto Revert
  13 Mode in those buffers (using @kbd{M-x auto-revert-mode}); and setting
  14 @code{global-auto-revert-non-file-buffers} non-@code{nil}.  The latter
  15 enables Auto Reverting for all types of buffers for which it is
  16 implemented (listed in the menu below).
  17
  18 Like file buffers, non-file buffers should normally not revert while
  19 you are working on them, or while they contain information that might
  20 get lost after reverting.  Therefore, they do not revert if they are
  21 ``modified''.  This can get tricky, because deciding when a non-file
  22 buffer should be marked modified is usually more difficult than for
  23 file buffers.
  24
  25 Another tricky detail is that, for efficiency reasons, Auto Revert
  26 often does not try to detect all possible changes in the buffer, only
  27 changes that are ``major'' or easy to detect.  Hence, enabling
  28 auto-reverting for a non-file buffer does not always guarantee that
  29 all information in the buffer is up-to-date, and does not necessarily
  30 make manual reverts useless.
  31
  32 At the other extreme, certain buffers automatically revert every
  33 @code{auto-revert-interval} seconds.  (This currently only applies to
  34 the Buffer Menu.)  In this case, Auto Revert does not print any
  35 messages while reverting, even when @code{auto-revert-verbose} is
  36 non-@code{nil}.
  37
  38 The details depend on the particular types of buffers and are
  39 explained in the corresponding sections.
  40
  41 @menu
  42 * Auto Reverting the Buffer Menu:: Auto Revert of the Buffer Menu.
  43 * Auto Reverting Dired::           Auto Revert of Dired buffers.
  44 * Supporting additional buffers::  How to add more Auto Revert support.
  45 @end menu
  46
  47 @node Auto Reverting the Buffer Menu
  48 @subsection Auto Reverting the Buffer Menu
  49
  50 If auto-reverting of non-file buffers is enabled, the Buffer Menu
  51 automatically reverts every @code{auto-revert-interval} seconds,
  52 whether there is a need for it or not.  (It would probably take longer
  53 to check whether there is a need than to actually revert.)
  54
  55 If the Buffer Menu inappropriately gets marked modified, just revert
  56 it manually using @kbd{g} and auto-reverting will resume.  However, if
  57 you marked certain buffers to get deleted or to be displayed, you have
  58 to be careful, because reverting erases all marks.  The fact that
  59 adding marks sets the buffer's modified flag prevents Auto Revert from
  60 automatically erasing the marks.
  61
  62 @node Auto Reverting Dired
  63 @subsection Auto Reverting Dired buffers
  64
  65 Auto-reverting Dired buffers currently works on GNU or Unix style
  66 operating systems.  It may not work satisfactorily on some other
  67 systems.
  68
  69 Dired buffers only auto-revert when the file list of the buffer's main
  70 directory changes (e.g. when a new file is added).  They do not
  71 auto-revert when information about a particular file changes
  72 (e.g. when the size changes) or when inserted subdirectories change.
  73 To be sure that @emph{all} listed information is up to date, you have
  74 to manually revert using @kbd{g}, @emph{even} if auto-reverting is
  75 enabled in the Dired buffer.  Sometimes, you might get the impression
  76 that modifying or saving files listed in the main directory actually
  77 does cause auto-reverting.  This is because making changes to a file,
  78 or saving it, very often causes changes in the directory itself; for
  79 instance, through backup files or auto-save files.  However, this is
  80 not guaranteed.
  81
  82 If the Dired buffer is marked modified and there are no changes you
  83 want to protect, then most of the time you can make auto-reverting
  84 resume by manually reverting the buffer using @kbd{g}.  There is one
  85 exception.  If you flag or mark files, you can safely revert the
  86 buffer.  This will not erase the flags or marks (unless the marked
  87 file has been deleted, of course).  However, the buffer will stay
  88 modified, even after reverting, and auto-reverting will not resume.
  89 This is because, if you flag or mark files, you may be working on the
  90 buffer and you might not want the buffer to change without warning.
  91 If you want auto-reverting to resume in the presence of marks and
  92 flags, mark the buffer non-modified using @kbd{M-~}.  However, adding,
  93 deleting or changing marks or flags will mark it modified again.
  94
  95 Remote Dired buffers are not auto-reverted (because it may be slow).
  96 Neither are Dired buffers for which you used shell wildcards or file
  97 arguments to list only some of the files.  @samp{*Find*} and
  98 @samp{*Locate*} buffers do not auto-revert either.
  99
 100 @node Supporting additional buffers
 101 @subsection Adding Support for Auto-Reverting additional Buffers.
 102
 103 This section is intended for Elisp programmers who would like to add
 104 support for auto-reverting new types of buffers.
 105
 106 To support auto-reverting the buffer must first of all have a
 107 @code{revert-buffer-function}.  @xref{Definition of
 108 revert-buffer-function,, Reverting, elisp, the Emacs Lisp Reference Manual}.
 109
 110 In addition, it @emph{must} have a @code{buffer-stale-function}.
 111
 112 @defvar buffer-stale-function
 113 The value of this variable is a function to check whether a non-file
 114 buffer needs reverting.  This should be a function with one optional
 115 argument @var{noconfirm}.  The function should return non-@code{nil}
 116 if the buffer should be reverted.  The buffer is current when this
 117 function is called.
 118
 119 While this function is mainly intended for use in auto-reverting, it
 120 could be used for other purposes as well.  For instance, if
 121 auto-reverting is not enabled, it could be used to warn the user that
 122 the buffer needs reverting.  The idea behind the @var{noconfirm}
 123 argument is that it should be @code{t} if the buffer is going to be
 124 reverted without asking the user and @code{nil} if the function is
 125 just going to be used to warn the user that the buffer is out of date.
 126 In particular, for use in auto-reverting, @var{noconfirm} is @code{t}.
 127 If the function is only going to be used for auto-reverting, you can
 128 ignore the @var{noconfirm} argument.
 129
 130 If you just want to automatically auto-revert every
 131 @code{auto-revert-interval} seconds (like the Buffer Menu), use:
 132
 133 @example
 134 (set (make-local-variable 'buffer-stale-function)
 135      #'(lambda (&optional noconfirm) 'fast))
 136 @end example
 137
 138 @noindent
 139 in the buffer's mode function.
 140
 141 The special return value @samp{fast} tells the caller that the need
 142 for reverting was not checked, but that reverting the buffer is fast.
 143 It also tells Auto Revert not to print any revert messages, even if
 144 @code{auto-revert-verbose} is non-@code{nil}.  This is important, as
 145 getting revert messages every @code{auto-revert-interval} seconds can
 146 be very annoying.  The information provided by this return value could
 147 also be useful if the function is consulted for purposes other than
 148 auto-reverting.
 149 @end defvar
 150
 151 Once the buffer has a @code{revert-buffer-function} and a
 152 @code{buffer-stale-function}, several problems usually remain.
 153
 154 The buffer will only auto-revert if it is marked unmodified.  Hence,
 155 you will have to make sure that various functions mark the buffer
 156 modified if and only if either the buffer contains information that
 157 might be lost by reverting, or there is reason to believe that the user
 158 might be inconvenienced by auto-reverting, because he is actively
 159 working on the buffer.  The user can always override this by manually
 160 adjusting the modified status of the buffer.  To support this, calling
 161 the @code{revert-buffer-function} on a buffer that is marked
 162 unmodified should always keep the buffer marked unmodified.
 163
 164 It is important to assure that point does not continuously jump around
 165 as a consequence of auto-reverting.  Of course, moving point might be
 166 inevitable if the buffer radically changes.
 167
 168 You should make sure that the @code{revert-buffer-function} does not
 169 print messages that unnecessarily duplicate Auto Revert's own messages,
 170 displayed if @code{auto-revert-verbose} is @code{t}, and effectively
 171 override a @code{nil} value for @code{auto-revert-verbose}.  Hence,
 172 adapting a mode for auto-reverting often involves getting rid of such
 173 messages.  This is especially important for buffers that automatically
 174 revert every @code{auto-revert-interval} seconds.
 175
 176 If the new auto-reverting is part of Emacs, you should mention it
 177 in the documentation string of @code{global-auto-revert-non-file-buffers}.
 178
 179 @ifinfo
 180 Similarly, you should add a node to this chapter's menu.  This node
 181 @end ifinfo
 182 @ifnotinfo
 183 Similarly, you should add a section to this chapter.  This section
 184 @end ifnotinfo
 185 should at the very least make clear whether enabling auto-reverting
 186 for the buffer reliably assures that all information in the buffer is
 187 completely up to date (or will be after @code{auto-revert-interval}
 188 seconds).
 189
 190 @ignore
 191    arch-tag: 2983e613-a272-45f6-9593-3010ad7f865e
 192 @end ignore