Mercurial > emacs
annotate man/emacs-xtra.texi @ 60039:d1e57e5b8403
(Hash Tables): Add desc to menu items.
(Creating Hash): Expain "full" means "make larger",
(Hash Access): Any object can be a key.
State value of maphash.
author | Richard M. Stallman <rms@gnu.org> |
---|---|
date | Mon, 14 Feb 2005 10:13:16 +0000 |
parents | aac0a33f5772 |
children | 7493ddb113fc |
rev | line source |
---|---|
56119 | 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 | |
56160
6ad083598109
(Supporting additional buffers): Minor change.
Luc Teirlinck <teirllm@auburn.edu>
parents:
56149
diff
changeset
|
11 This manual describes specialized features of Emacs. |
56119 | 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 | |
56128
cf2e292bf084
(Autorevert, Supporting additional buffers): Explain special treatment
Luc Teirlinck <teirllm@auburn.edu>
parents:
56119
diff
changeset
|
113 At the other extreme, certain buffers automatically auto-revert every |
cf2e292bf084
(Autorevert, Supporting additional buffers): Explain special treatment
Luc Teirlinck <teirllm@auburn.edu>
parents:
56119
diff
changeset
|
114 @code{auto-revert-interval} seconds. (This currently only applies to |
cf2e292bf084
(Autorevert, Supporting additional buffers): Explain special treatment
Luc Teirlinck <teirllm@auburn.edu>
parents:
56119
diff
changeset
|
115 the Buffer Menu.) In this case, Auto Revert does not print any |
cf2e292bf084
(Autorevert, Supporting additional buffers): Explain special treatment
Luc Teirlinck <teirllm@auburn.edu>
parents:
56119
diff
changeset
|
116 messages while reverting, even when @code{auto-revert-verbose} is |
cf2e292bf084
(Autorevert, Supporting additional buffers): Explain special treatment
Luc Teirlinck <teirllm@auburn.edu>
parents:
56119
diff
changeset
|
117 non-@code{nil}. |
cf2e292bf084
(Autorevert, Supporting additional buffers): Explain special treatment
Luc Teirlinck <teirllm@auburn.edu>
parents:
56119
diff
changeset
|
118 |
56119 | 119 The details depend on the particular types of buffers and are |
120 explained in the corresponding sections. | |
121 | |
122 @menu | |
123 * Auto Reverting the Buffer Menu:: | |
124 * Auto Reverting Dired:: | |
125 * Supporting additional buffers:: | |
126 @end menu | |
127 | |
128 @node Auto Reverting the Buffer Menu | |
129 @section Auto Reverting the Buffer Menu | |
130 | |
131 If auto-reverting of non-file buffers is enabled, the Buffer Menu | |
132 automatically reverts every @code{auto-revert-interval} seconds, | |
133 whether there is a need for it or not. (It would probably take longer | |
134 to check whether there is a need than to actually revert.) | |
135 | |
136 If the Buffer Menu inappropriately gets marked modified, just revert | |
137 it manually using @kbd{g} and auto-reverting will resume. However, if | |
138 you marked certain buffers to get deleted or to be displayed, you have | |
139 to be careful, because reverting erases all marks. The fact that | |
140 adding marks sets the buffer's modified flag prevents Auto Revert from | |
141 automatically erasing the marks. | |
142 | |
143 @node Auto Reverting Dired | |
144 @section Auto Reverting Dired buffers | |
145 | |
56149
0e86f3e9a45d
(Auto Reverting Dired): Minor changes.
Luc Teirlinck <teirllm@auburn.edu>
parents:
56131
diff
changeset
|
146 Auto-reverting Dired buffers currently works on GNU or Unix style |
0e86f3e9a45d
(Auto Reverting Dired): Minor changes.
Luc Teirlinck <teirllm@auburn.edu>
parents:
56131
diff
changeset
|
147 operating systems. It may not work satisfactorily on some other |
0e86f3e9a45d
(Auto Reverting Dired): Minor changes.
Luc Teirlinck <teirllm@auburn.edu>
parents:
56131
diff
changeset
|
148 systems. |
56119 | 149 |
150 Dired buffers only auto-revert when the file list of the buffer's main | |
151 directory changes. They do not auto-revert when information about a | |
152 particular file changes or when inserted subdirectories change. To be | |
153 sure that @emph{all} listed information is up to date, you have to | |
154 manually revert using @kbd{g}, @emph{even} if auto-reverting is | |
155 enabled in the Dired buffer. Sometimes, you might get the impression | |
156 that modifying or saving files listed in the main directory actually | |
157 does cause auto-reverting. This is because making changes to a file, | |
158 or saving it, very often causes changes in the directory itself, for | |
159 instance, through backup files or auto-save files. However, this is | |
160 not guaranteed. | |
161 | |
162 If the Dired buffer is marked modified and there are no changes you | |
163 want to protect, then most of the time you can make auto-reverting | |
164 resume by manually reverting the buffer using @kbd{g}. There is one | |
56149
0e86f3e9a45d
(Auto Reverting Dired): Minor changes.
Luc Teirlinck <teirllm@auburn.edu>
parents:
56131
diff
changeset
|
165 exception. If you flag or mark files, you can safely revert the |
0e86f3e9a45d
(Auto Reverting Dired): Minor changes.
Luc Teirlinck <teirllm@auburn.edu>
parents:
56131
diff
changeset
|
166 buffer. This will not erase the flags or marks (unless the marked |
0e86f3e9a45d
(Auto Reverting Dired): Minor changes.
Luc Teirlinck <teirllm@auburn.edu>
parents:
56131
diff
changeset
|
167 file has been deleted, of course). However, the buffer will stay |
0e86f3e9a45d
(Auto Reverting Dired): Minor changes.
Luc Teirlinck <teirllm@auburn.edu>
parents:
56131
diff
changeset
|
168 modified, even after reverting, and auto-reverting will not resume. |
0e86f3e9a45d
(Auto Reverting Dired): Minor changes.
Luc Teirlinck <teirllm@auburn.edu>
parents:
56131
diff
changeset
|
169 This is because, if you flag or mark files, you may be working on the |
0e86f3e9a45d
(Auto Reverting Dired): Minor changes.
Luc Teirlinck <teirllm@auburn.edu>
parents:
56131
diff
changeset
|
170 buffer and you might not want the buffer to change without warning. |
0e86f3e9a45d
(Auto Reverting Dired): Minor changes.
Luc Teirlinck <teirllm@auburn.edu>
parents:
56131
diff
changeset
|
171 If you want auto-reverting to resume in the presence of marks and |
0e86f3e9a45d
(Auto Reverting Dired): Minor changes.
Luc Teirlinck <teirllm@auburn.edu>
parents:
56131
diff
changeset
|
172 flags, mark the buffer non-modified using @kbd{M-~}. However, adding, |
0e86f3e9a45d
(Auto Reverting Dired): Minor changes.
Luc Teirlinck <teirllm@auburn.edu>
parents:
56131
diff
changeset
|
173 deleting or changing marks or flags will mark it modified again. |
56119 | 174 |
175 Remote Dired buffers are not auto-reverted. Neither are Dired buffers | |
176 for which you used shell wildcards or file arguments to list only some | |
177 of the files. @samp{*Find*} and @samp{*Locate*} buffers do not | |
178 auto-revert either. | |
179 | |
180 @node Supporting additional buffers | |
181 @section Adding Support for Auto-Reverting additional Buffers. | |
182 | |
183 This section is intended for Elisp programmers who would like to add | |
184 support for auto-reverting new types of buffers. | |
185 | |
186 To support auto-reverting the buffer must first of all have a | |
187 @code{revert-buffer-function}. @xref{Definition of | |
188 revert-buffer-function,, Reverting, elisp, the Emacs Lisp Reference Manual}. | |
189 | |
190 In addition, it @emph{must} have a @code{buffer-stale-function}. | |
191 | |
192 @defvar buffer-stale-function | |
193 The value of this variable is a function to check whether a non-file | |
194 buffer needs reverting. This should be a function with one optional | |
195 argument @var{noconfirm}. The function should return non-@code{nil} | |
196 if the buffer should be reverted. The buffer is current when this | |
197 function is called. | |
198 | |
199 While this function is mainly intended for use in auto-reverting, it | |
200 could be used for other purposes as well. For instance, if | |
201 auto-reverting is not enabled, it could be used to warn the user that | |
202 the buffer needs reverting. The idea behind the @var{noconfirm} | |
203 argument is that it should be @code{t} if the buffer is going to be | |
204 reverted without asking the user and @code{nil} if the function is | |
205 just going to be used to warn the user that the buffer is out of date. | |
206 In particular, for use in auto-reverting, @var{noconfirm} is @code{t}. | |
207 If the function is only going to be used for auto-reverting, you can | |
208 ignore the @var{noconfirm} argument. | |
209 | |
210 If you just want to automatically auto-revert every | |
211 @code{auto-revert-interval} seconds, use: | |
212 | |
213 @example | |
214 (set (make-local-variable 'buffer-stale-function) | |
215 #'(lambda (&optional noconfirm) 'fast)) | |
216 @end example | |
217 | |
218 @noindent | |
219 in the buffer's mode function. | |
220 | |
56128
cf2e292bf084
(Autorevert, Supporting additional buffers): Explain special treatment
Luc Teirlinck <teirllm@auburn.edu>
parents:
56119
diff
changeset
|
221 The special return value @samp{fast} tells the caller that the need |
cf2e292bf084
(Autorevert, Supporting additional buffers): Explain special treatment
Luc Teirlinck <teirllm@auburn.edu>
parents:
56119
diff
changeset
|
222 for reverting was not checked, but that reverting the buffer is fast. |
cf2e292bf084
(Autorevert, Supporting additional buffers): Explain special treatment
Luc Teirlinck <teirllm@auburn.edu>
parents:
56119
diff
changeset
|
223 It also tells Auto Revert not to print any revert messages, even if |
cf2e292bf084
(Autorevert, Supporting additional buffers): Explain special treatment
Luc Teirlinck <teirllm@auburn.edu>
parents:
56119
diff
changeset
|
224 @code{auto-revert-verbose} is non-@code{nil}. This is important, as |
cf2e292bf084
(Autorevert, Supporting additional buffers): Explain special treatment
Luc Teirlinck <teirllm@auburn.edu>
parents:
56119
diff
changeset
|
225 getting revert messages every @code{auto-revert-interval} seconds can |
cf2e292bf084
(Autorevert, Supporting additional buffers): Explain special treatment
Luc Teirlinck <teirllm@auburn.edu>
parents:
56119
diff
changeset
|
226 be very annoying. The information provided by this return value could |
cf2e292bf084
(Autorevert, Supporting additional buffers): Explain special treatment
Luc Teirlinck <teirllm@auburn.edu>
parents:
56119
diff
changeset
|
227 also be useful if the function is consulted for purposes other than |
cf2e292bf084
(Autorevert, Supporting additional buffers): Explain special treatment
Luc Teirlinck <teirllm@auburn.edu>
parents:
56119
diff
changeset
|
228 auto-reverting. |
56119 | 229 @end defvar |
230 | |
231 Once the buffer has a @code{revert-buffer-function} and a | |
232 @code{buffer-stale-function}, several problems usually remain. | |
233 | |
234 The buffer will only auto-revert if it is marked unmodified. Hence, | |
235 you will have to make sure that various functions mark the buffer | |
236 modified if and only if either the buffer contains information that | |
237 might be lost by reverting or there is reason to believe that the user | |
238 might be inconvenienced by auto-reverting, because he is actively | |
239 working on the buffer. The user can always override this by manually | |
240 adjusting the modified status of the buffer. To support this, calling | |
241 the @code{revert-buffer-function} on a buffer that is marked | |
242 unmodified should always keep the buffer marked unmodified. | |
243 | |
244 It is important to assure that point does not continuously jump around | |
245 as a consequence of auto-reverting. Of course, moving point might be | |
246 inevitable if the buffer radically changes. | |
247 | |
248 You should make sure that the @code{revert-buffer-function} does not | |
249 print messages that unnecessarily duplicate Auto Revert's own messages | |
250 if @code{auto-revert-verbose} is @code{t} and effectively override a | |
251 @code{nil} value for @code{auto-revert-verbose}. Hence, adapting a | |
252 mode for auto-reverting often involves getting rid of such messages. | |
56128
cf2e292bf084
(Autorevert, Supporting additional buffers): Explain special treatment
Luc Teirlinck <teirllm@auburn.edu>
parents:
56119
diff
changeset
|
253 This is especially important for buffers that automatically |
cf2e292bf084
(Autorevert, Supporting additional buffers): Explain special treatment
Luc Teirlinck <teirllm@auburn.edu>
parents:
56119
diff
changeset
|
254 auto-revert every @code{auto-revert-interval} seconds. |
56119 | 255 |
56160
6ad083598109
(Supporting additional buffers): Minor change.
Luc Teirlinck <teirllm@auburn.edu>
parents:
56149
diff
changeset
|
256 Also, you may want to update the documentation string of |
6ad083598109
(Supporting additional buffers): Minor change.
Luc Teirlinck <teirllm@auburn.edu>
parents:
56149
diff
changeset
|
257 @code{global-auto-revert-non-file-buffers}. |
6ad083598109
(Supporting additional buffers): Minor change.
Luc Teirlinck <teirllm@auburn.edu>
parents:
56149
diff
changeset
|
258 |
56119 | 259 @ifinfo |
260 Finally, you should add a node to this chapter's menu. This node | |
261 @end ifinfo | |
262 @ifnotinfo | |
263 Finally, you should add a section to this chapter. This section | |
264 @end ifnotinfo | |
265 should at the very least make clear whether enabling auto-reverting | |
266 for the buffer reliably assures that all information in the buffer is | |
267 completely up to date (or will be after @code{auto-revert-interval} | |
268 seconds). | |
269 | |
270 @node Subdir switches | |
271 @chapter Subdirectory Switches in Dired | |
272 | |
273 You can insert subdirectories with specified @code{ls} switches in | |
274 Dired buffers, using @kbd{C-u i}. You can change the @code{ls} | |
275 switches of an already inserted subdirectory using @kbd{C-u l}. | |
276 | |
59996
aac0a33f5772
Change release version from 21.4 to 22.1 throughout.
Kim F. Storm <storm@cua.dk>
parents:
56473
diff
changeset
|
277 In Emacs versions 22.1 and later, Dired remembers the switches, so |
56119 | 278 that reverting the buffer will not change them back to the main |
279 directory's switches. Deleting a subdirectory forgets about its | |
280 switches. | |
281 | |
282 Using @code{dired-undo} (usually bound to @kbd{C-_} and @kbd{C-x u}) | |
283 to reinsert or delete subdirectories, that were inserted with explicit | |
284 switches, can bypass Dired's machinery for remembering (or forgetting) | |
285 switches. Deleting a subdirectory using @code{dired-undo} does not | |
286 forget its switches. When later reinserted using @kbd{i}, it will be | |
287 reinserted using its old switches. Using @code{dired-undo} to | |
288 reinsert a subdirectory that was deleted using the regular | |
289 Dired commands (not @code{dired-undo}) will originally insert it with | |
290 its old switches. However, reverting the buffer will relist it using | |
291 the buffer's default switches. If any of this yields problems, you | |
292 can easily correct the situation using @kbd{C-u i} or @kbd{C-u l}. | |
293 | |
56471
ca944d885fe6
(Subdir switches): Dired does not remember the `R' switch.
Luc Teirlinck <teirllm@auburn.edu>
parents:
56160
diff
changeset
|
294 Dired does not remember the @code{R} switch. Inserting a subdirectory |
ca944d885fe6
(Subdir switches): Dired does not remember the `R' switch.
Luc Teirlinck <teirllm@auburn.edu>
parents:
56160
diff
changeset
|
295 with switches that include the @code{R} switch is equivalent with |
ca944d885fe6
(Subdir switches): Dired does not remember the `R' switch.
Luc Teirlinck <teirllm@auburn.edu>
parents:
56160
diff
changeset
|
296 inserting each of its subdirectories using all remaining switches. |
56473
d9fdff5fee26
(Subdir switches): Minor fix to previous change.
Luc Teirlinck <teirllm@auburn.edu>
parents:
56471
diff
changeset
|
297 For instance, updating or killing a subdirectory that was inserted |
d9fdff5fee26
(Subdir switches): Minor fix to previous change.
Luc Teirlinck <teirllm@auburn.edu>
parents:
56471
diff
changeset
|
298 with the @code{R} switch will not update or kill its subdirectories. |
56471
ca944d885fe6
(Subdir switches): Dired does not remember the `R' switch.
Luc Teirlinck <teirllm@auburn.edu>
parents:
56160
diff
changeset
|
299 |
56119 | 300 The buffer's default switches do not affect subdirectories that were |
301 inserted using explicitly specified switches. In particular, | |
302 commands such as @kbd{s}, that change the buffer's switches do not | |
303 affect such subdirectories. (They do affect subdirectories without | |
304 explicitly assigned switches, however.) | |
305 | |
306 You can make Dired forget about all subdirectory switches and relist | |
307 all subdirectories with the buffer's default switches using | |
308 @kbd{M-x dired-reset-subdir-switches}. This also reverts the Dired buffer. | |
309 | |
310 @node Index | |
311 @unnumbered Index | |
312 | |
313 @printindex cp | |
314 | |
315 @bye | |
56131
0806d31e3c9c
Changes from arch/CVS synchronization
Miles Bader <miles@gnu.org>
parents:
56128
diff
changeset
|
316 |
0806d31e3c9c
Changes from arch/CVS synchronization
Miles Bader <miles@gnu.org>
parents:
56128
diff
changeset
|
317 @ignore |
0806d31e3c9c
Changes from arch/CVS synchronization
Miles Bader <miles@gnu.org>
parents:
56128
diff
changeset
|
318 arch-tag: 75c33f13-32c6-41b6-9537-847a312e2e49 |
0806d31e3c9c
Changes from arch/CVS synchronization
Miles Bader <miles@gnu.org>
parents:
56128
diff
changeset
|
319 @end ignore |