docs/162438: du(1) man page improvements

Thu Nov 10 21:50:11 UTC 2011

The following reply was made to PR docs/162438; it has been noted by GNATS.

From: Benjamin Kaduk <kaduk at mit.edu>
To: Alexander Best <arundel at freebsd.org>
Cc: freebsd-gnats-submit at freebsd.org, freebsd-doc at freebsd.org
Subject: Re: docs/162438: du(1) man page improvements
Date: Thu, 10 Nov 2011 16:22:28 -0500 (EST)

 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.

 -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"
 >