bug#35418: [PATCH] Don't poll auto-revert files that use notification

["Mattias Engdegård" <mattiase@acm.org>]

[-- Attachment #1: Type: text/plain, Size: 2160 bytes --]

fre 2019-05-03 klockan 16:44 +0300 skrev Eli Zaretskii:
> > 
> It is better to cite the node names in the log, unless doing that is
> completely impractical.

Done. I found it a bit impractical in this case, but did so anyway.

> > -@node Autorevert
> > -@section Auto Reverting Non-File Buffers
> > +@c The including file must provide its own @node and @section
> > lines.
> 
> So maybe we shouldn't remove the @node here?  How about making it a
> subsection of "Auto Revert" instead?

The text in arevert-xtra has two subsections already. Then we would
have three subsections, where the first acts as a sort of prelude to
the two others. That might work for the on-line manual, but how would
it fit into emacs-xtra? What would the section be then?

> > +@vindex auto-revert-remote-files
> > +  These minor modes do not check or revert remote files, because
> > that is
> 
> Which "these minor modes"?  Such wording is only appropriate when it
> closely follows a list of modes, which is not the case here.  I think
> it's better to enumerate the modes explicitly here.

Replaced with 'The Auto Revert modes'; this should be readily
understood.

> >  periodically even when file notifications are used.  Such polling
> > is
> >  usually unnecessary, and turning it off may save power by relying
> > on
>    ^^^^^^^^^^^^^^^^^^^
> I would say "unnecessary in many cases".  "usually" begs the question
> why by default we do poll.  Bonus points for adding some hint about
> what rare situations do need such polling, as I think this
> description
> sounds like a small riddle without that, and doesn't allow people to
> make an educated decision regarding whether they do or don't want the
> polling turned off.

Done, but the hint you are asking for does come right after:

  [...] However,
  notification is ineffective on certain file systems; mainly network
  file system on Unix-like machines, where files can be altered from
  other machines.

which is the most important case that I'm aware of. (According to
Michael, Tramp notifications can be unreliable sometimes, but they have
to be enabled actively.)

Thanks for the review! Revised patch attached.


