From 4e6fd592fe0577922376e0be4ae35cc909d6f379 Mon Sep 17 00:00:00 2001 From: Glenn Morris Date: Sun, 28 Jun 2009 00:47:28 +0000 Subject: [PATCH] Minor language tweaks. --- doc/emacs/ChangeLog | 4 +++ doc/emacs/arevert-xtra.texi | 59 +++++++++++++++++++------------------ 2 files changed, 34 insertions(+), 29 deletions(-) diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog index 16f92a49b66..2de7a6b4d1f 100644 --- a/doc/emacs/ChangeLog +++ b/doc/emacs/ChangeLog @@ -1,3 +1,7 @@ +2009-06-28 Glenn Morris + + * arevert-xtra.texi: Minor language tweaks. + 2009-06-17 Kenichi Handa * mule.texi (Charsets): Update the description for the new charset. diff --git a/doc/emacs/arevert-xtra.texi b/doc/emacs/arevert-xtra.texi index b3457e8dab7..f2151186555 100644 --- a/doc/emacs/arevert-xtra.texi +++ b/doc/emacs/arevert-xtra.texi @@ -1,5 +1,6 @@ @c This is part of the Emacs manual. -@c Copyright (C) 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. +@c Copyright (C) 2004, 2005, 2006, 2007, 2008, 2009 +@c 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 @@ -7,13 +8,12 @@ @node Autorevert @section Auto Reverting non-file Buffers -Normally Global Auto Revert Mode only reverts file buffers. There are +Global Auto Revert Mode normally 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 +Mode in those buffers (using @kbd{M-x auto-revert-mode}); and setting +@code{global-auto-revert-non-file-buffers} non-@code{nil}. 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. +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 +26,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 @@ -67,14 +67,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,10 +92,10 @@ 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. @samp{*Find*} and +@samp{*Locate*} buffers do not auto-revert either. @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,21 +166,21 @@ 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 -- 2.39.2