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