Thanks, I installed the attached. This doesn't exactly match your
suggestion (as ls --help shouldn't be that chatty) but should address
the issues you raised. Some of those issues had already been fixed in
the development branch.From 9290066de069ce5ffdc6e8ea531ba14a72d36e3f Mon Sep 17 00:00:00 2001
From: Paul Eggert <egg...@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
