*** empty log message ***
[emacs.git] / man / emacs-xtra.texi
blob9dff3d9efd87fc391304f25efb4a7864e82c9eb6
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
10 @copying
11 This manual describes specialized features of Emacs.
13 Copyright (C) 2004
14 Free Software Foundation, Inc.
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.
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.''
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
36 @dircategory Emacs
37 @direntry
38 * Emacs-Xtra: (emacs-xtra).    Specialized Emacs features.
39 @end direntry
41 @titlepage
42 @title Specialized Emacs Features
43 @page
44 @vskip 0pt plus 1filll
45 @insertcopying
46 @end titlepage
48 @contents
50 @ifnottex
51 @node Top
52 @top Specialized Emacs Features
54 @insertcopying
56 @end ifnottex
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
65 @node Introduction
66 @unnumbered Introduction
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.
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.
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.
88 @node Autorevert
89 @chapter Auto Reverting non-file Buffers
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.
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.
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.
113 At the other extreme, certain buffers automatically auto-revert every
114 @code{auto-revert-interval} seconds.  (This currently only applies to
115 the Buffer Menu.)  In this case, Auto Revert does not print any
116 messages while reverting, even when @code{auto-revert-verbose} is
117 non-@code{nil}.
119 The details depend on the particular types of buffers and are
120 explained in the corresponding sections.
122 @menu
123 * Auto Reverting the Buffer Menu::
124 * Auto Reverting Dired::
125 * Supporting additional buffers::
126 @end menu
128 @node Auto Reverting the Buffer Menu
129 @section Auto Reverting the Buffer Menu
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.)
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.
143 @node Auto Reverting Dired
144 @section Auto Reverting Dired buffers
146 Auto-reverting Dired buffers currently works on GNU or Unix style
147 operating systems.  It may not work satisfactorily on some other
148 systems.
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.
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
165 exception.  If you flag or mark files, you can safely revert the
166 buffer.  This will not erase the flags or marks (unless the marked
167 file has been deleted, of course).  However, the buffer will stay
168 modified, even after reverting, and auto-reverting will not resume.
169 This is because, if you flag or mark files, you may be working on the
170 buffer and you might not want the buffer to change without warning.
171 If you want auto-reverting to resume in the presence of marks and
172 flags, mark the buffer non-modified using @kbd{M-~}.  However, adding,
173 deleting or changing marks or flags will mark it modified again.
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.
180 @node Supporting additional buffers
181 @section Adding Support for Auto-Reverting additional Buffers.
183 This section is intended for Elisp programmers who would like to add
184 support for auto-reverting new types of buffers.
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}.
190 In addition, it @emph{must} have a @code{buffer-stale-function}.
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.
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.
210 If you just want to automatically auto-revert every
211 @code{auto-revert-interval} seconds, use:
213 @example
214 (set (make-local-variable 'buffer-stale-function)
215      #'(lambda (&optional noconfirm) 'fast))
216 @end example
218 @noindent
219 in the buffer's mode function.
221 The special return value @samp{fast} tells the caller that the need
222 for reverting was not checked, but that reverting the buffer is fast.
223 It also tells Auto Revert not to print any revert messages, even if
224 @code{auto-revert-verbose} is non-@code{nil}.  This is important, as
225 getting revert messages every @code{auto-revert-interval} seconds can
226 be very annoying.  The information provided by this return value could
227 also be useful if the function is consulted for purposes other than
228 auto-reverting.
229 @end defvar
231 Once the buffer has a @code{revert-buffer-function} and a
232 @code{buffer-stale-function}, several problems usually remain.
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.
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.
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.
253 This is especially important for buffers that automatically
254 auto-revert every @code{auto-revert-interval} seconds.
256 Also, you may want to update the documentation string of
257 @code{global-auto-revert-non-file-buffers}.
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).
270 @node Subdir switches
271 @chapter Subdirectory Switches in Dired
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}.
277 In Emacs versions 21.4 and later, Dired remembers the switches, so
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.
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}.
294 Dired does not remember the @code{R} switch.  Inserting a subdirectory
295 with switches that include the @code{R} switch is equivalent with
296 inserting each of its subdirectories using all remaining switches.
297 For instance, updating or killing a subdirectory that was inserted
298 with the @code{R} switch will not update or kill its subdirectories.
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.)
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.
310 @node Index
311 @unnumbered Index
313 @printindex cp
315 @bye
317 @ignore
318    arch-tag: 75c33f13-32c6-41b6-9537-847a312e2e49
319 @end ignore