Mercurial > emacs
annotate man/arevert-xtra.texi @ 76353:b9f9cc15f5d7
** lennart.borgman@gmail.com, Feb 22: C-h k does not catch text properies keymaps
It actually does.
** Failure to build on Solaris. Did reverting Jan's change bring back the old bug?
No: the change was not completely reverted, only the part the caused
the new problem.
author | Chong Yidong <cyd@stupidchicken.com> |
---|---|
date | Mon, 05 Mar 2007 22:14:02 +0000 |
parents | 3d45362f1d38 |
children | 02b9a9aa5b0c |
rev | line source |
---|---|
70457 | 1 @c This is part of the Emacs manual. |
75348 | 2 @c Copyright (C) 2004, 2005, 2006, 2007 Free Software Foundation, Inc. |
70457 | 3 @c See file emacs.texi for copying conditions. |
4 @c | |
70440
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5 @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
|
6 @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
|
7 @node Autorevert |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8 @section Auto Reverting non-file Buffers |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9 |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10 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
|
11 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
|
12 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
|
13 @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
|
14 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
|
15 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
|
16 below. |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17 |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18 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
|
19 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
|
20 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
|
21 ``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
|
22 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
|
23 file buffers. |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
24 |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
25 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
|
26 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
|
27 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
|
28 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
|
29 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
|
30 make manual reverts useless. |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
31 |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
32 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
|
33 @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
|
34 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
|
35 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
|
36 non-@code{nil}. |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
37 |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
38 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
|
39 explained in the corresponding sections. |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
40 |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
41 @menu |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
42 * Auto Reverting the Buffer Menu:: |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
43 * Auto Reverting Dired:: |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
44 * Supporting additional buffers:: |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
45 @end menu |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
46 |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
47 @node Auto Reverting the Buffer Menu |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
48 @subsection Auto Reverting the Buffer Menu |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
49 |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
50 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
|
51 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
|
52 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
|
53 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
|
54 |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
55 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
|
56 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
|
57 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
|
58 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
|
59 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
|
60 automatically erasing the marks. |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
61 |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
62 @node Auto Reverting Dired |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
63 @subsection Auto Reverting Dired buffers |
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 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
|
66 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
|
67 systems. |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
68 |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
69 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
|
70 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
|
71 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
|
72 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
|
73 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
|
74 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
|
75 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
|
76 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
|
77 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
|
78 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
|
79 not guaranteed. |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
80 |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
81 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
|
82 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
|
83 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
|
84 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
|
85 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
|
86 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
|
87 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
|
88 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
|
89 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
|
90 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
|
91 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
|
92 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
|
93 |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
94 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
|
95 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
|
96 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
|
97 auto-revert either. |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
98 |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
99 @node Supporting additional buffers |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
100 @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
|
101 |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
102 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
|
103 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
|
104 |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
105 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
|
106 @code{revert-buffer-function}. @xref{Definition of |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
107 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
|
108 |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
109 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
|
110 |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
111 @defvar buffer-stale-function |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
112 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
|
113 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
|
114 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
|
115 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
|
116 function is called. |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
117 |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
118 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
|
119 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
|
120 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
|
121 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
|
122 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
|
123 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
|
124 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
|
125 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
|
126 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
|
127 ignore the @var{noconfirm} argument. |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
128 |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
129 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
|
130 @code{auto-revert-interval} seconds, use: |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
131 |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
132 @example |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
133 (set (make-local-variable 'buffer-stale-function) |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
134 #'(lambda (&optional noconfirm) 'fast)) |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
135 @end example |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
136 |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
137 @noindent |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
138 in the buffer's mode function. |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
139 |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
140 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
|
141 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
|
142 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
|
143 @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
|
144 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
|
145 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
|
146 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
|
147 auto-reverting. |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
148 @end defvar |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
149 |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
150 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
|
151 @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
|
152 |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
153 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
|
154 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
|
155 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
|
156 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
|
157 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
|
158 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
|
159 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
|
160 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
|
161 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
|
162 |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
163 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
|
164 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
|
165 inevitable if the buffer radically changes. |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
166 |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
167 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
|
168 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
|
169 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
|
170 @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
|
171 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
|
172 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
|
173 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
|
174 |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
175 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
|
176 @code{global-auto-revert-non-file-buffers}. |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
177 |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
178 @ifinfo |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
179 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
|
180 @end ifinfo |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
181 @ifnotinfo |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
182 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
|
183 @end ifnotinfo |
5e1c038e4afa
New file, a portion of emacs-xtra.texi.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
184 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
|
185 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
|
186 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
|
187 seconds). |
70461 | 188 |
189 @ignore | |
190 arch-tag: 2983e613-a272-45f6-9593-3010ad7f865e | |
191 @end ignore |