bug#67053: 29.1; Doc string of variable `dired-use-ls-dired'

[Eli Zaretskii]

> From: Drew Adams <drew.adams@oracle.com>
> Date: Fri, 10 Nov 2023 20:41:01 +0000
> 
> emacs -Q.
> 
> With MS Windows, which uses ls-lisp, the value of this variable is
> `unspecified'.  I think it always has this value.  Maybe this is
> necessary/correct (?).
> 
> But the doc string says this:
> 
>  The special value of 'unspecified' means to check whether "ls"
>  supports the "--dired" option, and save the result in this
>  variable.  This is performed the first time 'dired-insert-directory'
>  is invoked.
> 
> That's not as clear as it should be.  It gives the impression that the
> result of saving the result of that check of the value will be nil or
> some non-nil value other than `unspecified'.

Which is exactly what happens, when Dired uses 'ls'.

> It would be better to at least say that the result of the check can be
> that it hasn't been determined whether "ls" supports the "--dired"
> option, and thus that the variable value will remain `unspecified'
> after the check.

No, it will be either nil or non-nil, depending on the results of the
test.  Which is exactly what the doc string says.

> Or if it's the case that the check does, for MS Windows (or more
> generally for ls-lisp use), determine that "ls" doesn't support
> "--dired", then the value should be changed from `unspecified' to some
> other non-nil value, such as `t'.

No, it changes to nil if 'ls' that is used by Dired doesn't support
'--dired'.  As expected.

> Perhaps I'm misunderstanding something?  If so, please make the doc
> string clearer to avoid such misunderstanding.  Thx.

I don't see what is unclear in the doc string.  I suggest that you
try it:

  emacs -Q
  M-x set-variable RET ls-lisp-use-insert-directory-program RET t RET
  C-h v dired-use-ls-dired RET
  C-x d SOME-DIRECTORY RET
  C-h v dired-use-ls-dired RET

Depending on what version of 'ls' you have installed, the 2nd "C-h v"
will show either t or nil as the value of the variable.

So I don't see anything that we need to fix in this doc string.