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

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

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

mån 2019-04-29 klockan 19:23 +0300 skrev Eli Zaretskii:
> > 
> I think we should have sibling sections "Reverting" and "Autorevert",
> with the latter describing both types of auto-reverting.  And
> "Reverting" should have a cross-reference to "AutorevertAuto-" for
> automatic reverting of file-visiting buffers.

Here is a patch that does roughly that. I'm not entirely happy with the
old 'Auto-reverting non-buffer files' section, whose node name was just
'Autorevert'. I would have preferred it as a subsection to the new
auto-revert section, along with its existing two subsections, but since
its place isn't the same in the on-line and printed manuals, that
seemed technically tricky without duplicating a lot of text.



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

From d6ed8ed396a8a698ad63a8a4f3460ecdf982c507 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:
* doc/emacs/arevert-xtra.texi:
* doc/emacs/buffers.texi:
* doc/emacs/emacs.texi:
Rename node 'Autorevert' to 'Non-file buffers'.
Add node 'Auto-revert' and move general information on that topic there.
Shuffle text in that node into a rough least-to-most specific order.
---
 doc/emacs/arevert-xtra.texi |  2 +-
 doc/emacs/buffers.texi      |  4 +--
 doc/emacs/emacs.texi        |  3 +-
 doc/emacs/files.texi        | 61 ++++++++++++++++++++++---------------
 4 files changed, 42 insertions(+), 28 deletions(-)

diff --git a/doc/emacs/arevert-xtra.texi b/doc/emacs/arevert-xtra.texi
index cd7c1ff895..8575e1efdd 100644
--- a/doc/emacs/arevert-xtra.texi
+++ b/doc/emacs/arevert-xtra.texi
@@ -4,7 +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
+@node Non-file buffers
 @section Auto Reverting Non-File Buffers
 
 Global Auto Revert Mode normally only reverts file buffers.  There are
diff --git a/doc/emacs/buffers.texi b/doc/emacs/buffers.texi
index 27fcb7369a..66b21354c8 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{Non-file buffers,, emacs-xtra}, for details.
 @end iftex
 @ifnottex
-@xref{Autorevert, global-auto-revert-non-file-buffers}, for details.
+@xref{Non-file buffers, global-auto-revert-non-file-buffers}, for details.
 @end ifnottex
 
 @node Indirect Buffers
diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi
index 58ec373029..75b12940ea 100644
--- a/doc/emacs/emacs.texi
+++ b/doc/emacs/emacs.texi
@@ -443,8 +443,9 @@ 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.
+* Auto-revert::         Keeping buffers automatically up-to-date.
 @ifnottex
-* Autorevert::          Auto Reverting non-file buffers.
+* Non-file buffers::    Auto Reverting non-file buffers.
 @end ifnottex
 * Auto Save::           Auto Save periodically protects against loss of data.
 * File Aliases::        Handling multiple names for one file.
diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi
index 990b8f1679..93b2e79e70 100644
--- a/doc/emacs/files.texi
+++ b/doc/emacs/files.texi
@@ -25,8 +25,9 @@ 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.
+* Auto-revert::         Keeping buffers automatically up-to-date.
 @ifnottex
-* Autorevert::          Auto Reverting non-file buffers.
+* Non-file buffers::    Auto Reverting non-file buffers.
 @end ifnottex
 * Auto Save::           Auto Save periodically protects against loss of data.
 * File Aliases::        Handling multiple names for one file.
@@ -955,6 +956,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,21 +968,38 @@ 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
+  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}.
 
 @cindex file notifications
 @vindex auto-revert-use-notify
+@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
@@ -1002,24 +1025,14 @@ 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
 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
 under version control.  @xref{VC Mode Line}, for Auto Revert
 peculiarities when visiting files under version control.
+@xref{Non-file buffers} for auto-reverting buffers that do not visit
+files.
 
 @ifnottex
 @include arevert-xtra.texi
-- 
2.20.1