[src/trunk]: src/bin/ls PR/47167

[abs <abs%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/9c3a10ea8270
branches:  trunk
changeset: 782786:9c3a10ea8270
user:      abs <abs%NetBSD.org@localhost>
date:      Tue Nov 20 12:37:29 2012 +0000

description:
PR/47167
ls.1:
- Sort options in `SYNOPSIS', the option list, and texts within
  the man page;
- improve wording;
- improve macro usage;
- use more consistency regarding (locations for) information about
  which options override which;
- cross-reference `-d' and `-R';
- simplify description of `-k', removing redundant and unneeded
  information;
- sort entry type list (but leave `-a' and `-A' as they are, given
  their meaning);
- correct / augment description of `BLOCKSIZE' environment variable
  in `ENVIRONMENT' section;
- bump date.

ls.c:
- Sort options in `usage';
- augment comment about when to figure out block size.

diffstat:

 bin/ls/ls.1 |  103 ++++++++++++++++++++++++++++-------------------------------
 bin/ls/ls.c |    8 ++--
 2 files changed, 53 insertions(+), 58 deletions(-)

diffs (283 lines):

diff -r b6cda4bfc0a6 -r 9c3a10ea8270 bin/ls/ls.1
--- a/bin/ls/ls.1       Tue Nov 20 11:06:27 2012 +0000
+++ b/bin/ls/ls.1       Tue Nov 20 12:37:29 2012 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: ls.1,v 1.71 2012/10/21 08:18:27 wiz Exp $
+.\"    $NetBSD: ls.1,v 1.72 2012/11/20 12:37:29 abs Exp $
 .\"
 .\" Copyright (c) 1980, 1990, 1991, 1993, 1994
 .\"    The Regents of the University of California.  All rights reserved.
@@ -32,7 +32,7 @@
 .\"
 .\"     @(#)ls.1       8.7 (Berkeley) 7/29/94
 .\"
-.Dd April 2, 2011
+.Dd November 20, 2012
 .Dt LS 1
 .Os
 .Sh NAME
@@ -40,19 +40,19 @@
 .Nd list directory contents
 .Sh SYNOPSIS
 .Nm
-.Op Fl AaBbCcdFfghikLlMmnopqRrSsTtuWwx1
+.Op Fl 1AaBbCcdFfghikLlMmnopqRrSsTtuWwx
 .Op Ar
 .Sh DESCRIPTION
-For each operand that names a
+For each
 .Ar file
-of a type other than
+operand that names a file of a type other than
 directory,
 .Nm
 displays its name as well as any requested,
 associated information.
-For each operand that names a
+For each
 .Ar file
-of type directory,
+operand that names a file of type directory,
 .Nm
 displays the names of files contained
 within that directory, as well as any requested, associated
@@ -67,6 +67,11 @@
 .Pp
 The following options are available:
 .Bl -tag -width indent
+.It Fl \&1
+(The numeric digit
+.Dq one ) .
+Force output to be one entry per line.
+This is the default when output is not to a terminal.
 .It Fl A
 List all entries except for
 .Ql \&.
@@ -88,13 +93,18 @@
 Force multi-column output; this is the default when output is to a terminal.
 .It Fl c
 Use time when file status was last changed,
-instead of time of last modification of the file for sorting
-.Pq Fl t
-or printing
-.Pq Fl l .
+instead of time of last modification of the file for printing
+.Pq Fl l
+or sorting
+.Pq Fl t .
+Overrides
+.Fl u .
 .It Fl d
 Directories are listed as plain files (not searched recursively) and
 symbolic links in the argument list are not followed.
+Turns off
+.Fl R
+if also given.
 .It Fl F
 Display a slash
 .Pq Sq \&/
@@ -123,9 +133,9 @@
 except that the owner is not printed.
 .It Fl h
 Modifies the
-.Fl s
+.Fl l
 and
-.Fl l
+.Fl s
 options, causing the sizes to be reported in bytes displayed in a human
 readable format.
 Overrides
@@ -138,15 +148,8 @@
 Modifies the
 .Fl s
 option, causing the sizes to be reported in kilobytes.
-The rightmost of the
-.Fl k
-and
-.Fl h
-flags overrides the previous flag.
-See also
-.Fl h
-and
-.Fl M .
+Overrides
+.Fl h .
 .It Fl L
 For each file, if it's a link, evaluate file information and file type
 of the referenced file and not the link itself; however still print
@@ -169,8 +172,8 @@
 commas (or a locale appropriate separator) resulting in a more readable
 output.
 Overrides
-.Fl h .
-Does not override
+.Fl h ;
+does not override
 .Fl k .
 .It Fl m
 Stream output format; list files across the page, separated by commas.
@@ -201,6 +204,8 @@
 this is the default when output is to a terminal.
 .It Fl R
 Recursively list subdirectories encountered.
+See also
+.Fl d .
 .It Fl r
 Reverse the order of the sort to get reverse
 lexicographical order or the smallest or oldest entries first.
@@ -230,10 +235,12 @@
 .It Fl u
 Use time of last access,
 instead of last modification
-of the file for sorting
-.Pq Fl t
-or printing
-.Pq Fl l .
+of the file for printing
+.Pq Fl l
+or sorting
+.Pq Fl t .
+Overrides
+.Fl c .
 .It Fl W
 Display whiteouts when scanning directories.
 .It Fl w
@@ -241,19 +248,14 @@
 This is the default when output is not to a terminal.
 .It Fl x
 Multi-column output sorted across the page rather than down the page.
-.It Fl \&1
-(The numeric digit
-.Dq one ) .
-Force output to be one entry per line.
-This is the default when output is not to a terminal.
 .El
 .Pp
 The
 .Fl B ,
 .Fl b ,
-.Fl w ,
+.Fl q ,
 and
-.Fl q
+.Fl w
 options all override each other; the last one specified determines
 the format used for non-printable characters.
 .Pp
@@ -278,13 +280,6 @@
 .Fl g
 was specified last.
 .Pp
-The
-.Fl c
-and
-.Fl u
-options override each other; the last one specified determines
-the file time used.
-.Pp
 By default,
 .Nm
 lists one entry per line to standard
@@ -296,11 +291,11 @@
 .Pp
 File information is displayed with one or more
 .Aq blank
-separating the information associated with the
+characters separating the information associated with the
 .Fl i ,
-.Fl s ,
+.Fl l ,
 and
-.Fl l
+.Fl s
 options.
 .Ss The Long Format
 If the
@@ -333,7 +328,7 @@
 .El
 .Pp
 In addition, for each directory whose contents are displayed, the total
-number of blocks in units of 512 bytes or
+number of file system blocks in units of 512 bytes or
 .Ev BLOCKSIZE
 (see
 .Sx ENVIRONMENT )
@@ -361,6 +356,8 @@
 follows:
 .Pp
 .Bl -tag -width 4n -offset indent -compact
+.It Sy \-
+Regular file.
 .It Sy a
 Archive state 1.
 .It Sy A
@@ -373,14 +370,12 @@
 Directory.
 .It Sy l
 Symbolic link.
-.It Sy s
-Socket link.
 .It Sy p
 FIFO.
+.It Sy s
+Socket link.
 .It Sy w
 Whiteout.
-.It Sy \-
-Regular file.
 .El
 .Pp
 The next three fields
@@ -460,11 +455,11 @@
 If the environment variable
 .Ev BLOCKSIZE
 is set, and the
-.Fl h
+.Fl k
+option is not specified, the block counts
+(see
+.Fl l
 and
-.Fl k
-options are not specified, the block counts
-(see
 .Fl s )
 will be displayed in units of that size block.
 .It Ev COLUMNS
diff -r b6cda4bfc0a6 -r 9c3a10ea8270 bin/ls/ls.c
--- a/bin/ls/ls.c       Tue Nov 20 11:06:27 2012 +0000
+++ b/bin/ls/ls.c       Tue Nov 20 12:37:29 2012 +0000
@@ -1,4 +1,4 @@
-/*     $NetBSD: ls.c,v 1.69 2011/08/29 14:44:21 joerg Exp $    */
+/*     $NetBSD: ls.c,v 1.70 2012/11/20 12:37:29 abs Exp $      */
 
 /*
  * Copyright (c) 1989, 1993, 1994
@@ -42,7 +42,7 @@
 #if 0
 static char sccsid[] = "@(#)ls.c       8.7 (Berkeley) 8/5/94";
 #else
-__RCSID("$NetBSD: ls.c,v 1.69 2011/08/29 14:44:21 joerg Exp $");
+__RCSID("$NetBSD: ls.c,v 1.70 2012/11/20 12:37:29 abs Exp $");
 #endif
 #endif /* not lint */
 
@@ -117,7 +117,7 @@
 {
 
        (void)fprintf(stderr,
-           "usage: %s [-AaBbCcdFfghikLlMmnopqRrSsTtuWwx1] [file ...]\n",
+           "usage: %s [-1AaBbCcdFfghikLlMmnopqRrSsTtuWwx] [file ...]\n",
            getprogname());
        exit(EXIT_FAILURE);
        /* NOTREACHED */
@@ -331,7 +331,7 @@
                fts_options |= FTS_WHITEOUT;
 #endif
 
-       /* If -l or -s, figure out block size. */
+       /* If -i, -l, or -s, figure out block size. */
        if (f_inode || f_longform || f_size) {
                if (!kflag)
                        (void)getbsize(NULL, &blocksize);