bug#37771: 26.3; doc for `dired-auto-revert-buffer'

[Drew Adams <drew.adams@oracle.com>]

> > Please consider improving the doc so that it does the following:
> >
> > * Explains what is meant by "visiting" a Dired buffer.  The Emacs
> >   manuals and other doc only speak about visiting a file in a buffer.
      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

> >   Just what constitutes "visiting" a Dired buffer?  It seems like
> >   it's sufficient to display the buffer and select its window.
> >   Is that it?
> 
> It means whatever Emacs means by "visiting" a file.  I don't see what's
> there to explain.

Why do you think so?  Nowhere in our doc do we introduce
a notion of "visiting" a buffer.  And a Dired buffer is
not a file.

Isn't what's really meant only that the buffer is displayed
and its window is selected?  If so, say so.  That's a far
cry from visiting a file.

> > * Explains the Value Menu items in Customize - in particular, item
> >   `Revert changed Dired buffer'.
> 
> Explaining what "revert" means in this context seems a bit odd.
> There's a manual for that.

No.  Buffer reverting is particular to different
kinds of buffer (apart from file buffers, where
it acts about the same for any file).  So explain
what it means to revert a Dired buffer.  And yes,
it means something particular.

> > * Explains that the option has no effect on Dired buffers containing
> >   arbitrary file lists (i.e., whose DIRNAME is a cons).  It is
> >   relevant only for actual directory listings.
> 
> You mean that switching it off doesn't stop reverting in that case?

Switching what off?  I don't know what you mean here.

The point is that reverting a Dired buffer means one
thing for a file listing (ordinary use of Dired).

It means something else when the buffer has any an
arbitrary list of files (e.g. from different dirs
that are not just subdirs).  In such cases IF
reverting is possible its behavior can be particular
to the particular kind of listing.  And this variable
does not apply - its value has no effect. 

> 	      ;; Always revert when `dir-or-list' is a cons.  Also revert
> 	      ;; if `dired-directory' is a cons but `dir-or-list' is not.
> 	      ((or (consp dir-or-list) (consp dired-directory))
> 	       (setq dired-directory dir-or-list)
> 	       (revert-buffer))
> 	      ;; Always revert regardless of whether it has changed or not.
> 	      ((eq dired-auto-revert-buffer t)
> 	       (revert-buffer))
> 
> As far as I can tell, this is only reached when you call `dired'
> explicitly with a list of file names?  That dired updates the buffer
> when you call it with a bunch of file names, without consulting
> dired-auto-revert-buffer, seems pretty self-evident.

Self-evident from the code.  The point is that the
_doc_ for the variable should say that it has no
effect in such cases - it applies only to ordinary
file listings, such as produced by `ls'.

> > * Lists the Lisp values that correspond to the Value Menu items.
> 
> They all seem documented?

No.  This one is not: "Revert changed Dired buffer".

> "Revert changed Dired buffer" dired-directory-changed-p)
> is just a predicate function.

Of course it is.  But it is a particular, predefined
predicate, which corresponds to one of the menu items.

This is no different from when we have menu items
that correspond to other particular values.  We
document them.  Users should be able to see the
correspondence between the documented Lisp values
and the menu items.

> Didn't see anything that needed fixing here, and I'm closing this bug
> report.

Unfortunate.