code.delx.au - gnu-emacs/blob - man/arevert-xtra.texi

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