docs: fix some things that were overlooked during the first pass

Mainly more option sorting, some formatting adjustments, and the adding
of a missing --version here and there.

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

1 files changed, 56 insertions, 48 deletions

diff --git a/sys-utils/fallocate.1 b/sys-utils/fallocate.1
index b03f19b59..07623216e 100644
--- a/sys-utils/fallocate.1
+++ b/sys-utils/fallocate.1
@@ -4,9 +4,9 @@
 fallocate \- preallocate or deallocate space to a file
 .SH SYNOPSIS
 .B fallocate
+.RB [ \-c ]
 .RB [ \-n ]
 .RB [ \-p ]
-.RB [ \-c ]
 .RB [ \-z ]
 .RB [ \-o
 .IR offset ]
@@ -14,8 +14,7 @@ fallocate \- preallocate or deallocate space to a file
 .IR length
 .I filename
 .PP
-.B fallocate
-.RB \-d
+.B fallocate \-d
 .RB [ \-o
 .IR offset ]
 .RB [ \-l
@@ -24,28 +23,57 @@ fallocate \- preallocate or deallocate space to a file
 .SH DESCRIPTION
 .B fallocate
 is used to manipulate the allocated disk space for a file, either to deallocate
-or preallocate it. For filesystems which support the fallocate system call,
+or preallocate it.  For filesystems which support the fallocate system call,
 preallocation is done quickly by allocating blocks and marking them as
-uninitialized, requiring no IO to the data blocks. This is much faster than
+uninitialized, requiring no IO to the data blocks.  This is much faster than
 creating a file by filling it with zeros.
 .PP
 The exit code returned by
 .B fallocate
 is 0 on success and 1 on failure.
-.PP
 .SH OPTIONS
-The \fIlength\fR and \fIoffset\fR arguments may be followed by the multiplicative
-suffixes KiB=1024, MiB=1024*1024, and so on for GiB, TiB, PiB, EiB, ZiB and YiB
-(the "iB" is optional, e.g. "K" has the same meaning as "KiB") or the suffixes
-KB=1000, MB=1000*1000, and so on for GB, TB, PB, EB, ZB and YB.
-
+The \fIlength\fR and \fIoffset\fR
+arguments may be followed by the multiplicative suffixes KiB (=1024),
+MiB (=1024*1024), and so on for GiB, TiB, PiB, EiB, ZiB and YiB (the "iB" is
+optional, e.g., "K" has the same meaning as "KiB") or the suffixes
+KB (=1000), MB (=1000*1000), and so on for GB, TB, PB, EB, ZB and YB.
+.PP
 The options \fB\-\-collapse-range\fP, \fB\-\-dig-holes\fP, \fB\-\-punch-hole\fP and
 \fB\-\-zero-range\fP are mutually exclusive.
-
-.IP "\fB\-n, \-\-keep-size\fP"
+.TP
+.BR \-c , " \-\-collapse-range"
+Removes a byte range from a file, without leaving a hole.  The byte range
+to be collapsed starts at \fIoffset\fP and continues
+for \fIlength\fR bytes.  At the completion of the operation, the contents of
+the file starting at the location \fIoffset\fR+\fIlength\fR will be appended at the
+location \fIoffset\fR, and the file will be \fIlength\fR bytes smaller.  The option
+\fB\-\-keep\-size\fR may not be specified for colapse range operation.
+.sp
+Available since Linux 3.15 for ext4 (only for extent-based files) and XFS.
+.TP
+.BR \-d , " \-\-dig-holes"
+Detect and dig holes.  This makes the file sparse in-place, without using extra
+disk space.  The minimum size of the hole depends on filesystem I/O block size
+(usually 4096 bytes).  Also, when using this option, \fB\-\-keep-size\fP is
+implied.  If no range is specified by \fB\-\-offset\fP and \fB\-\-length\fP,
+then the entire file is analyzed for holes.
+.sp
+You can think of this option as doing a "\fBcp --sparse\fP" and then renaming
+the destination file to the original, without the need for extra disk space.
+.sp
+See \fB\-\-punch-hole\fP for a list of supported filesystems.
+.TP
+.BR \-l , " \-\-length " \fIlength
+Specifies the length of the range, in bytes.
+.TP
+.BR \-n , " \-\-keep-size"
 Do not modify the apparent length of the file.  This may effectively allocate
 blocks past EOF, which can be removed with a truncate.
-.IP "\fB\-p, \-\-punch-hole\fP"
+.TP
+.BR \-o , " \-\-offset " \fIoffset
+Specifies the beginning offset of the range, in bytes.
+.TP
+.BR \-p , " \-\-punch-hole"
 Deallocates space (i.e., creates a hole) in the byte range starting at
 \fIoffset\fP and continuing for \fIlength\fR bytes.  Within the
 specified range, partial filesystem blocks are zeroed, and whole
@@ -53,55 +81,35 @@ filesystem blocks are removed from the file.  After a successful
 call, subsequent reads from this range will return zeroes.  This option
 may not be specified at the same time as  the \fB\-\-zero-range\fP option.
 Also, when using this option, \fB\-\-keep-size\fP is implied.
-
+.sp
 Supported for XFS (since Linux 2.6.38), ext4 (since Linux 3.0),
 Btrfs (since Linux 3.7) and tmpfs (since Linux 3.5).
-.IP "\fB\-d, \-\-dig-holes\fP"
-Detect and dig holes. Makes the file sparse in-place, without using extra disk
-space. The minimal size of the hole depends on filesystem I/O block size
-(usually 4096 bytes). Also, when using this option, \fB\-\-keep-size\fP is
-implied. If no range is specified by \fB\-\-offset\fP and \fB\-\-length\fP,
-then all file is analyzed for holes.
-
-You can think of this as doing a "\fBcp --sparse\fP" and
-renaming the dest file as the original, without the need for extra disk space.
-
-See \fB\-\-punch-hole\fP for list of the supported filesystems.
-.IP "\fB\-c, \-\-collapse-range\fP"
-Removes a byte range from a file, without leaving a hole.  The byte range
-to be collapsed starts at \fIoffset\fP and continues
-for \fIlength\fR bytes.  At the completion of the operation, the contents of
-the file starting at the location offset+length will be appended at the
-location offset, and the file will be \fIlength\fR bytes smaller. The option
-\fB\-\-keep\-size\fR may not be specified for colapse range operation.
-
-Available since Linux 3.15 for ext4 (only for extent-based files) and XFS.
-.IP "\fB\-z, \-\-zero-range\fP"
+.TP
+.BR \-v , " \-\-verbose"
+Enable verbose mode.
+.TP
+.BR \-z , " \-\-zero-range"
 Zeroes space in the byte range starting at \fIoffset\fP and
 continuing for \fIlength\fR bytes.  Within the specified range, blocks are
 preallocated for the regions that span the holes in the file.  After
 a successful call, subsequent reads from this range will return zeroes.
-
+.sp
 Zeroing is done within the filesystem preferably by converting the
 range into unwritten extents.  This approach means that the specified
 range will not be physically zeroed out on the device (except for
 partial blocks at the either end of the range), and I/O is
 (otherwise) required only to update metadata.
-
+.sp
 Option \fB\-\-keep\-size\fP can be specified to prevent file length
 modification.
-
+.sp
 Available since Linux 3.14 for ext4 (only for extent-based files) and XFS.
-.IP "\fB\-o, \-\-offset\fP \fIoffset\fP
-Specifies the beginning offset of the range, in bytes.
-.IP "\fB\-l, \-\-length\fP \fIlength\fP
-Specifies the length of the range, in bytes.
-.IP "\fB\-h, \-\-help\fP"
-Display help text and exit.
-.IP "\fB-v, \-\-verbose"
-Enable verbose mode.
-.IP "\fB-V, \-\-version"
+.TP
+.BR \-V , " \-\-version"
 Display version information and exit.
+.TP
+.BR \-h , " \-\-help"
+Display help text and exit.
 .SH AUTHORS
 .UR sandeen@redhat.com
 Eric Sandeen