docs/84765: [patch] ls(1) manpage doesn't describe block handling well

[Gary W. Swearingen]

>Number:         84765
>Category:       docs
>Synopsis:       [patch] ls(1) manpage doesn't describe block handling well
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Wed Aug 10 15:40:18 GMT 2005
>Closed-Date:
>Last-Modified:
>Originator:     Gary W. Swearingen
>Release:        FreeBSD 5.4-RELEASE i386
>Organization:
none
>Environment:
n/a
>Description:

The ls(1) manpage doesn't describe block handling well.
Pieces of the block size discussion are scattered around.
The "total blocks" sometimes output by the -l and -s
options is not described completely.

>How-To-Repeat:
n/a

>Fix:

I put the main discussion of both issues in the "The Long Format"
section, and made the -l, -s, and BLOCKSIZE descriptions reference
the main discussion, mostly.


--- ls..orig.1	Sun Aug  7 12:24:22 2005
+++ ls.1	Sun Aug  7 16:58:50 2005
@@ -176,29 +176,17 @@
 .It Fl i
 For each file, print the file's file serial number (inode number).
 .It Fl k
-If the
-.Fl s
-option is specified, print the file size allocation in kilobytes,
-not blocks.
-This option overrides the environment variable
-.Ev BLOCKSIZE .
-Note that
-.Fl k
-is mutually exclusive to
-.Fl h ,
-and later
-.Fl k
-will nullify earlier
-.Fl h .
+This has the same effect as setting the environment variable
+.Ev BLOCKSIZE
+to 1024, except that it also nullifies any
+.Fl h
+options to its left.
 .It Fl l
 (The lowercase letter
 .Dq ell . )
-List in long format.
-(See below.)
-A total sum (in blocks, see the
-.Fl s
-option for the block size unit) for all the file
-sizes is output on a line before the long listing.
+List files in the long format, as described in the
+.Sx The Long Format
+subsection below.
 .It Fl m
 Stream output format; list files across the page, separated by commas.
 .It Fl n
@@ -223,13 +211,11 @@
 Reverse the order of the sort to get reverse
 lexicographical order or the oldest entries first.
 .It Fl s
-Display the number of file system blocks actually used by each file, in units
-of 512 bytes, where partial units are rounded up to the next integer value.
-A total sum for all the file
-sizes is output on a line before the listing.
-The environment variable
-.Ev BLOCKSIZE
-overrides the unit size of 512 bytes.
+Display the number of file system blocks used by each file.
+Block sizes and directory totals are handled as decribed in
+.Sx The Long Format
+subsection below, except (for unknown reasons) the directory totals
+are only output with multi-column outputs.
 .It Fl t
 Sort by time modified (most recently modified
 first) before sorting the operands by lexicographical
@@ -315,10 +301,6 @@
 month, day-of-month file was last modified,
 hour file last modified, minute file last
 modified, and the pathname.
-In addition, for each directory whose contents are displayed, the total
-number of 512-byte blocks used by the files in the directory is displayed
-on a line by itself immediately before the information for the files in the
-directory.
 .Pp
 If the modification time of the file is more than 6 months
 in the past or future, then the year of the last modification
@@ -337,6 +319,26 @@
 linked-to file is preceded by
 .Dq Li -> .
 .Pp
+If a file is a directory (and
+.Fl d
+is not used), the listing of the directory's contents is preceeded
+by a labeled total number of file system blocks used by the files
+listed as the directory's contents (which may or may not include
+.Pa \&.
+and
+.Pa ..
+and other files which start with a dot, depending on other options).
+.Pp
+The default block size is 512 bytes.
+It may be set with the
+.Fl k
+option or the
+.Ev BLOCKSIZE
+environment variable.
+Output numbers of blocks will have been rounded up so the number of bytes
+is at least as many as is used by the corresponding file system blocks
+which might have a different size.
+.Pp
 The file mode printed under the
 .Fl l
 option consists of the
@@ -460,12 +462,15 @@
 .Nm :
 .Bl -tag -width ".Ev CLICOLOR_FORCE"
 .It Ev BLOCKSIZE
-If the environment variable
-.Ev BLOCKSIZE
-is set, the block counts
-(see
-.Fl s )
-will be displayed in units of that size block.
+If this is set, its value, rounded up to 512 or down to a
+multiple of 512, will be used as the block size in bytes by the
+.Fl l
+and
+.Fl s
+options.
+See
+.Sx The Long Format
+subsection for more information.
 .It Ev CLICOLOR
 Use
 .Tn ANSI
@@ -675,3 +680,7 @@
 .Sh BUGS
 To maintain backward compatibility, the relationships between the many
 options are quite complex.
+.Pp
+The exception mentioned in the
+.Fl s
+option description is probably a bug.
>Release-Note:
>Audit-Trail:
>Unformatted: