From garys@opusnet.com  Wed Aug 10 15:37:18 2005
Return-Path: <garys@opusnet.com>
Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125])
	by hub.freebsd.org (Postfix) with ESMTP id 9AECF16A41F
	for <FreeBSD-gnats-submit@freebsd.org>; Wed, 10 Aug 2005 15:37:18 +0000 (GMT)
	(envelope-from garys@opusnet.com)
Received: from opusnet.com (mail.opusnet.com [209.210.200.6])
	by mx1.FreeBSD.org (Postfix) with ESMTP id EC00F43D5A
	for <FreeBSD-gnats-submit@freebsd.org>; Wed, 10 Aug 2005 15:37:17 +0000 (GMT)
	(envelope-from garys@opusnet.com)
Received: from localhost.localhost [70.98.246.232] by opusnet.com with ESMTP
  (SMTPD32-8.05) id AF2CA1580150; Wed, 10 Aug 2005 08:37:16 -0700
Received: from localhost.localhost (localhost.localhost [127.0.0.1])
	by localhost.localhost (8.13.3/8.13.3) with ESMTP id j7AFdecE081225
	for <FreeBSD-gnats-submit@freebsd.org>; Wed, 10 Aug 2005 08:39:40 -0700 (PDT)
	(envelope-from garys@opusnet.com)
Received: (from jojo@localhost)
	by localhost.localhost (8.13.3/8.13.3/Submit) id j7AFdZps081224;
	Wed, 10 Aug 2005 08:39:35 -0700 (PDT)
	(envelope-from garys@opusnet.com)
Message-Id: <45br45iyx4.r45@mail.opusnet.com>
Date: Wed, 10 Aug 2005 08:39:35 -0700
From: "Gary W. Swearingen" <garys@opusnet.com>
Reply-To: garys@opusnet.com
To: FreeBSD-gnats-submit@freebsd.org
Subject: [patch] ls(1) manpage doesn't describe block handling well
X-GNATS-Notify:

>Number:         84765
>Category:       docs
>Synopsis:       [patch] ls(1) manpage doesn't describe block handling well
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    garys
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Wed Aug 10 15:40:18 GMT 2005
>Closed-Date:    Wed Sep 07 17:50:55 GMT 2005
>Last-Modified:  Wed Sep 07 17:50:55 GMT 2005
>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:
State-Changed-From-To: open->analyzed 
State-Changed-By: garys 
State-Changed-When: Sun Aug 28 20:32:20 GMT 2005 
State-Changed-Why:  
PR came with my patch. 


Responsible-Changed-From-To: freebsd-doc->garys 
Responsible-Changed-By: garys 
Responsible-Changed-When: Sun Aug 28 20:32:20 GMT 2005 
Responsible-Changed-Why:  
I'll handle PR, with mentor. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=84765 