[-- Attachment #2: 0001-Reorganise-auto-revert-nodes-in-the-manual.patch --]
[-- Type: text/x-patch, Size: 9942 bytes --]

From 3b9fc1d288cb7168db3f1352f6e261266dbe4349 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Mattias=20Engdeg=C3=A5rd?= <mattiase@acm.org>
Date: Tue, 30 Apr 2019 22:35:56 +0200
Subject: [PATCH] Reorganise (auto-)revert nodes in the manual

The amount of information on auto-revert has grown to deserve a
section of its own (bug#35418).

* doc/emacs/files.texi
(Files): Adjust menu.
(Reverting, Auto Revert):
Add node `Auto Revert' and move general information on that topic there
from `Reverting'.
Sort paragraphs in `Auto Revert' in a rough least-to-most specific order.
Include the old `Autorevert' text and subsections into that node when
building the on-line manual.
(Autorevert): Remove.
* doc/emacs/arevert-xtra.texi (Autorevert): Remove node and section lines.
* doc/emacs/buffers.texi (Several Buffers): Adjust references.
* doc/emacs/emacs.texi (Top): Adjust menu.
* doc/emacs/emacs-xtra.texi:
(Top): Adjust menu.
(Non-File Buffers): Add node and section lines.
---
 doc/emacs/arevert-xtra.texi |  3 +-
 doc/emacs/buffers.texi      |  4 +--
 doc/emacs/emacs-xtra.texi   |  4 ++-
 doc/emacs/emacs.texi        |  4 +--
 doc/emacs/files.texi        | 71 +++++++++++++++++++++----------------
 5 files changed, 47 insertions(+), 39 deletions(-)

diff --git a/doc/emacs/arevert-xtra.texi b/doc/emacs/arevert-xtra.texi
index cd7c1ff895..8cc5b053b5 100644
--- a/doc/emacs/arevert-xtra.texi
+++ b/doc/emacs/arevert-xtra.texi
@@ -4,8 +4,7 @@
 @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
+@c The including file must provide its own @node and @section lines.
 
 Global Auto Revert Mode normally only reverts file buffers.  There are
 two ways to auto-revert certain non-file buffers: by enabling Auto
diff --git a/doc/emacs/buffers.texi b/doc/emacs/buffers.texi
index 27fcb7369a..14a0a01ca8 100644
--- a/doc/emacs/buffers.texi
+++ b/doc/emacs/buffers.texi
@@ -568,10 +568,10 @@ Several Buffers
 Auto Revert mode applies to the @file{*Buffer List*} buffer only if
 @code{global-auto-revert-non-file-buffers} is non-@code{nil}.
 @iftex
-@inforef{Autorevert,, emacs-xtra}, for details.
+@inforef{Auto Reverting the Buffer Menu,, emacs-xtra}, for details.
 @end iftex
 @ifnottex
-@xref{Autorevert, global-auto-revert-non-file-buffers}, for details.
+@xref{Auto Reverting the Buffer Menu, global-auto-revert-non-file-buffers}, for details.
 @end ifnottex
 
 @node Indirect Buffers
diff --git a/doc/emacs/emacs-xtra.texi b/doc/emacs/emacs-xtra.texi
index dcd8fae1b6..84bbdb84d0 100644
--- a/doc/emacs/emacs-xtra.texi
+++ b/doc/emacs/emacs-xtra.texi
@@ -59,7 +59,7 @@ Top
 * Picture Mode::        Editing pictures made up of characters using
                          the quarter-plane screen model.
 
-* Autorevert::          Auto Reverting non-file buffers.
+* Non-File Buffers::    Auto Reverting non-file buffers.
 * Subdir Switches::     Subdirectory switches in Dired.
 * Advanced Calendar/Diary Usage:: Advanced Calendar/Diary customization.
 * Emerge::              A convenient way of merging two versions of a program.
@@ -111,6 +111,8 @@ Introduction
 @raisesections
 @include picture-xtra.texi
 
+@node Non-File Buffers
+@section Auto Reverting Non-File Buffers
 @include arevert-xtra.texi
 
 @include dired-xtra.texi
diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi
index 58ec373029..a34cef221e 100644
--- a/doc/emacs/emacs.texi
+++ b/doc/emacs/emacs.texi
@@ -443,9 +443,7 @@ Top
 * Visiting::            Visiting a file prepares Emacs to edit the file.
 * Saving::              Saving makes your changes permanent.
 * Reverting::           Reverting cancels all the changes not saved.
-@ifnottex
-* Autorevert::          Auto Reverting non-file buffers.
-@end ifnottex
+* Auto Revert::         Keeping buffers automatically up-to-date.
 * Auto Save::           Auto Save periodically protects against loss of data.
 * File Aliases::        Handling multiple names for one file.
 * Directories::         Creating, deleting, and listing file directories.
diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi
index 990b8f1679..7f5e16a845 100644
--- a/doc/emacs/files.texi
+++ b/doc/emacs/files.texi
@@ -25,9 +25,7 @@ Files
 * Visiting::            Visiting a file prepares Emacs to edit the file.
 * Saving::              Saving makes your changes permanent.
 * Reverting::           Reverting cancels all the changes not saved.
-@ifnottex
-* Autorevert::          Auto Reverting non-file buffers.
-@end ifnottex
+* Auto Revert::         Keeping buffers automatically up-to-date.
 * Auto Save::           Auto Save periodically protects against loss of data.
 * File Aliases::        Handling multiple names for one file.
 * Directories::         Creating, deleting, and listing file directories.
@@ -955,6 +953,11 @@ Reverting
 is not modified.  (If you have edited the text, it would be wrong to
 discard your changes.)
 
+  You can also tell Emacs to revert buffers automatically when their
+visited files change on disk; @pxref{Auto Revert}.
+
+@node Auto Revert
+@section Auto Revert: Keeping buffers automatically up-to-date
 @cindex Global Auto Revert mode
 @cindex mode, Global Auto Revert
 @cindex Auto Revert mode
@@ -962,22 +965,39 @@ Reverting
 @findex global-auto-revert-mode
 @findex auto-revert-mode
 @findex auto-revert-tail-mode
-@vindex auto-revert-interval
-@vindex auto-revert-remote-files
+
+  A buffer can get out of sync with respect to its visited file on
+disk if that file is changed by another program.  To keep it up to
+date, you can enable Auto Revert mode by typing @kbd{M-x auto-revert-mode}.
+This automatically reverts the buffer when its visited file changes on
+disk.  To do the same for all file buffers, type
+@kbd{M-x global-auto-revert-mode} to enable Global Auto Revert mode.
+
+  Auto Revert will not revert a buffer if it has unsaved changes, or if
+its file on disk is deleted or renamed.
+
+  One use of Auto Revert mode is to ``tail'' a file such as a system
+log, so that changes made to that file by other programs are
+continuously displayed.  To do this, just move the point to the end of
+the buffer, and it will stay there as the file contents change.
+However, if you are sure that the file will only change by growing at
+the end, use Auto Revert Tail mode instead
+(@code{auto-revert-tail-mode}).  It is more efficient for this.
+Auto Revert Tail mode also works for remote files.
+
 @vindex auto-revert-verbose
-  You can also tell Emacs to revert buffers periodically.  To do this
-for a specific buffer, enable the minor mode Auto-Revert mode by
-typing @kbd{M-x auto-revert-mode}.  This automatically reverts the
-current buffer when its visited file changes on disk.  To do the same
-for all file buffers, type @kbd{M-x global-auto-revert-mode} to enable
-Global Auto-Revert mode.  These minor modes do not check or revert
-remote files, because that is usually too slow.  This behavior can be
-changed by setting the variable @code{auto-revert-remote-files} to
-non-@code{nil}.
+  When a buffer is auto-reverted, a message is generated.  This can be
+suppressed by setting @code{auto-revert-verbose} to @code{nil}.
+
+@vindex auto-revert-remote-files
+  The Auto Revert modes do not check or revert remote files, because
+that is usually too slow.  This behavior can be changed by setting the
+variable @code{auto-revert-remote-files} to non-@code{nil}.
 
 @cindex file notifications
 @vindex auto-revert-use-notify
-  By default, Auto-Revert mode works using @dfn{file notifications},
+@vindex auto-revert-interval
+  By default, Auto Revert mode works using @dfn{file notifications},
 whereby changes in the filesystem are reported to Emacs by the OS.
 You can disable use of file notifications by customizing the variable
 @code{auto-revert-use-notify} to a @code{nil} value, then Emacs will
@@ -990,10 +1010,10 @@ Reverting
 
 @vindex auto-revert-avoid-polling
 @vindex auto-revert-notify-exclude-dir-regexp
-  By default, Auto-Revert mode will poll files for changes
+  By default, Auto Revert mode will poll files for changes
 periodically even when file notifications are used.  Such polling is
-usually unnecessary, and turning it off may save power by relying on
-notifications only.  To do so, set the variable
+unnecessary in many cases, and turning it off may save power by
+relying on notifications only.  To do so, set the variable
 @code{auto-revert-avoid-polling} to non-@code{nil}.  However,
 notification is ineffective on certain file systems; mainly network
 file system on Unix-like machines, where files can be altered from
@@ -1002,19 +1022,7 @@ Reverting
 @code{auto-revert-notify-exclude-dir-regexp} to match files that
 should be excluded from using notification.
 
-  One use of Auto-Revert mode is to ``tail'' a file such as a system
-log, so that changes made to that file by other programs are
-continuously displayed.  To do this, just move the point to the end of
-the buffer, and it will stay there as the file contents change.
-However, if you are sure that the file will only change by growing at
-the end, use Auto-Revert Tail mode instead
-(@code{auto-revert-tail-mode}).  It is more efficient for this.
-Auto-Revert Tail mode works also for remote files.
-
-  When a buffer is auto-reverted, a message is generated.  This can be
-suppressed by setting @code{auto-revert-verbose} to @code{nil}.
-
-  In Dired buffers (@pxref{Dired}), Auto-Revert mode refreshes the
+  In Dired buffers (@pxref{Dired}), Auto Revert mode refreshes the
 buffer when a file is created or deleted in the buffer's directory.
 
   @xref{VC Undo}, for commands to revert to earlier versions of files
@@ -1022,6 +1030,7 @@ Reverting
 peculiarities when visiting files under version control.
 
 @ifnottex
+@c The node text continues here.
 @include arevert-xtra.texi
 @end ifnottex
 
-- 
2.20.1