Fixup some things that Leigh/Jay pointed out.

os/imagezip/imageunzip.8

@@ -83,6 +83,12 @@ is '-', the image is read from
 The output file for the expanded image.  If not specified,
 .Va stdout
 is used.
+.Bf Em
+Note that if the output file is a device special file, it should always be
+the special file for an entire disk even when restoring slice images with the
+.Fl s
+option.
+.Ef
 .El
 .Pp
 Recognized options are:
@@ -116,6 +122,10 @@ Specify a 32-bit
 that is to be written to free blocks when using the
 .Fl z
 option.  The default value is zero.
+The number may be in octal, decimal or hex depending on the prefix.
+See
+.Xr strtoul 3
+for details.
 .It Fl s Ar slice
 Restore
 .Ar image
@@ -149,12 +159,8 @@ does not include the content of free blocks in the image and
 because
 .Nm
 may not initialize these free blocks with any value, you cannot
-perform a simple compare of the source and destination of an image.
-.Pp
-If
-.Ar outfile
-is a device special file, it should always be the special file for
-an entire disk even when restoring slice images.
+perform a simple compare of the source and destination of an image
+to verify the correctness of the copy.
 .Pp
 Since slice images do not contain the DOS MBR, you cannot load a slice image
 on a naked disk and expect it to boot.
@@ -164,7 +170,7 @@ option to ignore all but the slice you care about, thus
 creating a full disk image containing only that single slice.
 .Pp
 If the output file is a disk or slice,
-it should not overlap with the filesystem you are running off of
+it should not overlap with the filesystem you are running on
 or disaster will ensue!
 .Sh EXAMPLES
 .Dl imageunzip /nfs/backup/images/myimage.ndz /dev/ad0
@@ -177,7 +183,7 @@ from a CDROM or the network.
 .Pp
 As above but uses ssh to transfer the image from the remote machine.
 .Pp
-.Dl ssh backup imagezip -s 1 /dev/ad0 | imageunzip -z -D 165 -s 1 - /dev/ad0
+.Dl ssh backup imagezip -s 1 /dev/ad0 - | imageunzip -z -D 165 -s 1 - /dev/ad0
 .Pp
 Image slice 1 on the remote machine and restore it to the same slice
 on the local disk, zeroing all free blocks and marking the slice as

os/imagezip/imagezip.8

@@ -11,8 +11,7 @@
 .Nd create a compressed image of a complete disk or DOS partition
 .Sh SYNOPSIS
 .Nm
-.Op Fl bdhilorv
-.Op Fl c Ar count
+.Op Fl dhiorv
 .Op Fl I Ar slice
 .Op Fl s Ar slice
 .Op Fl z Ar level
@@ -90,6 +89,7 @@ partition in turn.  If no partition table is found,
 fails.  Within a BSD slice, filesystem partitions are smartly compressed,
 unused and swap partitions are skipped, and all others are
 compressed conventionally.
+.Em This has only been tested with FreeBSD .
 .It Sy Linux filesystem
 (131).
 If the slice contains a Linux EXT2FS, it is smartly compressed.
@@ -108,32 +108,25 @@ Command line arguments are:
 .Bl -tag -width "outfile"
 .It device
 The device to be imaged.  This is typically a disk special file.
+.Bf Em
+If device is a disk special file, it should always be the special file for
+an entire disk even when creating slice images with the
+.Fl s
+option.
+.Ef
 .It outfile
-The output file for the resulting image.  If not specified,
-.Va stdout
-is used.
+The output file for the resulting image.  If
+.Ar outfile
+is '-', the image is written to
+.Va stdout .
+.Em Never write the output to a file on the disk or slice you are imaging .
+This would cause the disk or slice to change as you are saving it.
+When creating a slice image,
+it is ok to save to a different slice on the same disk.
 .El
 .Pp
-Recognized options are:
+The most common options are:
 .Bl -tag -width indent
