X-Git-Url: https://git.hcoop.net/bpt/emacs.git/blobdiff_plain/7b1019e2781472c793d0bf74e2b9ee17894270b8..be4e7c155b6922dd6105f4be57164210c3441f37:/doc/emacs/arevert-xtra.texi diff --git a/doc/emacs/arevert-xtra.texi b/doc/emacs/arevert-xtra.texi index f7682f897b..55d7646542 100644 --- a/doc/emacs/arevert-xtra.texi +++ b/doc/emacs/arevert-xtra.texi @@ -1,19 +1,18 @@ @c This is part of the Emacs manual. -@c Copyright (C) 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc. +@c Copyright (C) 2004-2012 Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @c @c This file is included either in emacs-xtra.texi (when producing the @c printed version) or in the main Emacs manual (for the on-line version). @node Autorevert -@section Auto Reverting non-file Buffers +@section Auto Reverting Non-File Buffers -Normally Global Auto Revert Mode only reverts file buffers. There are -two ways to auto-revert certain non-file buffers: enabling Auto Revert -Mode in those buffers (using @kbd{M-x auto-revert-mode}) and setting -@code{global-auto-revert-non-file-buffers} to @code{t}. The latter -enables Auto Reverting for all types of buffers for which it is -implemented, that is, for the types of buffers listed in the menu -below. +Global Auto Revert Mode normally only reverts file buffers. There are +two ways to auto-revert certain non-file buffers: by enabling Auto +Revert Mode in those buffers (using @kbd{M-x auto-revert-mode}); and +by setting @code{global-auto-revert-non-file-buffers} to a +non-@code{nil} value. The latter enables Auto Reverting for all types +of buffers for which it is implemented (listed in the menu below). Like file buffers, non-file buffers should normally not revert while you are working on them, or while they contain information that might @@ -26,10 +25,10 @@ Another tricky detail is that, for efficiency reasons, Auto Revert often does not try to detect all possible changes in the buffer, only changes that are ``major'' or easy to detect. Hence, enabling auto-reverting for a non-file buffer does not always guarantee that -all information in the buffer is up to date and does not necessarily +all information in the buffer is up-to-date, and does not necessarily make manual reverts useless. -At the other extreme, certain buffers automatically auto-revert every +At the other extreme, certain buffers automatically revert every @code{auto-revert-interval} seconds. (This currently only applies to the Buffer Menu.) In this case, Auto Revert does not print any messages while reverting, even when @code{auto-revert-verbose} is @@ -39,9 +38,9 @@ The details depend on the particular types of buffers and are explained in the corresponding sections. @menu -* Auto Reverting the Buffer Menu:: -* Auto Reverting Dired:: -* Supporting additional buffers:: +* Auto Reverting the Buffer Menu:: Auto Revert of the Buffer Menu. +* Auto Reverting Dired:: Auto Revert of Dired buffers. +* Supporting additional buffers:: How to add more Auto Revert support. @end menu @node Auto Reverting the Buffer Menu @@ -67,14 +66,15 @@ operating systems. It may not work satisfactorily on some other systems. Dired buffers only auto-revert when the file list of the buffer's main -directory changes. They do not auto-revert when information about a -particular file changes or when inserted subdirectories change. To be -sure that @emph{all} listed information is up to date, you have to -manually revert using @kbd{g}, @emph{even} if auto-reverting is +directory changes (e.g. when a new file is added). They do not +auto-revert when information about a particular file changes +(e.g. when the size changes) or when inserted subdirectories change. +To be sure that @emph{all} listed information is up to date, you have +to manually revert using @kbd{g}, @emph{even} if auto-reverting is enabled in the Dired buffer. Sometimes, you might get the impression that modifying or saving files listed in the main directory actually does cause auto-reverting. This is because making changes to a file, -or saving it, very often causes changes in the directory itself, for +or saving it, very often causes changes in the directory itself; for instance, through backup files or auto-save files. However, this is not guaranteed. @@ -91,11 +91,12 @@ If you want auto-reverting to resume in the presence of marks and flags, mark the buffer non-modified using @kbd{M-~}. However, adding, deleting or changing marks or flags will mark it modified again. -Remote Dired buffers are not auto-reverted. Neither are Dired buffers -for which you used shell wildcards or file arguments to list only some -of the files. @samp{*Find*} and @samp{*Locate*} buffers do not -auto-revert either. +Remote Dired buffers are not auto-reverted (because it may be slow). +Neither are Dired buffers for which you used shell wildcards or file +arguments to list only some of the files. @file{*Find*} and +@file{*Locate*} buffers do not auto-revert either. +@c FIXME? This should be in the elisp manual? @node Supporting additional buffers @subsection Adding Support for Auto-Reverting additional Buffers. @@ -127,7 +128,7 @@ If the function is only going to be used for auto-reverting, you can ignore the @var{noconfirm} argument. If you just want to automatically auto-revert every -@code{auto-revert-interval} seconds, use: +@code{auto-revert-interval} seconds (like the Buffer Menu), use: @example (set (make-local-variable 'buffer-stale-function) @@ -153,7 +154,7 @@ Once the buffer has a @code{revert-buffer-function} and a The buffer will only auto-revert if it is marked unmodified. Hence, you will have to make sure that various functions mark the buffer modified if and only if either the buffer contains information that -might be lost by reverting or there is reason to believe that the user +might be lost by reverting, or there is reason to believe that the user might be inconvenienced by auto-reverting, because he is actively working on the buffer. The user can always override this by manually adjusting the modified status of the buffer. To support this, calling @@ -165,27 +166,23 @@ as a consequence of auto-reverting. Of course, moving point might be inevitable if the buffer radically changes. You should make sure that the @code{revert-buffer-function} does not -print messages that unnecessarily duplicate Auto Revert's own messages -if @code{auto-revert-verbose} is @code{t} and effectively override a -@code{nil} value for @code{auto-revert-verbose}. Hence, adapting a -mode for auto-reverting often involves getting rid of such messages. -This is especially important for buffers that automatically -auto-revert every @code{auto-revert-interval} seconds. +print messages that unnecessarily duplicate Auto Revert's own messages, +displayed if @code{auto-revert-verbose} is @code{t}, and effectively +override a @code{nil} value for @code{auto-revert-verbose}. Hence, +adapting a mode for auto-reverting often involves getting rid of such +messages. This is especially important for buffers that automatically +revert every @code{auto-revert-interval} seconds. -Also, you may want to update the documentation string of -@code{global-auto-revert-non-file-buffers}. +If the new auto-reverting is part of Emacs, you should mention it +in the documentation string of @code{global-auto-revert-non-file-buffers}. @ifinfo -Finally, you should add a node to this chapter's menu. This node +Similarly, you should add a node to this chapter's menu. This node @end ifinfo @ifnotinfo -Finally, you should add a section to this chapter. This section +Similarly, you should add a section to this chapter. This section @end ifnotinfo should at the very least make clear whether enabling auto-reverting for the buffer reliably assures that all information in the buffer is completely up to date (or will be after @code{auto-revert-interval} seconds). - -@ignore - arch-tag: 2983e613-a272-45f6-9593-3010ad7f865e -@end ignore