docs: tweak the formatting and wording of several disk-utils man pages

Signed-off-by: Benno Schulenberg <bensberg@justemail.net>

10 files changed, 142 insertions, 131 deletions

diff --git a/disk-utils/elvtune.8 b/disk-utils/elvtune.8
index 6321ee101..f71b1d432 100644
--- a/disk-utils/elvtune.8
+++ b/disk-utils/elvtune.8
@@ -17,42 +17,44 @@ elvtune \- I/O elevator tuner
 .B elvtune \-v
 .SH DESCRIPTION
 .B elvtune
-allows to tune the I/O elevator per blockdevice queue basis. The
-tuning can be safely done at runtime. Tuning the elevator means
-being able to change disk performance and interactiveness. In the
-output of elvtune the address of the queue tuned will be shown
-and it can be considered as a queue ID.
-For example multiple partitions in the same harddisk will
+allows to tune the I/O elevator per blockdevice queue.  The
+tuning can be safely done at runtime.  Tuning the elevator means
+being able to change disk performance and interactiveness.
+In the output of
+.B elvtune
+the address of the queue tuned will be shown;
+it can be considered as a queue ID.
+Multiple partitions on the same harddisk will
 share the same queue and so tuning one partition will be
 like tuning the whole HD.
 .SH OPTIONS
 .TP
 .BI -r \ r_lat
-set the max latency that the I/O scheduler will provide on
+Set the maximum latency that the I/O scheduler will provide on
 each read.
 .TP
 .BI -w \ w_lat
-set the max latency that the I/O scheduler will provide on
+Set the maximum latency that the I/O scheduler will provide on
 each write.
 .TP
 .BI -b \ b_max
-max coalescing factor allowed on writes when there are reads
+Set the maximum coalescing factor allowed on writes when there are reads
 pending in the queue.
 .TP
 .BI -h
-help.
+Display help text and exit.
 .TP
 .BI -v
-version.
+Display version version information and exit.
 .SH NOTE
-Actually the only fields tunable are those relative
-to the IO scheduler. It's not possible to select
+Actually, the only fields tunable are those relative
+to the IO scheduler.  It's not possible to select
 a one-way or two-way elevator yet.
 .PP
 For logical blockdevices like LVM the tuning has to
 be done on the
 .I physical
-devices. Tuning the queue of the LVM logical device
+devices.  Tuning the queue of the LVM logical device
 is useless.
 .SH RETURN VALUE
 0 on success and 1 on failure.
diff --git a/disk-utils/fdformat.8 b/disk-utils/fdformat.8
index 67c5d03ea..d02241ef7 100644
--- a/disk-utils/fdformat.8
+++ b/disk-utils/fdformat.8
@@ -5,12 +5,12 @@
 fdformat \- low-level format a floppy disk
 .SH SYNOPSIS
 .B fdformat
-[\fIoptions\fR] \fIdevice\fR
+.RI [ options ] " device"
 .SH DESCRIPTION
 .B fdformat
-does a low level format on a floppy disk.
+does a low-level format on a floppy disk.
 .I device
