annotate man/arevert-xtra.texi @ 82420:7aa89a06bbac

*** empty log message ***
author Jay Belanger <jay.p.belanger@gmail.com>
date Fri, 17 Aug 2007 03:57:06 +0000
parents 3d45362f1d38
children 02b9a9aa5b0c
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
70457
bdd0ac985d67 Add Copyright notices.
Eli Zaretskii <eliz@gnu.org>
parents: 70440
diff changeset
1 @c This is part of the Emacs manual.
75348
3d45362f1d38 Add 2007 to copyright years.
Glenn Morris <rgm@gnu.org>
parents: 70461
diff changeset
2 @c Copyright (C) 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
70457
bdd0ac985d67 Add Copyright notices.
Eli Zaretskii <eliz@gnu.org>
parents: 70440
diff changeset
3 @c See file emacs.texi for copying conditions.
bdd0ac985d67 Add Copyright notices.
Eli Zaretskii <eliz@gnu.org>
parents: 70440
diff changeset
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
a6e9a00b021b Add arch tagline
Miles Bader <miles@gnu.org>
parents: 70457
diff changeset
188
a6e9a00b021b Add arch tagline
Miles Bader <miles@gnu.org>
parents: 70457
diff changeset
189 @ignore
a6e9a00b021b Add arch tagline
Miles Bader <miles@gnu.org>
parents: 70457
diff changeset
190 arch-tag: 2983e613-a272-45f6-9593-3010ad7f865e
a6e9a00b021b Add arch tagline
Miles Bader <miles@gnu.org>
parents: 70457
diff changeset
191 @end ignore