bin/45735: The dump(8) manpage, as well as the program's `usage'-line, needs improvement

[bughunting%xs4all.nl@localhost]

>Number:         45735
>Category:       bin
>Synopsis:       The dump(8) manpage, as well as the program's `usage'-line, 
>needs improvement
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    bin-bug-people
>State:          open
>Class:          doc-bug
>Submitter-Id:   net
>Arrival-Date:   Fri Dec 23 02:15:00 +0000 2011
>Originator:     Bug Hunting
>Release:        NetBSD-current (5.99.59)
>Organization:
>Environment:
>Description:
The dump(8) manpage, as well as the program's `usage'-line, needs improvement.

Exact changes (one can put this in the CVS commit message):

dump.8:
- improve wording / punctuation;
- correct order of options;
- make better use of mdoc(7)-macro.

main.c:
- add `-i' to the usage line (which was forgotten in r1.65);
- replace the name of `-r's argument in the usage line with the
  one used in the manpage (which was added there with r1.32 of
  dump.8).
>How-To-Repeat:
"man 8 dump" (show the manpage);
"dump -q" (print the `usage'-line, using a non-existent option).
>Fix:
Apply the following proposed patch (the MD5-sum of this patch is
5d91900956bdc553bd235c2d7857af72; please verify it before applying):

Index: sbin/dump/dump.8
===================================================================
RCS file: /cvsroot/src/sbin/dump/dump.8,v
retrieving revision 1.62
diff -u -r1.62 dump.8
--- sbin/dump/dump.8    5 Nov 2010 10:02:53 -0000       1.62
+++ sbin/dump/dump.8    23 Dec 2011 01:30:12 -0000
@@ -57,10 +57,9 @@
 .Op Fl W Li \&| Fl w
 .Pp
 .in -\n[indent-synopsis]u
-(The
-.Bx 4.3
+.Pf ( Bx 4.3
 option syntax is implemented for backward compatibility, but
-is not documented here).
+not documented here.)
 .Sh DESCRIPTION
 .Nm
 examines files on a file system and determines which files need to
@@ -209,15 +208,6 @@
 The size in kilobyte of the read buffers, rounded up to a multiple of the
 file system block size.
 Default is 32k.
-.It Fl l Ar timeout
-If a tape change is required, eject the tape and wait for the drive to
-be ready again.
-This is to be used with tape changers which automatically load
-the next tape when the tape is ejected.
-If after the timeout (in seconds) the drive is not ready
-.Nm
-falls back to the default behavior,
-and prompts the operator for the next tape.
 .It Fl L Ar label
 The user-supplied text string
 .Ar label
@@ -229,6 +219,15 @@
 Note that this label is limited to be at most LBLSIZE
 (currently 16) characters, which must include the terminating
 .Ql \e0 .
+.It Fl l Ar timeout
+If a tape change is required, eject the tape and wait for the drive to
+be ready again.
+This is to be used with tape changers which automatically load
+the next tape when the tape is ejected.
+If after the timeout (in seconds) the drive is not ready
+.Nm
+falls back to the default behavior,
+and prompts the operator for the next tape.
 .It Fl n
 Whenever
 .Nm
@@ -247,6 +246,9 @@
 option for the size of the buffers.
 Maximum is 512, the size of the cache is
 limited to 15% of the avail RAM by default.
+.It Fl S
+Display an estimate of the backup size and the number of tapes
+required, and exit without actually performing the dump.
 .It Fl s Ar feet
 Attempt to calculate the amount of tape needed
 at a particular density.
@@ -255,16 +257,6 @@
 prompts for a new tape.
 It is recommended to be a bit conservative on this option.
 The default tape length is 2300 feet.
-.It Fl S
-Display an estimate of the backup size and the number of tapes
-required, and exit without actually performing the dump.
-.It Fl t
-All informational log messages printed by
-.Nm
-will have the time prepended to them.
-Also, the completion time interval estimations
-will have the estimated time at which the dump
-will complete printed at the end of the line.
 .It Fl T Ar date
 Use the specified date as the starting time for the dump
 instead of the time determined from looking in
@@ -278,6 +270,13 @@
 option is mutually exclusive from the
 .Fl u
 option.
+.It Fl t
+All informational log messages printed by
+.Nm
+will have the time prepended to them.
+Also, the completion time interval estimations
+will have the estimated time at which the dump
+will complete printed at the end of the line.
 .It Fl u
 Update the file
 .Pa /etc/dumpdates
@@ -300,6 +299,10 @@
 (as opposed to an entire file system), then
 .Fl u
 is ignored.
+.It Fl X
+Similar to
+.Fl x
+but uses a file system internal snapshot on the file system to be dumped.
 .It Fl x Ar snap-backup
 Use a snapshot with
 .Ar snap-backup
@@ -307,10 +310,6 @@
 See
 .Xr fss 4
 for more details.
-.It Fl X
-Similar to
-.Fl x
-but uses a file system internal snapshot on the file system to be dumped.
 .It Fl W
 .Nm
 tells the operator what file systems need to be dumped.
@@ -332,7 +331,9 @@
 .Nm
 exits immediately.
 .It Fl w
-Is like W, but prints only those file systems which need to be dumped.
+Like
+.Fl W ,
+but prints only those file systems which need to be dumped.
 .El
 .Pp
 If
Index: sbin/dump/main.c
===================================================================
RCS file: /cvsroot/src/sbin/dump/main.c,v
retrieving revision 1.66
diff -u -r1.66 main.c
--- sbin/dump/main.c    11 Mar 2010 01:32:59 -0000      1.66
+++ sbin/dump/main.c    23 Dec 2011 01:30:12 -0000
@@ -661,9 +661,9 @@
        const char *prog = getprogname();
 
        (void)fprintf(stderr,
-"usage: %s [-0123456789aceFnStuX] [-B records] [-b blocksize]\n"
+"usage: %s [-0123456789aceFinStuX] [-B records] [-b blocksize]\n"
 "            [-d density] [-f file] [-h level] [-k read-blocksize]\n"
-"            [-L label] [-l timeout] [-r read-cache] [-s feet]\n"
+"            [-L label] [-l timeout] [-r cachesize] [-s feet]\n"
 "            [-T date] [-x snap-backup] files-to-dump\n"
 "       %s [-W | -w]\n", prog, prog);
        exit(X_STARTUP);