[PATCH 2/2] copyfilerange: (man) correct the markup and improve the wordings

[Benno Schulenberg <bensberg@telfort.nl>]

CC: Dick Marinus <dick@mrns.nl>
Signed-off-by: Benno Schulenberg <bensberg@telfort.nl>
---
 misc-utils/copyfilerange.1.adoc | 61 ++++++++++++++-------------------
 1 file changed, 25 insertions(+), 36 deletions(-)

diff --git a/misc-utils/copyfilerange.1.adoc b/misc-utils/copyfilerange.1.adoc
index 4d214f4db..303a1a7b2 100644
--- a/misc-utils/copyfilerange.1.adoc
+++ b/misc-utils/copyfilerange.1.adoc
@@ -4,54 +4,43 @@
 :man manual: User Commands
 :man source: util-linux {release-version}
 :page-layout: base
-:range: copyfilerange
+:command: copyfilerange
 
 == NAME
 
-copyfilerange - Copy file ranges from source to destination file.
+copyfilerange - copy range(s) from source to destination file
 
 == SYNOPSIS
 
-*copyfilerange* [options] [<source>] [<destination>] [<range>...]
+*copyfilerange* [options] _source_ _destination_ _range_...
 
 == DESCRIPTION
 
-*copyfilerange* copy file ranges from source to destination file
-*copyfilerange* is a simple utility to call the *copy_file_range*(2) system call.
+The *copyfilerange* command copies byte ranges from source to destination file.
+It is a wrapper around the *copy_file_range*(2) system call.
 
-It can be used write files with unallocated gaps (sparse files) and/or share blocks between multiple files (reflinks).
+The command can be used to create files with unallocated gaps (sparse files)
+and/or with shared blocks between multiple files (reflinks).
 
-== ARGUMENTS
+Each _range_ is of the form _source_offset_**:**_destination_offset_**:**_length_,
+with all values in bytes. If _length_ is 0, then as much data as is available is
+copied. Multiple ranges may be supplied.
 
-*source*::
-Source filename
-
-*destination*::
-Destination filename
-
-*range*::
-
-Consists of a range specified as *source_offset:dest_offset:length*
-
-All values are in bytes, if length is set to 0 copy as much as available.
-Multiple range can be supplied.
-
-When one or more of the offsets are omitted the operation will use the last used location, starting with 0
+When one or both of the offsets are omitted, the operation uses the last-used
+file location, starting with 0.
 
 == OPTIONS
 
-*-v*, *--verbose*::
-Verbose output of copied file ranges
+*-r*, *--ranges* _file_::
+Read range(s) separated by newlines from this _file_.
 
-*-r*, *--ranges*::
-Ranges filename
+*-v*, *--verbose*::
+Verbose output of the copied ranges.
 
 include::man-common/help-version.adoc[]
 
 == EXIT STATUS
 
-*copyfilerange* has the following exit status values:
-
 *0*::
 success
 *1*::
@@ -59,7 +48,7 @@ unspecified failure
 
 == NOTES
 
-The *copy_file_range*(2) system call has some serious caveats, the source and destination files must use the same filesystem type and some virtual filesystems (like procfs) won't work. *copy_file_range*(2) will use reflinks when the filesystem supports this. To use reflinks the file range most often needs to align with the filesystem block size on both the source and destination file.
+The *copy_file_range*(2) system call has some serious caveats: the source and destination files must use the same filesystem type, and some virtual filesystems (like procfs) won't work. *copy_file_range*(2) will use reflinks when the filesystem supports this. To use reflinks, the file range most often needs to align with the filesystem block size on both the source and destination file.
 
 == AUTHORS
 
@@ -68,21 +57,21 @@ mailto:dick@mrns.nl[Dick Marinus]
 == EXAMPLES
 
 ....
-~$ copyfilerange original-file reflink ::
+copyfilerange original-file reflink ::
 
-~$ copyfilerange original-file first-block ::4096
+copyfilerange original-file first-block ::4096
 
-~$ copyfilerange original-file even-blocks -r <(seq 0 8192 40960|awk '{print $1"::4096"}')
+copyfilerange original-file even-blocks -r <(seq 0 8192 40960|awk '{print $1"::4096"}')
 
-~$ copyfilerange original-file sparse-file 0:1M:1
+copyfilerange original-file sparse-file 0:1M:1
 
-~$ copyfilerange original-file split-first-mb ::1M
+copyfilerange original-file split-first-mb ::1M
 
-~$ copyfilerange original-file split-remainder 1M::
+copyfilerange original-file split-remainder 1M::
 
-~$ copyfilerange split-first-mb join ::
+copyfilerange split-first-mb join ::
 
-~$ copyfilerange split-remainder join 1M::
+copyfilerange split-remainder join 1M::
 ....
 
 == SEE ALSO
-- 
2.53.0