emacs-29 97b8ac376b5 1/2: Fix the effects and documentation of 'dired-free-space'

[Eli Zaretskii]

branch: emacs-29
commit 97b8ac376b55ad48a8e66e9ab3975f81bc8cbfab
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    Fix the effects and documentation of 'dired-free-space'
    
    * lisp/dired.el (dired-free-space): Fix doc string and Custom tags.
    (dired--insert-disk-space): When 'dired-free-space' is 'separate',
    return the position of the beginning of the disk-space line, to be
    compatible with pre-Emacs 29 behavior under
    'dired-hide-details-mode'.  (Bug#65186)
    
    * doc/emacs/dired.texi (Misc Dired Features): Fix wording in
    documentation of 'dired-free-space'.
---
 doc/emacs/dired.texi | 17 +++++++++++------
 lisp/dired.el        | 24 ++++++++++++++++--------
 2 files changed, 27 insertions(+), 14 deletions(-)

diff --git a/doc/emacs/dired.texi b/doc/emacs/dired.texi
index 77c4e09c826..c20c221cd78 100644
--- a/doc/emacs/dired.texi
+++ b/doc/emacs/dired.texi
@@ -1726,12 +1726,17 @@ rotation is lossless, and uses an external utility 
called
 @section Other Dired Features
 
 @vindex dired-free-space
-  By default, Dired will display the available space on the disk in
-the first line.  This is the @code{first} value of the
-@code{dired-free-space} variable.  If you set this to
-@code{separate} instead, Dired will display this on a separate line
-(including the space the files in the current directory takes).  If
-you set this to @code{nil}, the free space isn't displayed at all.
+  By default, Dired displays the available space on the directory's
+disk on the first line of that directory listing, following the
+directory name.  You can control this display by customizing the
+variable @code{dired-free-space}.  Its default value is @code{first},
+which produces the available space after the directory name.  If you
+customize it to the value @code{separate} instead, Dired will display
+the disk space information on a separate line, following the line with
+the directory name, and will include in that line the space used by
+the files in the current directory as well as the available disk
+space.  If you set this to @code{nil}, the available disk space
+information will not be displayed at all.
 
 @kindex + @r{(Dired)}
 @findex dired-create-directory
diff --git a/lisp/dired.el b/lisp/dired.el
index d0af05d68f0..4c2e9243e6c 100644
--- a/lisp/dired.el
+++ b/lisp/dired.el
@@ -218,14 +218,19 @@ If t, they are marked if and as the files linked to were 
marked.
 If a character, new links are unconditionally marked with that character.")
 
 (defcustom dired-free-space 'first
-  "Whether and how to display the amount of free disk space in Dired buffers.
+  "Whether and how to display the disk space usage info in Dired buffers.
 If nil, don't display.
-If `separate', display on a separate line (along with used count).
-If `first', display only the free disk space on the first line,
-following the directory name."
-  :type '(choice (const :tag "On a separate line" separate)
-                 (const :tag "On the first line, after directory name" first)
-                 (const :tag "Don't display" nil))
+If `separate', display on a separate line, and include both the used
+and the free disk space.
+If `first', the default, display only the free disk space on the first
+line, following the directory name."
+  :type '(choice (const
+                  :tag
+                  "On separate line, display both used and free space" 
separate)
+                 (const
+                  :tag
+                  "On first line, after directory name, display only free 
space" first)
+                 (const :tag "Don't display disk space usage" nil))
   :version "29.1"
   :group 'dired)
 
@@ -1769,7 +1774,10 @@ see `dired-use-ls-dired' for more details.")
          ((eq dired-free-space 'separate)
          (end-of-line)
          (insert " available " available)
-          (forward-line 1)
+          ;; The separate free-space line is considered part of the
+          ;; directory content, for the purposes of
+          ;; 'dired-hide-details-mode'.
+          (beginning-of-line)
           (point))
          ((eq dired-free-space 'first)
           (goto-char beg)