-.It Fl b
-Tells
-.Nm
-that
-.Ar device
-is a BSD slice.  Should be used only when the device does not contain
-a DOS partition table and really does contains a BSD filesystem.
-Incompatible with
-.Fl l .
-You will probably never need this option.
-.It Fl c Ar count
-Explicitly tell
-.Nm
-how many sectors to compress in full disk mode.  Can be used to compress
-a subset of a disk.
-Incompatible with
-.Fl s .
-You will probably never need this option.
 .It Fl d
 Turn on debugging output.  Can be specified multiple times to increase
 the level of debugging output.
@@ -151,16 +144,6 @@ Incompatible with
 Prints a variety of diagnostic information about what
 .Nm
 would do, but doesn't create an image file.
-.It Fl l
-Tells
-.Nm
-that
-.Ar device
-is a Linux filesystem slice.  Should be used only when the device does
-not contain a DOS partition table and really does contains a Linux filesystem.
-Incompatible with
-.Fl b .
-You will probably never need this option.
 .It Fl o
 Indicate the progress of image creation by printing a dot ('.') to
 .Dv stderr
@@ -187,6 +170,37 @@ compression library.  Higher levels mean better compression but will cause
 .Nm
 to run longer.  Level 0 means no compression.  The default value is 4.
 .El
+.Pp
+There are also a few additional
+.Dq developer
+options that you should never need to use:
+.Bl -tag -width indent
+.It Fl b
+Tells
+.Nm
+that
+.Ar device
+is a BSD slice.  Should be used only when the device does not contain
+a DOS partition table and really does contains a BSD filesystem.
+Incompatible with
+.Fl l .
+.It Fl c Ar count
+Explicitly tell
+.Nm
+how many sectors to compress in full disk mode.  Can be used to compress
+a subset of a disk.
+Incompatible with
+.Fl s .
+.It Fl l
+Tells
+.Nm
+that
+.Ar device
+is a Linux filesystem slice.  Should be used only when the device does
+not contain a DOS partition table and really does contains a Linux filesystem.
+Incompatible with
+.Fl b .
+.El
 .Sh DIAGNOSTICS
 The
 .Nm
@@ -225,20 +239,17 @@ If you need such a bootable slice image, you can use the
 option to ignore all but the slice you care about, thus
 creating a full disk image containing only that single slice.
 .Pp
-The output image,
-.Ar outfile ,
-created by imagezip should not be on the same disk
-that you are imaging since you would be changing the disk as it is saving.
 In general, it is a bad idea to create an image of an active disk.
+At best you wind up with incomplete data, at worst a corrupted disk image.
 .Pp
 FreeBSD partition tables contain absolute, not slice relative, block
 numbers.
 .Nm
 contains code to recognize this and generates "relocation entries"
-for imageunzip to use.  But this is only one problem you will encounter
+for imageunzip to use.  However, this is only one problem you will encounter
 if attempting to move a FreeBSD slice to a different location.
 .Pp
-Likewise, Linux boot boot blocks generated by LILO appear to contain
+Likewise, Linux boot blocks generated by LILO appear to contain
 absolute block numbers.  In theory, the
 .Nm
 relocation mechanism could handle this, but no one I know groks LILO.
@@ -253,7 +264,7 @@ NFS to a remote machine.  This could be done with the machine in single
 user mode and the root filesystem mounted read-only, or it could be
 done from a CDROM or network booted system.
 .Pp
-.Dl imagezip /dev/ad0 | ssh backup 'cat > /backup/images/myimage.ndz'
+.Dl imagezip /dev/ad0 - | ssh backup 'cat > /backup/images/myimage.ndz'
 .Pp
 As above but uses ssh to transfer the image to the remote machine.
 .Pp
@@ -262,9 +273,10 @@ As above but uses ssh to transfer the image to the remote machine.
 Create a slice image of DOS partition 1 on the primary disk, amusing
 yourself by watching the dots go by.
 .Pp
-.Dl imagezip -r -z 9 /dev/ad0 | imageunzip - /dev/ad1
+.Dl imagezip -o -I 2 -I 3 -I 4 /dev/ad0 myimage.ndz
 .Pp
-A really slow way to copy one disk to another.
+Similar to the previous example, but create a full disk image which
+contains only the data from DOS partition 1.
 .Sh SEE ALSO
 .Xr imageunzip 8 ,
 .Xr imagedump 8 ,