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

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

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

lör 2019-05-04 klockan 12:04 +0300 skrev Eli Zaretskii:
> 
> IOW, only when you describe changes to another node you should start
> on a new line.  The above is the formatting produced by "C-x 4 a" and
> its ilk.

Reformatted.

> No, I meant make "Autorevert" (under its new name) a subsection of
> "Auto Revert", and the 2 subsections of "Autorevert" sub-subsections.
> Or did I misunderstand the problem you were describing?

Done. It seems that a subsection can be directly under a top node
without a section as intermediate step; I didn't know that.

> Yes, but that hint doesn't mention the polling.  I think it's
> important to tell that polling is needed in these rare cases.

Text added.

Thanks again; revised patch attached.

> 

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

From ea7c087df14f302543ce9e2711cc8cbde09dbc30 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

Put all information about auto-revert into a section of its own, and
organise the text in a more logical way.  Previously it was mainly
described in the section about reverting (bug#35418).

* doc/emacs/files.texi (Files): Adjust menu.
(Reverting, Auto Revert, Autorevert): Add node `Auto Revert' and move
text on that topic from `Reverting', rearranged.  Turn the old
`Autorevert' node into a subsection under `Auto Revert'.
* doc/emacs/arevert-xtra.texi (Autorevert): Rename and turn into
subsubsection.
* 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 |  9 +++--
 doc/emacs/buffers.texi      |  4 +-
 doc/emacs/emacs-xtra.texi   |  2 +-
 doc/emacs/emacs.texi        |  4 +-
 doc/emacs/files.texi        | 75 +++++++++++++++++++++----------------
 5 files changed, 51 insertions(+), 43 deletions(-)

diff --git a/doc/emacs/arevert-xtra.texi b/doc/emacs/arevert-xtra.texi
index cd7c1ff895..9e01a10ace 100644
--- a/doc/emacs/arevert-xtra.texi
+++ b/doc/emacs/arevert-xtra.texi
@@ -4,8 +4,9 @@
 @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
+
+@node Non-File Buffers
+@subsection Auto Reverting Non-File Buffers
 
 Global Auto Revert Mode normally only reverts file buffers.  There are
 two ways to auto-revert certain non-file buffers: by enabling Auto
@@ -43,7 +44,7 @@ Autorevert
 @end menu
 
 @node Auto Reverting the Buffer Menu
-@subsection Auto Reverting the Buffer Menu
+@subsubsection Auto Reverting the Buffer Menu
 
 If auto-reverting of non-file buffers is enabled, the Buffer Menu
 @iftex
@@ -65,7 +66,7 @@ Auto Reverting the Buffer Menu
 automatically erasing the marks.
 
 @node Auto Reverting Dired
-@subsection Auto Reverting Dired buffers
+@subsubsection Auto Reverting Dired buffers
 
 Dired buffers only auto-revert when the file list of the buffer's main
 directory changes (e.g., when a new file is added or deleted).  They
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..e9231b4e3a 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.
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..c51d076fa2 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,31 +1010,20 @@ Reverting
 
 @vindex auto-revert-avoid-polling
 @vindex auto-revert-notify-exclude-dir-regexp
-  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
+  By default, Auto Revert mode will poll files for changes
+periodically even when file notifications are used.  Polling is
+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
-other machines.  To force polling when
+other machines.  For such file systems, polling may be necessary.
+To force polling when
 @code{auto-revert-avoid-polling} is non-@code{nil}, set
 @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
-- 
2.20.1