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

From: Eli Zaretskii <[email-masked]>
Date: Sat, 04 May 2019 12:04:28 +0300

> From: Mattias Engdegård <[email-masked]>
> Cc: [email-masked], [email-masked]
> Date: Fri, 03 May 2019 16:47:51 +0200
> 
> > 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.

Thanks, but why did you start the description of the change on a new
line?  Here:

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

This should be formatted like this (indented 2 spaces for clarity):

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

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.

> > > -@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?

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?

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

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

Thanks.