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

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

[Drew Adams]

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)

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]

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)

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

[Drew Adams]

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

Yes, it mentions MS Windows.  But that text is unrelated
to this bug, which is about the value that results from
checking for support of "--dired".  It's not clear from
the doc that that result can be `unspecified'.  The
wording suggests that the "check" clears up `unspecified',
replacing it, presumably, with either nil or some non-nil
value other than `unspecified'.

The special value of `unspecified' apparently does _not_
just mean that such a check is needed and will be done.
The value means that support isn't known, whether or
not the check has been done.

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

[Eli Zaretskii]

> Cc: 67053@debbugs.gnu.org
> From: Drew Adams <drew.adams@oracle.com>
> Date: Fri, 10 Nov 2023 23:40:45 +0000
> 
> The special value of `unspecified' apparently does _not_
> just mean that such a check is needed and will be done.
> The value means that support isn't known, whether or
> not the check has been done.

No, it means the check has not been done yet, and will be done when
needed.  After the check the value will never be 'unspecified'.

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

[Michael Heerdegen]

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

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

AFAIU in your case this check is never performed (because
`ls-lisp-use-insert-directory-program' defaults to nil in your case).

The doc is not really wrong because "This is performed the first time
`dired-insert-directory' is invoked." is just never for you.

Michael.

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

[Drew Adams]

> > Perhaps I'm misunderstanding something?  If so, please make the doc
> > string clearer to avoid such misunderstanding.
> 
> AFAIU in your case this check is never performed (because
> `ls-lisp-use-insert-directory-program' defaults to nil in your case).

Yes.

> The doc is not really wrong because "This is performed the first time
> `dired-insert-directory' is invoked." is just never for you.

1. I don't see that the check never being performed
makes that doc, as written, any clearer, or that
understanding that doc depends on the check being
performed or on function `dired-insert-directory'
being invoked.

Understanding the actual behavior on MS Windows does
depend on the check (not) being performed, but that's
the code, not the doc.

2. (a) Yes, `ls-lisp-use-insert-directory-program'
is nil in my case, but (b) `dired-insert-directory'
_is_ invoked.

Debugger entered--entering a function:
* dired-insert-directory("z:/foo/bar/toto/bbbbb/" "-al" nil nil t)
  ^^^^^^^^^^^^^^^^^^^^^^
  dired-readin-insert()
  #f(compiled-function () #<bytecode -0xc727057c68a81bd>)()
  combine-change-calls-1(1 1 #f(compiled-function ...))
  dired-readin()
  dired-internal-noselect("z:/foo/bar/toto/bbbbb/" nil)
  dired-noselect("~/toto/bbbbb" nil)
  #f(compiled-function (dirname &optional switches) ...
  ls-lisp--dired(#f(compiled-function ...
  apply(ls-lisp--dired #f(compiled-function ...
  dired("~/toto/bbbbb" nil)
  funcall-interactively(dired "~/toto/bbbbb" nil)
  command-execute(dired)

The _check of `dired-use-ls-dired'_ is never done by
`dired-insert-directory', because this test is nil:

  (not (and (featurep 'ls-lisp)
       (null ls-lisp-use-insert-directory-program)))

This doesn't clarify that doc, IMO.  It does, however,
mean that the part you quoted is incorrect - the doc
_is_ really wrong.

When `ls-lisp-use-insert-directory-program' is nil,
not only does the check not occur the first time
`dired-insert-directory' is invoked, but it's _never_
performed.

In short, `dired-use-ls-dired' isn't used if option
`ls-lisp-use-insert-directory-program' is nil; it's
irrelevant in that case.  The doc should say that.

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

[Michael Heerdegen]

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

> In short, `dired-use-ls-dired' isn't used if option
> `ls-lisp-use-insert-directory-program' is nil; it's
> irrelevant in that case.  The doc should say that.

If that is what you suggest - yes, I think this would be reasonable.

Michael.

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

[Eli Zaretskii]

> Cc: "67053@debbugs.gnu.org" <67053@debbugs.gnu.org>
> From: Michael Heerdegen <michael_heerdegen@web.de>
> Date: Sat, 11 Nov 2023 07:43:14 +0100
> 
> Drew Adams <drew.adams@oracle.com> writes:
> 
> > In short, `dired-use-ls-dired' isn't used if option
> > `ls-lisp-use-insert-directory-program' is nil; it's
> > irrelevant in that case.  The doc should say that.
> 
> If that is what you suggest - yes, I think this would be reasonable.

If that's the only problem with the doc string, then I already added a
note to that affect (although I wonder why a user who doesn't use 'ls'
would be bothered by this factoid).  FTR, it was very hard to
understand from the original report that this is the source of the
confusion.  Why would someone expect Emacs to check what 'ls' does if
'ls' is not used?

Anyway, I'm now closing this bug, as I don't think we have anything
else to do here.

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.