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