Mercurial > emacs
comparison man/emacs-xtra.texi @ 56119:23a626038a46
New file.
author | Luc Teirlinck <teirllm@auburn.edu> |
---|---|
date | Tue, 15 Jun 2004 20:55:24 +0000 |
parents | |
children | cf2e292bf084 |
comparison
equal
deleted
inserted
replaced
56118:6fbabfb26a3c | 56119:23a626038a46 |
---|---|
1 \input texinfo @c -*-texinfo-*- | |
2 @comment %**start of header | |
3 @setfilename ../info/emacs-xtra | |
4 @settitle Specialized Emacs Features | |
5 @syncodeindex fn cp | |
6 @syncodeindex vr cp | |
7 @syncodeindex ky cp | |
8 @comment %**end of header | |
9 | |
10 @copying | |
11 This file describes specialized features of Emacs. | |
12 | |
13 Copyright (C) 2004 | |
14 Free Software Foundation, Inc. | |
15 | |
16 @quotation | |
17 Permission is granted to copy, distribute and/or modify this document | |
18 under the terms of the GNU Free Documentation License, Version 1.1 or | |
19 any later version published by the Free Software Foundation; with no | |
20 Invariant Sections, with the Front-Cover texts being ``A GNU | |
21 Manual'', and with the Back-Cover Texts as in (a) below. A copy of the | |
22 license is included in the section entitled ``GNU Free Documentation | |
23 License'' in the Emacs manual. | |
24 | |
25 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify | |
26 this GNU Manual, like GNU software. Copies published by the Free | |
27 Software Foundation raise funds for GNU development.'' | |
28 | |
29 This document is part of a collection distributed under the GNU Free | |
30 Documentation License. If you want to distribute this document | |
31 separately from the collection, you can do so by adding a copy of the | |
32 license to the document, as described in section 6 of the license. | |
33 @end quotation | |
34 @end copying | |
35 | |
36 @dircategory Emacs | |
37 @direntry | |
38 * Emacs-Xtra: (emacs-xtra). Specialized Emacs features. | |
39 @end direntry | |
40 | |
41 @titlepage | |
42 @title Specialized Emacs Features | |
43 @page | |
44 @vskip 0pt plus 1filll | |
45 @insertcopying | |
46 @end titlepage | |
47 | |
48 @contents | |
49 | |
50 @ifnottex | |
51 @node Top | |
52 @top Specialized Emacs Features | |
53 | |
54 @insertcopying | |
55 | |
56 @end ifnottex | |
57 | |
58 @menu | |
59 * Introduction:: What documentation belongs here? | |
60 * Autorevert:: Auto Reverting non-file buffers. | |
61 * Subdir switches:: Subdirectory switches in Dired. | |
62 * Index:: | |
63 @end menu | |
64 | |
65 @node Introduction | |
66 @unnumbered Introduction | |
67 | |
68 This manual contains detailed information about various features that | |
69 are too specialized to be included in the Emacs manual. It is | |
70 intended to be readable by anyone having a basic knowledge of Emacs. | |
71 However, certain sections may be intended for a more specialized | |
72 audience, such as Elisp authors. This should be clearly pointed out | |
73 at the beginning of these sections. | |
74 | |
75 This manual is intended as a complement, rather than an alternative, | |
76 to other ways to gain a more detailed knowledge of Emacs than the | |
77 Emacs manual can provide, such as browsing packages using @kbd{C-h p}, | |
78 accessing mode documentation using @kbd{C-h m} and browsing user | |
79 options using Custom. Also, certain packages, or collections of | |
80 related features, have their own manuals. The present manual is | |
81 mainly intended to be a collection of smaller specialized features, | |
82 too small to get their own manual. | |
83 | |
84 Sections intended specifically for Elisp programmers can follow the | |
85 style of the Elisp manual. Other sections should follow the style of | |
86 the Emacs manual. | |
87 | |
88 @node Autorevert | |
89 @chapter Auto Reverting non-file Buffers | |
90 | |
91 Normally Global Auto Revert Mode only reverts file buffers. There are | |
92 two ways to auto-revert certain non-file buffers: enabling Auto Revert | |
93 Mode in those buffers (using @kbd{M-x auto-revert-mode}) and setting | |
94 @code{global-auto-revert-non-file-buffers} to @code{t}. The latter | |
95 enables Auto Reverting for all types of buffers for which it is | |
96 implemented, that is, for the types of buffers listed in the menu | |
97 below. | |
98 | |
99 Like file buffers, non-file buffers should normally not revert while | |
100 you are working on them, or while they contain information that might | |
101 get lost after reverting. Therefore, they do not revert if they are | |
102 ``modified''. This can get tricky, because deciding when a non-file | |
103 buffer should be marked modified is usually more difficult than for | |
104 file buffers. | |
105 | |
106 Another tricky detail is that, for efficiency reasons, Auto Revert | |
107 often does not try to detect all possible changes in the buffer, only | |
108 changes that are ``major'' or easy to detect. Hence, enabling | |
109 auto-reverting for a non-file buffer does not always guarantee that | |
110 all information in the buffer is up to date and does not necessarily | |
111 make manual reverts useless. | |
112 | |
113 The details depend on the particular types of buffers and are | |
114 explained in the corresponding sections. | |
115 | |
116 @menu | |
117 * Auto Reverting the Buffer Menu:: | |
118 * Auto Reverting Dired:: | |
119 * Supporting additional buffers:: | |
120 @end menu | |
121 | |
122 @node Auto Reverting the Buffer Menu | |
123 @section Auto Reverting the Buffer Menu | |
124 | |
125 If auto-reverting of non-file buffers is enabled, the Buffer Menu | |
126 automatically reverts every @code{auto-revert-interval} seconds, | |
127 whether there is a need for it or not. (It would probably take longer | |
128 to check whether there is a need than to actually revert.) | |
129 | |
130 If the Buffer Menu inappropriately gets marked modified, just revert | |
131 it manually using @kbd{g} and auto-reverting will resume. However, if | |
132 you marked certain buffers to get deleted or to be displayed, you have | |
133 to be careful, because reverting erases all marks. The fact that | |
134 adding marks sets the buffer's modified flag prevents Auto Revert from | |
135 automatically erasing the marks. | |
136 | |
137 @node Auto Reverting Dired | |
138 @section Auto Reverting Dired buffers | |
139 | |
140 Auto-reverting Dired buffers currently only works satisfactorily on | |
141 GNU/Linux and Unix style operating systems. | |
142 | |
143 Dired buffers only auto-revert when the file list of the buffer's main | |
144 directory changes. They do not auto-revert when information about a | |
145 particular file changes or when inserted subdirectories change. To be | |
146 sure that @emph{all} listed information is up to date, you have to | |
147 manually revert using @kbd{g}, @emph{even} if auto-reverting is | |
148 enabled in the Dired buffer. Sometimes, you might get the impression | |
149 that modifying or saving files listed in the main directory actually | |
150 does cause auto-reverting. This is because making changes to a file, | |
151 or saving it, very often causes changes in the directory itself, for | |
152 instance, through backup files or auto-save files. However, this is | |
153 not guaranteed. | |
154 | |
155 If the Dired buffer is marked modified and there are no changes you | |
156 want to protect, then most of the time you can make auto-reverting | |
157 resume by manually reverting the buffer using @kbd{g}. There is one | |
158 exception. If you flag or mark files, then, unlike for the Buffer | |
159 Menu, you can safely revert the buffer. This will not erase the flags | |
160 or marks (unless the marked file has been deleted, of course). | |
161 However, the buffer will stay modified, even after reverting, and | |
162 auto-reverting will not resume. This is because, if you flag or mark | |
163 files, you may be working on the buffer and you might not want the | |
164 buffer to change without warning. If you want auto-reverting to | |
165 resume in the presence of marks and flags, mark the buffer | |
166 non-modified using @kbd{M-~}. However, adding, deleting or changing | |
167 marks or flags will mark it modified again. | |
168 | |
169 Remote Dired buffers are not auto-reverted. Neither are Dired buffers | |
170 for which you used shell wildcards or file arguments to list only some | |
171 of the files. @samp{*Find*} and @samp{*Locate*} buffers do not | |
172 auto-revert either. | |
173 | |
174 @node Supporting additional buffers | |
175 @section Adding Support for Auto-Reverting additional Buffers. | |
176 | |
177 This section is intended for Elisp programmers who would like to add | |
178 support for auto-reverting new types of buffers. | |
179 | |
180 To support auto-reverting the buffer must first of all have a | |
181 @code{revert-buffer-function}. @xref{Definition of | |
182 revert-buffer-function,, Reverting, elisp, the Emacs Lisp Reference Manual}. | |
183 | |
184 In addition, it @emph{must} have a @code{buffer-stale-function}. | |
185 | |
186 @defvar buffer-stale-function | |
187 The value of this variable is a function to check whether a non-file | |
188 buffer needs reverting. This should be a function with one optional | |
189 argument @var{noconfirm}. The function should return non-@code{nil} | |
190 if the buffer should be reverted. The buffer is current when this | |
191 function is called. | |
192 | |
193 While this function is mainly intended for use in auto-reverting, it | |
194 could be used for other purposes as well. For instance, if | |
195 auto-reverting is not enabled, it could be used to warn the user that | |
196 the buffer needs reverting. The idea behind the @var{noconfirm} | |
197 argument is that it should be @code{t} if the buffer is going to be | |
198 reverted without asking the user and @code{nil} if the function is | |
199 just going to be used to warn the user that the buffer is out of date. | |
200 In particular, for use in auto-reverting, @var{noconfirm} is @code{t}. | |
201 If the function is only going to be used for auto-reverting, you can | |
202 ignore the @var{noconfirm} argument. | |
203 | |
204 If you just want to automatically auto-revert every | |
205 @code{auto-revert-interval} seconds, use: | |
206 | |
207 @example | |
208 (set (make-local-variable 'buffer-stale-function) | |
209 #'(lambda (&optional noconfirm) 'fast)) | |
210 @end example | |
211 | |
212 @noindent | |
213 in the buffer's mode function. | |
214 | |
215 The special return value @samp{fast} tells the caller that the need for | |
216 reverting was not checked, but that reverting the buffer is fast. | |
217 This information could be useful if the function is consulted for | |
218 purposes other than auto-reverting. | |
219 @end defvar | |
220 | |
221 Once the buffer has a @code{revert-buffer-function} and a | |
222 @code{buffer-stale-function}, several problems usually remain. | |
223 | |
224 The buffer will only auto-revert if it is marked unmodified. Hence, | |
225 you will have to make sure that various functions mark the buffer | |
226 modified if and only if either the buffer contains information that | |
227 might be lost by reverting or there is reason to believe that the user | |
228 might be inconvenienced by auto-reverting, because he is actively | |
229 working on the buffer. The user can always override this by manually | |
230 adjusting the modified status of the buffer. To support this, calling | |
231 the @code{revert-buffer-function} on a buffer that is marked | |
232 unmodified should always keep the buffer marked unmodified. | |
233 | |
234 It is important to assure that point does not continuously jump around | |
235 as a consequence of auto-reverting. Of course, moving point might be | |
236 inevitable if the buffer radically changes. | |
237 | |
238 You should make sure that the @code{revert-buffer-function} does not | |
239 print messages that unnecessarily duplicate Auto Revert's own messages | |
240 if @code{auto-revert-verbose} is @code{t} and effectively override a | |
241 @code{nil} value for @code{auto-revert-verbose}. Hence, adapting a | |
242 mode for auto-reverting often involves getting rid of such messages. | |
243 | |
244 @ifinfo | |
245 Finally, you should add a node to this chapter's menu. This node | |
246 @end ifinfo | |
247 @ifnotinfo | |
248 Finally, you should add a section to this chapter. This section | |
249 @end ifnotinfo | |
250 should at the very least make clear whether enabling auto-reverting | |
251 for the buffer reliably assures that all information in the buffer is | |
252 completely up to date (or will be after @code{auto-revert-interval} | |
253 seconds). | |
254 | |
255 @node Subdir switches | |
256 @chapter Subdirectory Switches in Dired | |
257 | |
258 You can insert subdirectories with specified @code{ls} switches in | |
259 Dired buffers, using @kbd{C-u i}. You can change the @code{ls} | |
260 switches of an already inserted subdirectory using @kbd{C-u l}. | |
261 | |
262 In Emacs versions 21.4 and later, Dired remembers the switches, so | |
263 that reverting the buffer will not change them back to the main | |
264 directory's switches. Deleting a subdirectory forgets about its | |
265 switches. | |
266 | |
267 Using @code{dired-undo} (usually bound to @kbd{C-_} and @kbd{C-x u}) | |
268 to reinsert or delete subdirectories, that were inserted with explicit | |
269 switches, can bypass Dired's machinery for remembering (or forgetting) | |
270 switches. Deleting a subdirectory using @code{dired-undo} does not | |
271 forget its switches. When later reinserted using @kbd{i}, it will be | |
272 reinserted using its old switches. Using @code{dired-undo} to | |
273 reinsert a subdirectory that was deleted using the regular | |
274 Dired commands (not @code{dired-undo}) will originally insert it with | |
275 its old switches. However, reverting the buffer will relist it using | |
276 the buffer's default switches. If any of this yields problems, you | |
277 can easily correct the situation using @kbd{C-u i} or @kbd{C-u l}. | |
278 | |
279 The buffer's default switches do not affect subdirectories that were | |
280 inserted using explicitly specified switches. In particular, | |
281 commands such as @kbd{s}, that change the buffer's switches do not | |
282 affect such subdirectories. (They do affect subdirectories without | |
283 explicitly assigned switches, however.) | |
284 | |
285 You can make Dired forget about all subdirectory switches and relist | |
286 all subdirectories with the buffer's default switches using | |
287 @kbd{M-x dired-reset-subdir-switches}. This also reverts the Dired buffer. | |
288 | |
289 @node Index | |
290 @unnumbered Index | |
291 | |
292 @printindex cp | |
293 | |
294 @bye |