Mercurial > emacs

--- a/doc/emacs/ChangeLog	Sat Jun 27 22:09:39 2009 +0000
+++ b/doc/emacs/ChangeLog	Sun Jun 28 00:47:58 2009 +0000
@@ -1,3 +1,7 @@
+2009-06-28  Glenn Morris  <rgm@gnu.org>
+
+	* arevert-xtra.texi: Minor language tweaks.
+
 2009-06-23  Miles Bader  <miles@gnu.org>

 	* display.texi (Scrolling): Document `recenter-redisplay'
--- a/doc/emacs/arevert-xtra.texi	Sat Jun 27 22:09:39 2009 +0000
+++ b/doc/emacs/arevert-xtra.texi	Sun Jun 28 00:47:58 2009 +0000
@@ -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 @@
 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 @@
 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 @@
 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 @@
 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 @@
 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 @@
 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