emacs-28 a8bb12ab05: Improve discoverability of 'insert-directory-program'

[Eli Zaretskii]

branch: emacs-28
commit a8bb12ab054e063718687c0d8565ff9e7276585a
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    Improve discoverability of 'insert-directory-program'
    
    * lisp/files.el (insert-directory-program): Mention 'dired' in the
    doc string.
    * lisp/dired.el (dired): Mention 'insert-directory-program' in the
    doc string.  (Bug#54962)
---
 lisp/dired.el | 7 +++++--
 lisp/files.el | 4 +++-
 2 files changed, 8 insertions(+), 3 deletions(-)

diff --git a/lisp/dired.el b/lisp/dired.el
index a3768d224b..f5ddd7aa39 100644
--- a/lisp/dired.el
+++ b/lisp/dired.el
@@ -994,8 +994,11 @@ If a directory or nothing is found at point, return nil."
 ;;;###autoload
 (defun dired (dirname &optional switches)
   "\"Edit\" directory DIRNAME--delete, rename, print, etc. some files in it.
-Optional second argument SWITCHES specifies the `ls' options used.
-\(Interactively, use a prefix argument to be able to specify SWITCHES.)
+Optional second argument SWITCHES specifies the options to be used
+when invoking `insert-directory-program', usually `ls', which produces
+the listing of the directory files and their attributes.
+Interactively, a prefix argument will cause the command to prompt
+for SWITCHES.
 
 If DIRNAME is a string, Dired displays a list of files in DIRNAME (which
 may also have shell wildcards appended to select certain files).
diff --git a/lisp/files.el b/lisp/files.el
index 5fa38e46af..d8e7989672 100644
--- a/lisp/files.el
+++ b/lisp/files.el
@@ -7236,7 +7236,9 @@ need to be passed verbatim to shell commands."
 
 
 (defvar insert-directory-program (purecopy "ls")
-  "Absolute or relative name of the `ls' program used by `insert-directory'.")
+  "Absolute or relative name of the `ls'-like program.
+This is used by `insert-directory' and `dired-insert-directory'
+\(thus, also by `dired').")
 
 (defcustom directory-free-space-program (purecopy "df")
   "Program to get the amount of free space on a file system.