Commit | Line | Data |
---|---|---|
8cf51b2c GM |
1 | @c This is part of the Emacs manual. |
2 | @c Copyright (C) 2004, 2005, 2006, 2007 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 | |
9 | ||
10 | Normally Global Auto Revert Mode only reverts file buffers. There are | |
11 | two ways to auto-revert certain non-file buffers: enabling Auto Revert | |
12 | Mode in those buffers (using @kbd{M-x auto-revert-mode}) and setting | |
13 | @code{global-auto-revert-non-file-buffers} to @code{t}. The latter | |
14 | enables Auto Reverting for all types of buffers for which it is | |
15 | implemented, that is, for the types of buffers listed in the menu | |
16 | 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 auto-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:: | |
43 | * Auto Reverting Dired:: | |
44 | * Supporting additional buffers:: | |
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. They do not auto-revert when information about a | |
71 | particular file changes or when inserted subdirectories change. To be | |
72 | sure that @emph{all} listed information is up to date, you have to | |
73 | 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. | |
80 | ||
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. | |
93 | ||
94 | Remote Dired buffers are not auto-reverted. Neither are Dired buffers | |
95 | for which you used shell wildcards or file arguments to list only some | |
96 | of the files. @samp{*Find*} and @samp{*Locate*} buffers do not | |
97 | auto-revert either. | |
98 | ||
99 | @node Supporting additional buffers | |
100 | @subsection Adding Support for Auto-Reverting additional Buffers. | |
101 | ||
102 | This section is intended for Elisp programmers who would like to add | |
103 | support for auto-reverting new types of buffers. | |
104 | ||
105 | To support auto-reverting the buffer must first of all have a | |
106 | @code{revert-buffer-function}. @xref{Definition of | |
107 | revert-buffer-function,, Reverting, elisp, the Emacs Lisp Reference Manual}. | |
108 | ||
109 | In addition, it @emph{must} have a @code{buffer-stale-function}. | |
110 | ||
111 | @defvar buffer-stale-function | |
112 | The value of this variable is a function to check whether a non-file | |
113 | buffer needs reverting. This should be a function with one optional | |
114 | argument @var{noconfirm}. The function should return non-@code{nil} | |
115 | if the buffer should be reverted. The buffer is current when this | |
116 | function is called. | |
117 | ||
118 | While this function is mainly intended for use in auto-reverting, it | |
119 | could be used for other purposes as well. For instance, if | |
120 | auto-reverting is not enabled, it could be used to warn the user that | |
121 | the buffer needs reverting. The idea behind the @var{noconfirm} | |
122 | argument is that it should be @code{t} if the buffer is going to be | |
123 | reverted without asking the user and @code{nil} if the function is | |
124 | just going to be used to warn the user that the buffer is out of date. | |
125 | In particular, for use in auto-reverting, @var{noconfirm} is @code{t}. | |
126 | If the function is only going to be used for auto-reverting, you can | |
127 | ignore the @var{noconfirm} argument. | |
128 | ||
129 | If you just want to automatically auto-revert every | |
130 | @code{auto-revert-interval} seconds, use: | |
131 | ||
132 | @example | |
133 | (set (make-local-variable 'buffer-stale-function) | |
134 | #'(lambda (&optional noconfirm) 'fast)) | |
135 | @end example | |
136 | ||
137 | @noindent | |
138 | in the buffer's mode function. | |
139 | ||
140 | The special return value @samp{fast} tells the caller that the need | |
141 | for reverting was not checked, but that reverting the buffer is fast. | |
142 | It also tells Auto Revert not to print any revert messages, even if | |
143 | @code{auto-revert-verbose} is non-@code{nil}. This is important, as | |
144 | getting revert messages every @code{auto-revert-interval} seconds can | |
145 | be very annoying. The information provided by this return value could | |
146 | also be useful if the function is consulted for purposes other than | |
147 | auto-reverting. | |
148 | @end defvar | |
149 | ||
150 | Once the buffer has a @code{revert-buffer-function} and a | |
151 | @code{buffer-stale-function}, several problems usually remain. | |
152 | ||
153 | The buffer will only auto-revert if it is marked unmodified. Hence, | |
154 | you will have to make sure that various functions mark the buffer | |
155 | modified if and only if either the buffer contains information that | |
156 | might be lost by reverting or there is reason to believe that the user | |
157 | might be inconvenienced by auto-reverting, because he is actively | |
158 | working on the buffer. The user can always override this by manually | |
159 | adjusting the modified status of the buffer. To support this, calling | |
160 | the @code{revert-buffer-function} on a buffer that is marked | |
161 | unmodified should always keep the buffer marked unmodified. | |
162 | ||
163 | It is important to assure that point does not continuously jump around | |
164 | as a consequence of auto-reverting. Of course, moving point might be | |
165 | inevitable if the buffer radically changes. | |
166 | ||
167 | You should make sure that the @code{revert-buffer-function} does not | |
168 | print messages that unnecessarily duplicate Auto Revert's own messages | |
169 | if @code{auto-revert-verbose} is @code{t} and effectively override a | |
170 | @code{nil} value for @code{auto-revert-verbose}. Hence, adapting a | |
171 | mode for auto-reverting often involves getting rid of such messages. | |
172 | This is especially important for buffers that automatically | |
173 | auto-revert every @code{auto-revert-interval} seconds. | |
174 | ||
175 | Also, you may want to update the documentation string of | |
176 | @code{global-auto-revert-non-file-buffers}. | |
177 | ||
178 | @ifinfo | |
179 | Finally, you should add a node to this chapter's menu. This node | |
180 | @end ifinfo | |
181 | @ifnotinfo | |
182 | Finally, you should add a section to this chapter. This section | |
183 | @end ifnotinfo | |
184 | should at the very least make clear whether enabling auto-reverting | |
185 | for the buffer reliably assures that all information in the buffer is | |
186 | completely up to date (or will be after @code{auto-revert-interval} | |
187 | seconds). | |
188 | ||
189 | @ignore | |
190 | arch-tag: 2983e613-a272-45f6-9593-3010ad7f865e | |
191 | @end ignore |