Mercurial > emacs
comparison man/arevert-xtra.texi @ 70440:5e1c038e4afa
New file, a portion of emacs-xtra.texi.
author | Eli Zaretskii <eliz@gnu.org> |
---|---|
date | Sat, 06 May 2006 12:45:46 +0000 |
parents | |
children | bdd0ac985d67 |
comparison
equal
deleted
inserted
replaced
70439:48fec2b642c9 | 70440:5e1c038e4afa |
---|---|
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). |