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

From: Drew Adams <[email-masked]>
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'.

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.

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

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

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)