docs/162438: du(1) man page improvements

[Alexander Best]

On Thu Nov 10 11, Benjamin Kaduk wrote:
> On Thu, 10 Nov 2011, Alexander Best wrote:
> 
> >Patch attached with submission follows:
> >
> >diff --git a/usr.bin/du/du.1 b/usr.bin/du/du.1
> >index ef8b5ac..960be23 100644
> >--- a/usr.bin/du/du.1
> >+++ b/usr.bin/du/du.1
> >@@ -28,7 +28,7 @@
> >.\"	@(#)du.1	8.2 (Berkeley) 4/1/94
> >.\" $FreeBSD$
> >.\"
> >-.Dd November 6, 2008
> >+.Dd November 10, 2011
> >.Dt DU 1
> >.Os
> >.Sh NAME
> >@@ -36,15 +36,12 @@
> >.Nd display disk usage statistics
> >.Sh SYNOPSIS
> >.Nm
> >-.Op Fl A
> >+.Op Fl Achklmnx
> >.Op Fl H | L | P
> >-.Op Fl a | s | d Ar depth | Fl t Ar threshold
> >-.Op Fl c
> >-.Op Fl l
> >-.Op Fl h | k | m | B Ar blocksize
> >-.Op Fl n
> >-.Op Fl x
> >+.Op Fl a | s | d Ar depth
> >+.Op Fl B Ar blocksize
> >.Op Fl I Ar mask
> >+.Op Fl t Ar threshold
> >.Op Ar
> >.Sh DESCRIPTION
> >The
> >@@ -61,11 +58,13 @@ The options are as follows:
> >Display the apparent size instead of the disk usage.
> >This can be helpful when operating on compressed volumes or sparse files.
> >.It Fl B Ar blocksize
> >-Calculate block counts in
> >+Calculate block count in
> 
> I think this is incorrect.  Block counts are computed for all path 
> arguments given to du(1).  (Even if it was just "block count", it would 
> need to be "the block count".)
> 
> >.Ar blocksize
> >byte blocks.
> >This is different from the
> >-.Fl k, m
> >+.Fl h, k
> >+and
> >+.Fl  m
> >options or setting
> >.Ev BLOCKSIZE
> >and gives an estimate of how much space the examined file hierarchy would
> >@@ -79,20 +78,45 @@ is rounded up to the next multiple of 512.
> >.It Fl H
> >Symbolic links on the command line are followed, symbolic links in file
> >hierarchies are not followed.
> >-.It Fl L
> >-Symbolic links on the command line and in file hierarchies are followed.
> >.It Fl I Ar mask
> >Ignore files and directories matching the specified
> >.Ar mask .
> >+.It Fl L
> >+Symbolic links on the command line and in file hierarchies are followed.
> >.It Fl P
> >No symbolic links are followed.
> >This is the default.
> >.It Fl a
> >Display an entry for each file in a file hierarchy.
> >+.It Fl c
> >+Display a grand total.
> >+.It Fl d Ar depth
> >+Display an entry for all files and directories
> >+.Ar depth
> >+directories deep.
> >.It Fl h
> >"Human-readable" output.
> >Use unit suffixes: Byte, Kilobyte, Megabyte,
> >Gigabyte, Terabyte and Petabyte.
> >+.It Fl k
> >+Display block count in 1024-byte (1-Kbyte) blocks.
> 
> Likewise here.
> 
> >+.It Fl l
> >+If a file has multiple hard links, count its size many times.
> 
> I would probably s/many/multiple/ to make the parallelism clear.
> 
> >+The default behavior of
> >+.Nm
> >+is to count files with multiple hard links only once.
> >+When the
> >+.Fl l
> >+option is specified, the hard link checks are disabled, and these files
> >+are counted (and displayed) as many times as they are found.
> 
> Could use .Pq, I suppose.
> 
> >+.It Fl m
> >+Display block count in 1048576-byte (1-Mbyte) blocks.
> 
> block counts, again.
> (and .Pq)
> 
> (Is moving a block of text around in the same commit as changing it 
> actually a good idea?)
> 
> >+.It Fl n
> >+Ignore files and directories with user
> >+.Dq nodump
> >+flag
> >+.Pq Dv UF_NODUMP
> >+set.
> >.It Fl r
> >Generate messages about directories that cannot be read, files
> >that cannot be opened, and so on.
> [the block that got moved]
> >@@ -152,26 +151,33 @@ If either the
> >.Fl H
> >or
> >.Fl L
> >-options are specified, storage used by any symbolic links which are
> >-followed is not counted or displayed.
> >+option is specified, storage used by any symbolic links which are
> >+followed is not counted (or displayed).
> >+.Pp
> >+The
> >+.Fl h, k
> >+and
> >+.Fl m
> >+options all override each other; the last one specified determines
> >+the block count used.
> >.Sh ENVIRONMENT
> >.Bl -tag -width BLOCKSIZE
> >.It Ev BLOCKSIZE
> >If the environment variable
> >.Ev BLOCKSIZE
> >is set, and the
> >-.Fl k, m
> >+.Fl h, k
> >or
> >-.Fl h
> >-options are not specified, the block counts will be displayed in units of
> >+.Fl m
> >+options are not specified, the block count will be displayed in units of
> 
> counts again
> 
> 
> Thanks for spotting the style issues.

thanks for looking at my patch. i'll try to fix all those issues you mentioned
and will submit a followup patch.

cheers.
alex

> 
> -Ben Kaduk
> 
> 
> >that block size.
> >If
> >.Ev BLOCKSIZE
> >is not set, and the
> >-.Fl k, m
> >+.Fl h, k
> >or
> >-.Fl h
> >-options are not specified, the block counts will be displayed in 512-byte
> >+.Fl m
> >+options are not specified, the block count will be displayed in 512-byte
> >blocks.
> >.El
> >.Sh SEE ALSO
> >
> >
> >>Release-Note:
> >>Audit-Trail:
> >>Unformatted:
> >_______________________________________________
> >freebsd-doc at freebsd.org mailing list
> >http://lists.freebsd.org/mailman/listinfo/freebsd-doc
> >To unsubscribe, send any mail to "freebsd-doc-unsubscribe at freebsd.org"
> >