From 9290066de069ce5ffdc6e8ea531ba14a72d36e3f Mon Sep 17 00:00:00 2001
From: Paul Eggert <eggert@cs.ucla.edu>
Date: Fri, 24 May 2024 08:42:14 -0700
Subject: [PATCH] ls: improve sorting doc

Problem reported by Dan Jaobson (Bug#71171).
* doc/coreutils.texi: Clarify that directory entries are sorted,
not command-line arguments.
* src/ls.c (usage): Be less chatty about -U and
about --group-directories-first.
---
 doc/coreutils.texi | 40 ++++++++++++++++++++++------------------
 src/ls.c           |  7 ++-----
 2 files changed, 24 insertions(+), 23 deletions(-)

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 3762c6f96..1fa7f79ad 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -7640,7 +7640,8 @@ non-option argument is specified, @command{ls} operates on the current
 directory, acting as if it had been invoked with a single argument of @samp{.}.
 
 @vindex LC_ALL
-By default, the output is sorted alphabetically, according to the locale
+By default, @command{ls} lists each directory's contents alphabetically,
+according to the locale
 settings in effect.@footnote{If you use a non-POSIX
 locale (e.g., by setting @env{LC_ALL} to @samp{en_US}), then @command{ls} may
 produce output that is sorted differently than you're accustomed to.
@@ -7747,16 +7748,6 @@ or any of the following options is in effect:
 @option{--dereference} (@option{-L}), or
 @option{--dereference-command-line} (@option{-H})).
 
-@item --group-directories-first
-@opindex --group-directories-first
-Group all the directories before the files and then sort the
-directories and the files separately using the selected sort key
-(see @option{--sort} option).
-That is, this option specifies a primary sort key,
-and the @option{--sort} option specifies a secondary key.
-However, any use of @option{--sort=none}
-(@option{-U}) disables this option altogether.
-
 @item --hide=PATTERN
 @opindex --hide=@var{pattern}
 In directories, ignore files whose names match the shell pattern
@@ -8137,9 +8128,12 @@ In long format, print the security context to the left of the size column.
 @subsection Sorting the output
 
 @cindex sorting @command{ls} output
-These options change the order in which @command{ls} sorts the information
-it outputs.  By default, sorting is done by character code
-(e.g., ASCII order).
+@vindex LC_COLLATE
+These options change the order in which @command{ls} outputs
+information for the files in a directory.
+(Command-line operands are always processed left to right.)
+By default, files are sorted alphabetically by name, using the
+character collating sequence specified by the @env{LC_COLLATE} locale.
 
 @table @samp
 
@@ -8160,9 +8154,19 @@ sort according to the ctime.  @xref{File timestamps}.
 @opindex -f
 @cindex unsorted directory listing
 @cindex directory order, listing by
-Produce an unsorted listing of all directory entries.
-This is like @option{--all} (@option{-a}) combined
-with @option{--sort=none} (@option{-U}).
+Do not sort, and list all files.
+This is like @option{--sort=none} (@option{-U}) combined
+with @option{--all} (@option{-a}).
+
+@item --group-directories-first
+@opindex --group-directories-first
+When listing a directory's files,
+group all subdirectories before non-directories
+and then sort the subdirectories and the non-directories separately.
+That is, this option specifies a primary sort key,
+and the other sorting options specify a secondary key.
+However, any use of @option{--sort=none}
+(@option{-U}) disables this option altogether.
 
 @item -r
 @itemx --reverse
@@ -8401,7 +8405,7 @@ Specifying @option{--hyperlink} and no @var{when} is equivalent to
 
 @item --indicator-style=@var{word}
 @opindex --indicator-style
-Append a character indicator with style @var{word} to entry names,
+Append a character indicator with style @var{word} to file names,
 as follows:
 
 @table @samp
diff --git a/src/ls.c b/src/ls.c
index 916d7c050..5e2f7c3e7 100644
--- a/src/ls.c
+++ b/src/ls.c
@@ -5478,10 +5478,7 @@ Sort entries alphabetically if none of -cftuvSUX nor --sort is specified.\n\
 "), stdout);
       fputs (_("\
       --group-directories-first\n\
-                             group directories before files;\n\
-                             can be augmented with a --sort option, but any\n\
-                             use of --sort=none (-U) disables grouping\n\
-\n\
+                             group directories before files\n\
 "), stdout);
       fputs (_("\
   -G, --no-group             in a long listing, don't print group names\n\
@@ -5605,7 +5602,7 @@ Sort entries alphabetically if none of -cftuvSUX nor --sort is specified.\n\
 \n\
 "), stdout);
       fputs (_("\
-  -U                         do not sort; list entries in directory order\n\
+  -U                         do not sort directory entries\n\
 "), stdout);
       fputs (_("\
   -v                         natural sort of (version) numbers within text\n\
-- 
2.43.0