[9front] man du -s correction diff

[9front] man du -s correction diff

[Kyle Milz]

[-- Attachment #1: du_s.diff --]
[-- Type: text/plain, Size: 424 bytes --]

hi,

the description in the manual for du -s looks just plain wrong.
by itself du -s only prints values for the top level.


kyle

diff ca73f673473457152d6f1b2e9030495f8dec5c49 uncommitted
--- a/sys/man/1/du
+++ b/sys/man/1/du
@@ -73,9 +73,7 @@
 .B -s
 option causes
 .I du
-to descend the hierarchy as always, but to print only a summary line
-for each
-.IR file .
+to only print values for the top level.
 .PP
 The
 .B -e

Re: [9front] man du -s correction diff

[umbraticus]

I think you should at least try to keep the word “summary”
in there, since I assume the flag is a mnemonic for that…

umbraticus

Re: [9front] man du -s correction diff

[Xiao-Yong Jin]

> On Nov 1, 2021, at 5:46 PM, Kyle Milz <krwmilz@gmail.com> wrote:
> 
> hi,
> 
> the description in the manual for du -s looks just plain wrong.
> by itself du -s only prints values for the top level.
> 
> 
> kyle
> 
> diff ca73f673473457152d6f1b2e9030495f8dec5c49 uncommitted
> --- a/sys/man/1/du
> +++ b/sys/man/1/du
> @@ -73,9 +73,7 @@
>  .B -s
>  option causes
>  .I du
> -to descend the hierarchy as always, but to print only a summary line
> -for each
> -.IR file .
> +to only print values for the top level.
>  .PP
>  The
>  .B -e

"file" here refers to the synopsis

du [ -aefhnqstu ] [ -b size ] [ -p SI-prefix ] [ file ... ]

Re: [9front] man du -s correction diff

[hiro]

On 11/1/21, Kyle Milz <krwmilz@gmail.com> wrote:
> hi,
>
> the description in the manual for du -s looks just plain wrong.
> by itself du -s only prints values for the top level.

you can add more files to your argument list.
by itself (du -s) the file is implied to be the current directory.

Re: [9front] man du -s correction diff

[Eckard Brauer]

Am Tue, 2 Nov 2021 10:30:08 +0100
schrieb hiro <23hiro@gmail.com>:

> On 11/1/21, Kyle Milz <krwmilz@gmail.com> wrote:
>  [...]
>
> you can add more files to your argument list.
> by itself (du -s) the file is implied to be the current directory.

correct. It prints summary/summaries for the directory/directories given
or the current directory if none is given as arg.

Re: [9front] man du -s correction diff

[Humm]

Quoth Kyle Milz:
>the description in the manual for du -s looks just plain wrong.
>by itself du -s only prints values for the top level.

The top level being each `file` argument, and the values being gotten 
by descending the hierarchy as always.

-- 
Humm

Re: [9front] man du -s correction diff

[Kyle Milz]

On Tue, Nov 02, 2021 at 12:39:17PM +1300, umbraticus@prosimetrum.com wrote:
> I think you should at least try to keep the word “summary”
> in there, since I assume the flag is a mnemonic for that…

after re-reading the diff today i finally understand what the original
description was: print a summary for each *specified* file.

i was confused and interpreted it as: descend the hierarchy as always
and print a summary for each hierarchy file.

i no longer think this diff is clearer.

> umbraticus

Re: [9front] man du -s correction diff

[ori]

Quoth Humm <hummsmith42@gmail.com>:
> Quoth Kyle Milz:
> >the description in the manual for du -s looks just plain wrong.
> >by itself du -s only prints values for the top level.
> 
> The top level being each `file` argument, and the values being gotten 
> by descending the hierarchy as always.
> 
> -- 
> Humm
> 

I agree that the current phrasing is a bit confusing.
What about "for each file" => "for each argument"?

Re: [9front] man du -s correction diff

[Kyle Milz]

On Tue, Nov 02, 2021 at 12:57:15PM -0400, ori@eigenstate.org wrote:
> Quoth Humm <hummsmith42@gmail.com>:
[...]
> > 
> > The top level being each `file` argument, and the values being gotten 
> > by descending the hierarchy as always.
> > 
> > -- 
> > Humm
> > 
> 
> I agree that the current phrasing is a bit confusing.
> What about "for each file" => "for each argument"?

given no markup this seems much better. however the original manual
marks up `file` with .IR, and when viewed with something that
displays that markup differently, it is obvious that `file` means
the final argument of du, as described in the synopsis.

Re: [9front] man du -s correction diff

[Eckard Brauer]

> I agree that the current phrasing is a bit confusing.
> What about "for each file" => "for each argument"?

"each non-option argument"? "-s" (and a few more) is an argument for
itself...

Re: [9front] man du -s correction diff

[hiro]

doesnt help when you dont supply an argument.
and if you do supply an argument, well folders are also files, so...

On 11/2/21, ori@eigenstate.org <ori@eigenstate.org> wrote:
> Quoth Humm <hummsmith42@gmail.com>:
>> Quoth Kyle Milz:
>> >the description in the manual for du -s looks just plain wrong.
>> >by itself du -s only prints values for the top level.
>>
>> The top level being each `file` argument, and the values being gotten
>> by descending the hierarchy as always.
>>
>> --
>> Humm
>>
>
> I agree that the current phrasing is a bit confusing.
> What about "for each file" => "for each argument"?
>
>

Re: [9front] man du -s correction diff

[ori]

Quoth Eckard Brauer <eckard.brauer@gmx.de>:
> > I agree that the current phrasing is a bit confusing.
> > What about "for each file" => "for each argument"?
> 
> "each non-option argument"? "-s" (and a few more) is an argument for
> itself...

A bunch of tweaks.

diff ca73f673473457152d6f1b2e9030495f8dec5c49 uncommitted
--- a//sys/man/1/du
+++ b//sys/man/1/du
@@ -35,60 +35,53 @@
 The count for a directory includes the counts of the
 contained files and directories.
 .PP
-The
+The following options are accepted:
+.TP
 .B -a
-option prints the number of blocks
-for every file in a directory.
+Print the number of blocks for every file in a directory.
 Normally counts are printed only for contained directories.
-.PP
-The
+.TP
 .B -f
-option suppresses the printing of warning messages.
-.PP
-The
+Suppresses the printing of warning messages.
+.TP
 .B -n
-option prints the size in bytes and the name of each file; it sets
+Print the size in bytes and the name of each file; it sets
 .BR -a .
-.PP
-The
+.TP
 .B -t
-option prints, in the format of
+Print, in the format of
 .B du
 .BR -n ,
-the modified time of
-each file rather than the size.
+the modified time of each file rather than the size.
 If the options
 .B -tu
 are specified then the accessed time is printed.
-.PP
-The
+.TP
 .B -q
-option prints, in the format of
+Print, in the format of
 .B du
 .BR -n ,
 the QID path of
 each file rather than the size.
-.PP
-The
+.TP
 .B -s
-option causes
+Causes
 .I du
 to descend the hierarchy as always, but to print only a summary line
 for each
-.IR file .
-.PP
-The
+.I file 
+argument.
+.TP
 .B -e
-option causes
+Causes
 .I du
 to print values (sizes, times or QID paths)
 in `scientific notation' via
 .IR print (2)'s
 .BR %g .
-.PP
-The
+.TP
 .B -h
-option causes
+Causes
 .I du
 to print values (sizes, times or QID paths)
 in scientific notation,
@@ -96,10 +89,9 @@
 (e.g.,
 .L G
 for binary gigabytes).
-.PP
-The
+.TP
 .B -p
-option causes
+Causes
 .I du
 to print values (sizes, times or QID paths)
 in units of
@@ -109,12 +101,6 @@
 An empty
 .IR SI-prefix
 corresponds to a scale factor of 1 (e.g., print sizes in bytes).
-.\" .PP
-.\" The
-.\" .B -r
-.\" option causes
-.\" .I du
-.\" to read and discard every byte of every file encountered.
 .SH EXAMPLES
 Print the size of
 .L /tmp

Re: [9front] man du -s correction diff

[Kyle Milz]

On Tue, Nov 02, 2021 at 03:38:10PM -0400, ori@eigenstate.org wrote:
> A bunch of tweaks.

looks like we almost wrote the same diff..

comments inline.

> diff ca73f673473457152d6f1b2e9030495f8dec5c49 uncommitted
> --- a//sys/man/1/du
> +++ b//sys/man/1/du
> @@ -35,60 +35,53 @@
>  The count for a directory includes the counts of the
>  contained files and directories.
>  .PP
> -The
> +The following options are accepted:
> +.TP
>  .B -a
> -option prints the number of blocks
> -for every file in a directory.
> +Print the number of blocks for every file in a directory.
>  Normally counts are printed only for contained directories.
> -.PP
> -The
> +.TP
>  .B -f
> -option suppresses the printing of warning messages.
> -.PP
> -The
> +Suppresses the printing of warning messages.

use present tense 'Supress' to match the other options?

> +.TP
>  .B -n
> -option prints the size in bytes and the name of each file; it sets
> +Print the size in bytes and the name of each file; it sets
>  .BR -a .
> -.PP
> -The
> +.TP
>  .B -t
> -option prints, in the format of
> +Print, in the format of
>  .B du
>  .BR -n ,
> -the modified time of
> -each file rather than the size.
> +the modified time of each file rather than the size.
>  If the options
>  .B -tu
>  are specified then the accessed time is printed.
> -.PP
> -The
> +.TP
>  .B -q
> -option prints, in the format of
> +Print, in the format of
>  .B du
>  .BR -n ,
>  the QID path of
>  each file rather than the size.
> -.PP
> -The
> +.TP
>  .B -s
> -option causes
> +Causes

i dont think 'Causes du to...' adds any value. i think we can assume the
reader knows that options are going to change a programs behavior.

>  .I du
>  to descend the hierarchy as always, but to print only a summary line
>  for each
> -.IR file .
> -.PP
> -The
> +.I file 
> +argument.
> +.TP

yes

>  .B -e
> -option causes
> +Causes

same as above

>  .I du
>  to print values (sizes, times or QID paths)
>  in `scientific notation' via
>  .IR print (2)'s
>  .BR %g .
> -.PP
> -The
> +.TP
>  .B -h
> -option causes
> +Causes

same as above

>  .I du
>  to print values (sizes, times or QID paths)
>  in scientific notation,
> @@ -96,10 +89,9 @@
>  (e.g.,
>  .L G
>  for binary gigabytes).
> -.PP
> -The
> +.TP
>  .B -p
> -option causes
> +Causes

same as above 

>  .I du
>  to print values (sizes, times or QID paths)
>  in units of
> @@ -109,12 +101,6 @@
>  An empty
>  .IR SI-prefix
>  corresponds to a scale factor of 1 (e.g., print sizes in bytes).
> -.\" .PP
> -.\" The
> -.\" .B -r
> -.\" option causes
> -.\" .I du
> -.\" to read and discard every byte of every file encountered.

hmm, this is actually supported by the source code, although it says
its undocumented. i'm inclined to leave it here, commented,
but dont feel strongly.

>  .SH EXAMPLES
>  Print the size of
>  .L /tmp
>