Mercurial > emacs
annotate doc/emacs/arevert-xtra.texi @ 112419:a651b7492a78
* lisp/emacs-lisp/checkdoc.el (checkdoc-this-string-valid-engine):
Assume foo(bar) is a manpage reference rather than some unquoted symbol.
author | Stefan Monnier <monnier@iro.umontreal.ca> |
---|---|
date | Fri, 21 Jan 2011 13:12:32 -0500 |
parents | 376148b31b5e |
children | ef719132ddfa |
rev | line source |
---|---|
84222 | 1 @c This is part of the Emacs manual. |
112218
376148b31b5e
Add 2011 to FSF/AIST copyright years.
Glenn Morris <rgm@gnu.org>
parents:
106815
diff
changeset
|
2 @c Copyright (C) 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 |
103607 | 3 @c Free Software Foundation, Inc. |
84222 | 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 | |
103848
e7c52afb2b96
(Autorevert): Add menu descriptions.
Glenn Morris <rgm@gnu.org>
parents:
103607
diff
changeset
|
9 @section Auto Reverting Non-File Buffers |
84222 | 10 |
103607 | 11 Global Auto Revert Mode normally only reverts file buffers. There are |
84222 | 12 two ways to auto-revert certain non-file buffers: enabling Auto Revert |
103607 | 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 | |
84222 | 15 enables Auto Reverting for all types of buffers for which it is |
103607 | 16 implemented (listed in the menu below). |
84222 | 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 | |
103607 | 29 all information in the buffer is up-to-date, and does not necessarily |
84222 | 30 make manual reverts useless. |
31 | |
103607 | 32 At the other extreme, certain buffers automatically revert every |
84222 | 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 | |
103848
e7c52afb2b96
(Autorevert): Add menu descriptions.
Glenn Morris <rgm@gnu.org>
parents:
103607
diff
changeset
|
42 * Auto Reverting the Buffer Menu:: Auto Revert of the Buffer Menu. |
e7c52afb2b96
(Autorevert): Add menu descriptions.
Glenn Morris <rgm@gnu.org>
parents:
103607
diff
changeset
|
43 * Auto Reverting Dired:: Auto Revert of Dired buffers. |
e7c52afb2b96
(Autorevert): Add menu descriptions.
Glenn Morris <rgm@gnu.org>
parents:
103607
diff
changeset
|
44 * Supporting additional buffers:: How to add more Auto Revert support. |
84222 | 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 | |
103607 | 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 | |
84222 | 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, | |
103607 | 78 or saving it, very often causes changes in the directory itself; for |
84222 | 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 | |
103607 | 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. | |
84222 | 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 | |
103607 | 131 @code{auto-revert-interval} seconds (like the Buffer Menu), use: |
84222 | 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 | |
103607 | 157 might be lost by reverting, or there is reason to believe that the user |
84222 | 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 | |
103607 | 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. | |
84222 | 175 |
103607 | 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}. | |
84222 | 178 |
179 @ifinfo | |
103607 | 180 Similarly, you should add a node to this chapter's menu. This node |
84222 | 181 @end ifinfo |
182 @ifnotinfo | |
103607 | 183 Similarly, you should add a section to this chapter. This section |
84222 | 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 |