From: Giorgos Keramidas <keramida@freebsd.org>
To: "Gary W. Swearingen" <garys@opusnet.com>
Cc: bug-followup@freebsd.org
Subject: Re: docs/84765: [patch] ls(1) manpage doesn't describe block handling well
Date: Tue, 30 Aug 2005 15:19:33 +0300

 On 2005-08-28 15:00, "Gary W. Swearingen" <garys@opusnet.com> wrote:
 > Well, I've done a little with gnats.  I hanged several times while
 > editing in vi.  I switched to emacs and I hanged once when exiting,
 > but the PR looked OK.
 >
 > Here's an new-and-improved patch for your approval (or anyone's
 > comment):
 
 Just a minor comment below.
 
 > --- ls..orig.1	Sun Aug  7 12:24:22 2005
 > +++ ls.1	Sun Aug 28 14:50:54 2005
 > @@ -337,6 +320,26 @@
 >  linked-to file is preceded by
 >  .Dq Li -> .
 >  .Pp
 > +If a file is a directory (and
 
 "a file is a directory" sounds a bit confusing.  I'm not sure how we can
 write this in a way that avoids confusion and still retains the original
 spirit of BSD UNIX that "directories are just special files".  Perhaps
 something like this?
 
 	If one of the listed directory entries is a directory itself ...
 

From: garys@opusnet.com (Gary W. Swearingen)
To: Giorgos Keramidas <keramida@freebsd.org>
Cc: bug-followup@freebsd.org
Subject: Re: docs/84765: [patch] ls(1) manpage doesn't describe block
 handling well
Date: Tue, 30 Aug 2005 08:40:56 -0700

 Giorgos Keramidas <keramida@freebsd.org> writes:
 
 >> +If a file is a directory (and
 >
 > "a file is a directory" sounds a bit confusing.  I'm not sure how we can
 > write this in a way that avoids confusion and still retains the original
 > spirit of BSD UNIX that "directories are just special files".  Perhaps
 > something like this?
 >
 > 	If one of the listed directory entries is a directory itself ...
 
 Yeah, I worried about that one too.  The next (pre-existing) para
 talks about the type of file being Directory, FIFO, etc.  Your
 alternative is a bit long.
 
 
 I think the meaning remains if I simply rm the nastiness and repair grammar.
 From:
     If a file is a directory (and
     .Fl d
     is not used), the listing of the directory's contents is preceeded
 to:
     The listing of a directory's contents is preceeded.
 
 OK?  Here is part of my private PR file that my CVS tool works from.
 Let me know which parts of this you want to see in the future.  I can
 omit any of: the XMLish lines; the repo; the branch; the commit_msg,
 if you'd like.
 
 
 <----------------------------------------------provisional_repository>
 src
 </---------------------------------------------provisional_repository>
 <---------------------------------------------provisional_repo_branch>
 HEAD
 </--------------------------------------------provisional_repo_branch>
 <----------------------------------------------provisional_commit_msg>
 Improved descriptions of block size handling.
 
 PR:             docs/84765
 Submitted by:   garys
 Approved by:    keramida
 MFC after:      3 days
 </---------------------------------------------provisional_commit_msg>
 <-----------------------------------------------provisional_file_list>
 src/bin/ls/ls.1
 </----------------------------------------------provisional_file_list>
 <----------------------------------------------provisional_file_patch>
 --- ls..orig.1	Sun Aug  7 12:24:22 2005
 +++ ls.1	Tue Aug 30 08:19:31 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 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,12 @@
  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 blocks used in the file system by each file.
 +Block sizes and directory totals are handled as decribed in
 +.Sx The Long Format
 +subsection below, except (if the long format is not also requested)
 +the directory totals are not output when the output is in a
 +single column, even if multi-column output is requested.
  .It Fl t
  Sort by time modified (most recently modified
  first) before sorting the operands by lexicographical
 @@ -315,10 +302,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 +320,24 @@
  linked-to file is preceded by
  .Dq Li -> .
  .Pp
 +The listing of a directory's contents is preceeded
 +by a labeled total number of blocks used in the file system by the files
 +which are 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.
 +The block size may be set with option
 +.Fl k
 +or environment variable
 +.Ev BLOCKSIZE .
 +Numbers of blocks in the output will have been rounded up so the
 +numbers of bytes is at least as many as 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 +461,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 +679,10 @@
  .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 might be a feature that was
 +based on the fact that single-column output
 +usually goes to something other than a terminal.
 +It is debatable whether this is a design bug.
 </---------------------------------------------provisional_file_patch>
State-Changed-From-To: analyzed->patched 
State-Changed-By: garys 
State-Changed-When: Wed Aug 31 18:04:26 GMT 2005 
State-Changed-Why:  
Committed to HEAD only. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=84765 
State-Changed-From-To: patched->closed 
State-Changed-By: garys 
State-Changed-When: Wed Sep 7 17:49:53 GMT 2005 
State-Changed-Why:  
Patched in HEAD, RELENG_6, RELENG_5. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=84765 
>Unformatted:
