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

[Eli Zaretskii <eliz@gnu.org>]

> From: Mattias Engdegård <mattiase@acm.org>
> Cc: Eli Zaretskii <eliz@gnu.org>, 35418@debbugs.gnu.org
> Date: Thu, 02 May 2019 14:53:20 +0200
> 
> * doc/emacs/files.texi:
> * doc/emacs/arevert-xtra.texi:
> * doc/emacs/buffers.texi:
> * doc/emacs/emacs.texi:
> * doc/emacs/emacs-xtra.texi:
> Add node 'Auto-revert' and move general information on that topic there.
> Sort paragraphs in that node in a rough least-to-most specific order.
> Include the old 'Autorevert' node into that node when building the
> on-line manual.

It is better to cite the node names in the log, unless doing that is
completely impractical.

> 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.

So maybe we shouldn't remove the @node here?  How about making it a
subsection of "Auto Revert" instead?

> +@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.

> +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,7 +1010,7 @@ 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
   ^^^^^^^^^^^^^^^^^^^
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.

Thanks.