On 7/28/21 4:57 AM, Pádraig Brady wrote:
I see --zero implies --format=single-column, but allows --format=long.
That's the right default, but also most flexible.
Yes, it's a little tricky here.
For quite some time the ls -1 (digit 1 option) code has disagreed with
its documentation. The doc said '-1' is equivalent to
'--format=single-column', but the code makes '-l -1' equivalent to '-l'
whereas '-l --format=single-column' is equivalent to no option at all.
I see three possible fixes here:
1. Change the doc to match the code, i.e., change the documentation to
say that -1 is not the same thing as --format=single-column.
2. Change the code so that --format=single-column also has no effect
after -l, and change the doc to document this.
3. Change the code to match the doc.
(3) would not conform to POSIX, so that's out. (1) is less work for us
and does not affect existing uses, so I installed the first attached
patch to implement (1). This first patch also cleans up a bunch of other
documentation cruft that I noticed in the 'ls' documentation. The second
patch updates up some old-fashioned terminology I noticed while working
on the first patch.
You could talk me into (2), I suppose
From dd6591b20e0841e5aecaa082bac1f959a5e18f9c Mon Sep 17 00:00:00 2001
From: Paul Eggert
Date: Wed, 28 Jul 2021 11:26:48 -0700
Subject: [PATCH 1/2] doc: improve ls documentation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
* doc/coreutils.texi (ls invocation): Document implementation more
closely. Be more consistent about style. Omit some needless words.
* src/ls.c (usage): Don’t overdocument -f, as the details were wrong.
Omit -1 advice as it’s a bit obsolete now that we have --zero and
is a bit much for --usage output anyway.
---
doc/coreutils.texi | 173 -
src/ls.c | 15 ++--
2 files changed, 99 insertions(+), 89 deletions(-)
diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 2d2770864..64cadf634 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -7350,7 +7350,8 @@ and @command{vdir}, which list information about files.
The @command{ls} program lists information about files (of any type,
including directories). Options and file arguments can be intermixed
-arbitrarily, as usual.
+arbitrarily, as usual. Later options override earlier options that
+are incompatible.
For non-option command-line arguments that are directories, by default
@command{ls} lists the contents of directories, not recursively, and
@@ -7460,10 +7461,10 @@ Do not dereference symbolic links, with one exception:
if a command line argument specifies a symbolic link that refers to
a directory, show information for that directory rather than for the
link itself.
-This is the default behavior when no other dereferencing-related
-option has been specified (@option{--classify} (@option{-F}),
+This is the default behavior unless long format is being used
+or any of the following options is in effect:
+@option{--classify} (@option{-F}),
@option{--directory} (@option{-d}),
-(@option{-l}),
@option{--dereference} (@option{-L}), or
@option{--dereference-command-line} (@option{-H})).
@@ -7541,7 +7542,7 @@ default, only file names are shown.
@item --author
@opindex --author
@cindex hurd, author, printing
-List each file's author when producing long format directory listings.
+In long format, list each file's author.
In GNU/Hurd, file authors can differ from their owners, but in other
operating systems the two are the same.
@@ -7550,8 +7551,7 @@ operating systems the two are the same.
@opindex -D
@opindex --dired
@cindex dired Emacs mode support
-With the long listing (@option{-l}) format, print an additional line after
-the main output:
+Print an additional line after the main output:
@example
//DIRED// @var{beg1} @var{end1} @var{beg2} @var{end2} @dots{}
@@ -7563,7 +7563,8 @@ byte position of the beginning and end of each file name in the output.
This makes it easy for Emacs to find the names, even when they contain
unusual characters such as space or newline, without fancy searching.
-If directories are being listed recursively (@option{-R}), output a similar
+If directories are being listed recursively via
+@option{--recursive} (@option{-R}), output a similar
line with offsets for each subdirectory name:
@example
@@ -7608,7 +7609,7 @@ $ ls -gloRF --dired a
//DIRED-OPTIONS// --quoting-style=literal
@end example
-Note that the pairs of offsets on the @samp{//DIRED//} line above delimit
+The pairs of offsets on the @samp{//DIRED//} line above delimit
these names: @file{f1}, @file{f2}, @file{sub}, @file{sub2}, @file{deeper},
@file{file}.
The offsets on the @samp{//SUBDIRED//} line delimit the following
@@ -7623,11 +7624,12 @@ $ dd bs=1 skip=222 count=6 < out 2>/dev/null; echo
deeper
@end example
-Note that although the listing above includes a trailing slash
+Although the listing
