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

[Jeremy Bryant via "Bug reports for GNU Emacs, the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>]

Here are some thoughts to help explore a modification of the docstring.

I observe the rest of the docstring mentions MS Windows explicitly, but
maybe incomplete for your suggestion.

"
...support this option.  Alternatively, you might want to use Emacs's
own emulation of \"ls\", by using:
  (setq ls-lisp-use-insert-directory-program nil)
  (require \\='ls-lisp)
This is used by default on MS Windows, which does not have an \"ls\" program.
Note that `ls-lisp' does not support as many options as GNU ls, though.
For more details, see Info node `(emacs)ls in Lisp'."
"


(On my machine (GNU/Linux), this variable starts at the defcustom
default of 'unspecified until the first call of M-x dired, whereupon it
becomes t )

Drew Adams <drew.adams@oracle.com> writes:

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

Do you think there should be a specific value such as maybe 'dired-flag-unsupported

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

Would you suggest that the right thing would be for the value to move
from 'unspecified to something like 'check-inconclusive?  This is a
change in the defun not just the docstring

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

In the current docstring, t is describes as confirming that ls DOES
support --dired

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

I can propose a patch but I have an incomplete understanding of the
problem above.

>
> In GNU Emacs 29.1 (build 2, x86_64-w64-mingw32) of 2023-08-02 built on
>  AVALON
> Windowing system distributor 'Microsoft Corp.', version 10.0.19045
> System Description: Microsoft Windows 10 Pro (v10.0.2009.19045.3570)
>
> Configured using:
>  'configure --with-modules --without-dbus --with-native-compilation=aot
>  --without-compress-install --with-tree-sitter CFLAGS=-O2'
>
> Configured features:
> ACL GIF GMP GNUTLS HARFBUZZ JPEG JSON LCMS2 LIBXML2 MODULES NATIVE_COMP
> NOTIFY W32NOTIFY PDUMPER PNG RSVG SOUND SQLITE3 THREADS TIFF
> TOOLKIT_SCROLL_BARS TREE_SITTER WEBP XPM ZLIB
>
> (NATIVE_COMP present but libgccjit not available)