-is usually one of the following (for floppy devices, the major = 2, and the
+is usually one of the following (for floppy devices the major = 2, and the
 minor is shown for informational purposes only):
 .sp
 .nf
@@ -46,8 +46,7 @@ to load the disk parameters.
 .SH OPTIONS
 .TP
 \fB\-n\fR, \fB\-\-no\-verify\fR
-No verify.  This option will disable the verification that is performed
-after the format.
+Skip the verification that is normally performed after the formatting.
 .TP
 \fB\-V\fR, \fB\-\-version\fR
 Output version information and exit.
diff --git a/disk-utils/fsck.minix.8 b/disk-utils/fsck.minix.8
index 8f25b0bbd..e84b82b0a 100644
--- a/disk-utils/fsck.minix.8
+++ b/disk-utils/fsck.minix.8
@@ -14,13 +14,13 @@ performs a consistency check for the Linux MINIX filesystem.  The current
 version supports the 14 character and 30 character filename options.
 
 The program
-assumes the file system is quiescent.
+assumes the filesystem is quiescent.
 .B fsck.minix
 should not be used on a mounted device unless you can be sure nobody is
 writing to it (and remember that the kernel can write to it when it
 searches for files).
 
-The device will usually have the following form:
+The \fIdevice\fR name will usually have the following form:
 .nf
 .RS
 /dev/hda[1-63] (IDE disk 1)
@@ -30,7 +30,7 @@ The device will usually have the following form:
 .RE
 .fi
 
-If the file system was changed (i.e., repaired), then
+If the filesystem was changed (i.e., repaired), then
 .B fsck.minix
 will print "FILE SYSTEM HAS CHANGED" and will
 .BR sync (2)
@@ -53,30 +53,30 @@ writing to the disk, and that no files are "zombies" waiting for deletion.
 .SH OPTIONS
 .TP
 .B \-l
-Lists all filenames
+List all filenames.
 .TP
 .B \-r
-Performs interactive repairs
+Perform interactive repairs.
 .TP
 .B \-a
-Performs automatic repairs (this option implies
-.BR \-r ),
-and serves to answer all of the questions asked with the default.  Note
-that this can be extremely dangerous in the case of extensive file system
+Perform automatic repairs.  (This option implies
+.B \-r
+and serves to answer all of the questions asked with the default.)  Note
+that this can be extremely dangerous in the case of extensive filesystem
 damage.
 .TP
 .B \-v
-Verbose
+Be verbose.
 .TP
 .B \-s
-Outputs super-block information
+Output super-block information.
 .TP
 .B \-m
-Activates MINIX-like "mode not cleared" warnings
+Activate MINIX-like "mode not cleared" warnings.
 .TP
 .B \-f
-Force file system check even if the file system was marked as valid (this
-marking is done by the kernel when the file system is unmounted).
+Force a filesystem check even if the filesystem was marked as valid (this
+marking is done by the kernel when the filesystem is unmounted).
 .SH "SEE ALSO"
 .BR fsck (8),
 .BR fsck.ext (8),
@@ -95,7 +95,7 @@ most commonly seen in normal usage.
 If the device does not exist,
 .B fsck.minix
 will print "unable to read super block".  If the device exists, but is not
-a MINIX file system,
+a MINIX filesystem,
 .B fsck.minix
 will print "bad magic number in super-block".
 .SH "EXIT CODES"
@@ -105,10 +105,10 @@ is the sum of the following:
 .IP 0
 No errors
 .IP 3
-File system errors corrected, system should be rebooted if file system was
+Filesystem errors corrected, system should be rebooted if filesystem was
 mounted
 .IP 4
-File system errors left uncorrected
+Filesystem errors left uncorrected
 .IP 8
 Operational error
 .IP 16
@@ -120,7 +120,7 @@ Linus Torvalds (torvalds@cs.helsinki.fi)
 .br
 Error code values by Rik Faith (faith@cs.unc.edu)
 .br
-Added support for file system valid flag: Dr. Wettstein
+Added support for filesystem valid flag: Dr. Wettstein
 (greg%wind.uucp@plains.nodak.edu)
 .br
 Check to prevent fsck of mounted filesystem added by Daniel Quinlan
diff --git a/disk-utils/isosize.8 b/disk-utils/isosize.8
index 678fd8060..6cbc1ffd2 100644
--- a/disk-utils/isosize.8
+++ b/disk-utils/isosize.8
@@ -3,7 +3,7 @@
 isosize \- output the length of an iso9660 filesystem
 .SH SYNOPSIS
 .B isosize
-[\fIoptions\fR] \fIiso9660_image_file\fR
+.RI [ options ] " iso9660_image_file"
 .SH DESCRIPTION
 .\" Add any additional description here
 .PP
@@ -14,19 +14,19 @@ any switches (and errors) it will output the size of the iso9660
 filesystem in bytes.  This can now be a large number (>> 4 GB).
 .SH OPTIONS
 .TP
-\fB\-x\fR, \fB\-\-sectors\fR
+.BR \-x , " \-\-sectors"
 Show the block count and block size in human-readable form.
 The output uses the term "sectors" for "blocks".
 .TP
-\fB\-d\fR, \fB\-\-divisor\fR=\fINUM\fR
+.BR \-d , " \-\-divisor " \fInumber\fR
 Only has an effect when
 .B \-x
-is not given.  The number shown (if no errors)
+is not given.  The value shown (if no errors)
 is the iso9660 file size in bytes divided by
-.IR NUM .
+.IR number .
 So if
-.I NUM
-is the block size then the shown number will be the block count.
+.I number
+is the block size then the shown value will be the block count.
 .PP
 The size of the file (or block device) holding an iso9660
 filesystem can be marginally larger than the actual size of the
diff --git a/disk-utils/mkfs.8 b/disk-utils/mkfs.8
index 02d8b0605..af9304bc7 100644
--- a/disk-utils/mkfs.8
+++ b/disk-utils/mkfs.8
@@ -5,7 +5,9 @@ mkfs \- build a Linux filesystem
 .SH SYNOPSIS
 .SH SYNOPSIS
 .B mkfs
-[\fIoptions\fR] [\fB-t\fR \fItype fs-options\fR] \fIdevice\fR [\fIsize\fR]
+.RI [ options ]
+.RB [ \-t
+.IR "type fs-options" ] " device " [ size ]
 .SH DESCRIPTION
 .B mkfs
 is used to build a Linux filesystem on a device, usually
@@ -28,7 +30,7 @@ is simply a front-end for the various filesystem builders
 (\fBmkfs.\fIfstype\fR)
 available under Linux.
 The filesystem-specific builder is searched for in a number
-of directories like perhaps
+of directories, like perhaps
 .IR /sbin ,
 .IR /sbin/fs ,
 .IR /sbin/fs.d ,
@@ -45,8 +47,8 @@ Please see the filesystem-specific builder manual pages for
 further details.
 .SH OPTIONS
 .TP
-\fB\-t\fR, \fB\-\-type\fR=\fITYPE\fR
-Specifies the type of filesystem to be built.
+.BR \-t , " \-\-type " \fItype\fR
+Specify the \fItype\fR of filesystem to be built.
 If not specified, the default filesystem type
 (currently ext2) is used.
 .TP
@@ -55,19 +57,19 @@ Filesystem-specific options to be passed to the real filesystem builder.
 Although not guaranteed, the following options are supported
 by most filesystem builders.
 .TP
-\fB\-V\fR, \fB\-\-verbose\fR
+.BR \-V , " \-\-verbose"
 Produce verbose output, including all filesystem-specific commands
 that are executed.
 Specifying this option more than once inhibits execution of any
 filesystem-specific commands.
 This is really only useful for testing.
 .TP
-\fB\-V\fR, \fB\-\-version\fR
-Display version information and exit.  Option \fB\-V\fR will display
+.BR \-V , " \-\-version"
+Display version information and exit.  (Option \fB\-V\fR will display
 version information only when it is the only parameter, otherwise it
-will work as \fB\-\-verbose\fR.
+will work as \fB\-\-verbose\fR.)
 .TP
-\fB\-h\fR, \fB\-\-help\fR
+.BR \-h , " \-\-help"
 Display help and exit.
 .SH BUGS
 All generic options must precede and not be combined with
@@ -77,7 +79,7 @@ Some filesystem-specific programs do not support the
 (verbose) option, nor return meaningful exit codes.
 Also, some filesystem-specific programs do not automatically
 detect the device size and require the
-.I blocks
+.I size
 parameter to be specified.
 .SH AUTHORS
 David Engel (david@ods.com)
diff --git a/disk-utils/mkfs.bfs.8 b/disk-utils/mkfs.bfs.8
index 466d6409d..c1794e5a8 100644
--- a/disk-utils/mkfs.bfs.8
+++ b/disk-utils/mkfs.bfs.8
@@ -5,44 +5,48 @@
 mkfs.bfs \- make an SCO bfs filesystem
 .SH SYNOPSIS
 .B mkfs.bfs
-[\fIoptions\fR] \fIdevice \fR[\fIblock-count\fR]
+.RI [ options ] " device " [ block-count ]
 .SH DESCRIPTION
 .B mkfs.bfs
-creates an SCO bfs file-system on a block device
+creates an SCO bfs filesystem on a block device
 (usually a disk partition or a file accessed via the loop device).
 .PP
 The
 .I block-count
-parameter is the desired size of the file system, in blocks.
+parameter is the desired size of the filesystem, in blocks.
 If nothing is specified, the entire partition will be used.
 .SH OPTIONS
 .TP
-\fB\-N\fR, \fB\-\-inodes\fR=\fINUM\fR
-Specify the desired number of inodes (at most 512).
-If nothing is specified some default number in the range 48-512 is picked
+.BR \-N , " \-\-inodes " \fInumber\fR
+Specify the desired \fInumber\fR of inodes (at most 512).
+If nothing is specified, some default number in the range 48-512 is picked
 depending on the size of the partition.
 .TP
-\fB\-V\fR, \fB\-\-vname\fR=\fINAME\fR
-Specify the volume label. I have no idea if/where this is used.
+.BR \-V , " \-\-vname " \fIlabel\fR
+Specify the volume \fIlabel\fR.  I have no idea if/where this is used.
 .TP
-\fB\-F\fR, \fB\-\-fname\fR=\fINAME\fR
-Specify the fsname. I have no idea if/where this is used.
+.BR \-F , " \-\-fname " \fIname\fR
+Specify the filesystem \fIname\fR.  I have no idea if/where this is used.
 .TP
-\fB\-v\fR, \fB\-\-verbose\fR
+.BR \-v , " \-\-verbose"
 Explain what is being done.
 .TP
-\fB\-c\fR
+.B \-c
 This option is silently ignored.
 .TP
-\fB\-l\fR
+.B \-l
 This option is silently ignored.
 .TP
-\fB\-V\fR, \fB\-\-version\fR
-Output version information and exit.
-\fB\-V\fR works only when specified as an only option.
+.BR \-h , " \-\-help"
+Display help text and exit.
 .TP
-\fB\-h\fR, \fB\-\-help\fR
-Display help and exit.
+.BR \-V , " \-\-version"
+Output version information and exit.
+Option
+.B \-V
+only works as
+.B \-\-version
+when it is the only option.
 .SH "EXIT CODES"
 The exit code returned by
 .B mkfs.bfs
diff --git a/disk-utils/mkfs.minix.8 b/disk-utils/mkfs.minix.8
index 4ee0e819b..a65a711dd 100644
--- a/disk-utils/mkfs.minix.8
+++ b/disk-utils/mkfs.minix.8
@@ -16,7 +16,7 @@ mkfs.minix \- make a Minix filesystem
 .RI [ size-in-blocks ]
 .SH DESCRIPTION
 .B mkfs.minix
-creates a Linux MINIX file-system on a device (usually a disk partition).
+creates a Linux MINIX filesystem on a device (usually a disk partition).
 
 The
 .I device
@@ -41,28 +41,28 @@ Only block counts strictly greater than 10 and strictly less than
 .SH OPTIONS
 .TP
 .B \-c
-Check the device for bad blocks before creating the file system.  If any
+Check the device for bad blocks before creating the filesystem.  If any
 are found, the count is printed.
 .TP
 .BI \-n " namelength"
 Specify the maximum length of filenames.
 Currently, the only allowable values are 14 and 30.
-The default is 30. Note that kernels older than 0.99p7
+The default is 30.  Note that kernels older than 0.99p7
 only accept namelength 14.
 .TP
 .BI \-i " inodecount"
 Specify the number of inodes for the filesystem.
 .TP
 .BI \-l " filename"
-Read the bad blocks list from
+Read the list of bad blocks from
 .IR filename .
-The file has one bad block number per line.  The count of bad blocks read
+The file has one bad-block number per line.  The count of bad blocks read
 is printed.
 .TP
 .B \-1
 Make a Minix version 1 filesystem.
 .TP
-.B  \-2,\-v
+.BR \-2 , " \-v"
 Make a Minix version 2 filesystem.
 .TP
 .B \-3
diff --git a/disk-utils/mkswap.8 b/disk-utils/mkswap.8
index 59a93dcc3..c65317115 100644
--- a/disk-utils/mkswap.8
+++ b/disk-utils/mkswap.8
@@ -8,9 +8,9 @@
 mkswap \- set up a Linux swap area
 .SH SYNOPSIS
 .B mkswap
-.RB [ options ]
-.IR device
-.RB [ size ]
+.RI [ options ]
+.I device
+.RI [ size ]
 .SH DESCRIPTION
 .B mkswap
 sets up a Linux swap area on a device or in a file.
@@ -47,54 +47,59 @@ The swap header does not touch the first block.  A boot loader or disk label
 can be there, but it is not a recommended setup.  The recommended setup is to
 use a separate partition for a Linux swap area.
 
-.B mkswap, like many others mkfs-like utils, erases the first block to remove
-.B old on-disk filesystems.
+.BR mkswap ,
+like many others mkfs-like utils,
+.B erases the first partition block to make any previous filesystem invisible.
 
+However,
 .B mkswap
 refuses to erase the first block on a device with a disk
-label (SUN, BSD, ...) or on a whole disk (e.g. /dev/sda).
+label (SUN, BSD, ...) and on a whole disk (e.g. /dev/sda).
 
 .SH OPTIONS
 .TP
 .BR \-c , " \-\-check"
 Check the device (if it is a block device) for bad blocks
 before creating the swap area.
-If any are found, the count is printed.
+If any bad blocks are found, the count is printed.
 .TP
 .BR \-f , " \-\-force"
-Force -- go ahead even if the command is stupid.
+Go ahead even if the command is stupid.
 This allows the creation of a swap area larger than the file
 or partition it resides on.
 
-Without this option,
+Also, without this option,
 .B mkswap
-will refuse to erase the first block on a device with a partition table or on
+will refuse to erase the first block on a device with a partition table and on
 a whole disk (e.g. /dev/sda).
 .TP
-.BR \-L , " \-\-label" \ device-label
-Specify a label, to allow
+.BR \-L , " \-\-label " \fIlabel\fR
+Specify a \fIlabel\fR for the device, to allow
 .B swapon
 by label.
 .TP
-.BR \-p , " \-\-pagesize" \ SIZE
-Specify the page size (in bytes) to use.  This option is usually unnecessary,
+.BR \-p , " \-\-pagesize " \fIsize\fR
+Specify the page \fIsize\fR (in bytes) to use.  This option is usually unnecessary;
 .B mkswap
 reads the size from the kernel.
 .TP
-.BR \-U , " \-\-uuid" \ UUID
-Specify the uuid to use.  The default is to generate a UUID.
+.BR \-U , " \-\-uuid " \fIUUID\fR
+Specify the \fIUUID\fR to use.  The default is to generate a UUID.
 .TP
-.BR \-v , " \-\-swapversion" \ 1
-Specify the swap-space version.  The old \-v 0 option has become obsolete
-and now only \-v 1 is supported.
-
-The kernel has not supported v0 swap-space format since 2.5.22 (Jun 2002).
-The new version v1 is supported since 2.1.117 (Aug 1998).
+.BR \-v , " \-\-swapversion 1"
+Specify the swap-space version.  (This option is currently pointless, as the old
+.B \-v 0
+option has become obsolete and now only
+.B \-v 1
+is supported.
+The kernel has not supported v0 swap-space format since 2.5.22 (June 2002).
+The new version v1 is supported since 2.1.117 (August 1998).)
 .TP
-.BR \-V , " \-\-version"
-Output version information and exit.
 .BR \-h , " \-\-help"
-Output help screen and exit.
+Display help text and exit.
+.TP
+.BR \-V , " \-\-version"
+Display version information and exit.
 
 .SH NOTES
 The maximum useful size of a swap area depends on the architecture and
diff --git a/disk-utils/raw.8 b/disk-utils/raw.8
index b85080a5a..0e47843c6 100644
--- a/disk-utils/raw.8
+++ b/disk-utils/raw.8
@@ -9,12 +9,10 @@ raw \- bind a Linux raw character device
 .B raw
 .I /dev/raw/raw<N> /dev/<blockdev>
 .PP
-.B raw
-.B \-q
+.B raw \-q
 .I /dev/raw/raw<N>
 .PP
-.B raw
-.B \-qa
+.B raw \-qa
 .SH DESCRIPTION
 .B raw
 is used to bind a Linux raw character device to a block device.  Any
@@ -38,7 +36,7 @@ to an existing block device file.
 .PP
 The bindings already in existence can be queried with the 
 .I \-q
-option, with is used either with a raw device filename to query that one
+option, which is used either with a raw device filename to query that one
 device, or with the 
 .I \-a
 option to query all bound raw devices.
@@ -70,16 +68,16 @@ will query an existing binding instead of setting a new one.
 .B -a
 With
 .B -q
-, specifies that all bound raw devices should be queried.
+, specify that all bound raw devices should be queried.
 .TP
 .B -h
-provides a usage summary.
+Provide a usage summary.
 .SH BUGS
 The Linux
-.B dd
-(1) command should be used without bs= option or the blocksize needs to be a
-multiple of the sector size of the device (512 bytes usually) otherwise it
-will fail with "Invalid Argument" messages (EINVAL).
+.BR dd (1)
+command should be used without the \fBbs=\fR option, or the blocksize
+needs to be a multiple of the sector size of the device (512 bytes usually),
+otherwise it will fail with "Invalid Argument" messages (EINVAL).
 
 .PP
 Raw I/O devices do not maintain cache coherency with the Linux block
diff --git a/disk-utils/swaplabel.8 b/disk-utils/swaplabel.8
index 327a65f26..0d47456c4 100644
--- a/disk-utils/swaplabel.8
+++ b/disk-utils/swaplabel.8
@@ -22,35 +22,36 @@ If the optional arguments
 .B \-L 
 and
 .B \-U 
-are not present,
+are not given,
 .B swaplabel
-will simply display the swap area label and UUID of
+will simply display the current swap-area label and UUID of
 .IR device .
 .PP
 If an optional argument is present, then
 .B swaplabel
-will change the appropriate value of
+will change the appropriate value on
 .IR device .
 These values can also be set during swap creation using
 .BR mkswap (8).
 The
 .B swaplabel
-utility allows to change the label or UUID on actively used swap device.
+utility allows to change the label or UUID on an actively used swap device.
 .SH OPTIONS
-.IP "\fB\-h, \-\-help\fP"
-Print help and exit.
-.IP "\fB\-L, \-\-label\fP \fIlabel\fP"
-Specify a new label for
-.IR device .
+.TP
+.BR \-h , " \-\-help"
+Display help text and exit.
+.TP
+.BR \-L , " \-\-label " \fIlabel\fR
+Specify a new \fIlabel\fR for the device.
 Swap partition labels can be at most 16 characters long.  If
-.IR label
+.I label
 is longer than 16 characters,
-.B swapinfo
+.B swaplabel
 will truncate it and print a warning message.
-.IP "\fB\-U, \-\-uuid\fP \fIuuid\fP"
-Specify a new UUID for
-.IR device .
-.IR UUID
+.TP
+.BR \-U , " \-\-uuid " \fIUUID\fR
+Specify a new \fIUUID\fR for the device.
+The \fI UUID\fR
 must be in the standard 8-4-4-4-12 character format, such as is output by
 .BR uuidgen (1) .
 .PP
@@ -58,8 +59,8 @@ must be in the standard 8-4-4-4-12 character format, such as is output by
 .B swaplabel
 was written by Jason Borden <jborden@bluehost.com> and Karel Zak <kzak@redhat.com>.
 .SH AVAILABILITY
-.B swaplabel
-is part of the util-linux package and is available from ftp://ftp.kernel.org/pub/linux/utils/util-linux/.
+The swaplabel command is part of the util-linux package and is available from
+ftp://ftp.kernel.org/pub/linux/utils/util-linux/.
 .SH SEE ALSO
 .BR mkswap (8),
 .BR swapon (8),