diff mbox

[v2,6/7] qemu-img: clean up dd documentation

Message ID 20160826091643.15841-7-fullmanet@gmail.com (mailing list archive)
State New, archived
Headers show

Commit Message

Reda Sallahi Aug. 26, 2016, 9:16 a.m. UTC 
The dd section on qemu-img --help was a bit hard to read since it was not
well aligned. This patch fixes the display problem and also makes the
sentences on the .texi file more consistent with one another (uppercase and
conjugasion).

Signed-off-by: Reda Sallahi <fullmanet@gmail.com>
Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com>
---
 qemu-img.c    | 48 +++++++++++++++++++++++++-----------------------
 qemu-img.texi | 48 ++++++++++++++++++++++++------------------------
 2 files changed, 49 insertions(+), 47 deletions(-)

Comments

Eric Blake Sept. 13, 2016, 4:31 p.m. UTC | #1 
On 08/26/2016 04:16 AM, Reda Sallahi wrote:
> The dd section on qemu-img --help was a bit hard to read since it was not
> well aligned. This patch fixes the display problem and also makes the
> sentences on the .texi file more consistent with one another (uppercase and
> conjugasion).

s/conjugasion/conjugation/

> 
> Signed-off-by: Reda Sallahi <fullmanet@gmail.com>
> Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com>
> ---
>  qemu-img.c    | 48 +++++++++++++++++++++++++-----------------------
>  qemu-img.texi | 48 ++++++++++++++++++++++++------------------------
>  2 files changed, 49 insertions(+), 47 deletions(-)
> 


>             "List of LEVELS for dd:\n"
> -           "  'none'   surpresses everything but error messages\n"
> -           "  'noxfer' surpresses the final transfer statistics\n\n"
> +           "  'none'         surpress everything but error messages\n"
> +           "  'noxfer'       surpress the final transfer statistics\n\n"

s/surpress/suppress/ (twice)

> +           "  'fsync'        physically write output file data before"
> +           " finishing\n"
> +           "  'fdatasync'    physically write output file data before"
> +           " finishing\n"

What's the difference between these two? (fdatasync only flushes file
data, while fsync flushes ALL file metadata and is thus stronger. But
using the same wording for both lines doesn't make it obvious which one
is stronger, and I shouldn't have to resort to 'man fdatasync' to learn
the difference).


>  @item fdatasync
> -Synchronize output data just before finishing. This forces a physical write of output data.
> +Synchronizes output data just before finishing. This forces a physical write of output data.
>  @item fsync
> -Synchronize output data just before finishing. This forces a physical write of output data.
> +Synchronizes output data just before finishing. This forces a physical write of output data.

Again, mention which version is stronger.

>  @item excl
> -Err if the output file already exists.
> +Errs if the output file already exists.

s/Errs/Raises an error/

>  @item nocreat
> -Do not create the output file; the output file must already exist.
> +Does not create the output file; the output file must already exist.
>  @item sparse
> -Seek rather than write NUL output blocks.
> +Seeks rather than write NUL output blocks.
>  
>  @item iflag=@var{flags}
> -defines the flags used to read the input file. The flag list is seprated using
> +Defines the flags used to read the input file. The flag list is seprated using

s/seprated/separated/

>  commas.
>  @item oflag=@var{flags}
> -defines the flags used to write the output file. The flag list is seprated
> +Defines the flags used to write the output file. The flag list is seprated

and again

>  using commas.
>  
>  The flag list:
>  @item direct
> -direct I/O for data.
> +Direct I/O for data.
>  @item dsync
> -synchronised I/O for data.
> +Synchronised I/O for data.

Do we have a strong preference for US (-ized) vs. UK (-ised) spelling
elsewhere in this document?
diff mbox

Patch

diff --git a/qemu-img.c b/qemu-img.c
index 55977ff..207e16c 100644
--- a/qemu-img.c
+++ b/qemu-img.c
@@ -169,37 +169,39 @@  static void QEMU_NORETURN help(void)
            "  '-s' run in Strict mode - fail on different image size or sector allocation\n"
            "\n"
            "Parameters to dd subcommand:\n"
-           "  'bs=BYTES' read and write up to BYTES bytes at a time "
+           "  'bs=BYTES'     read and write up to BYTES bytes at a time "
            "(default: 512)\n"
-           "  'count=N' copy only N input blocks\n"
-           "  'if=FILE' read from FILE\n"
-           "  'of=FILE' write to FILE\n"
-           "  'skip=N' skip N bs-sized blocks at the start of input\n"
-           "  'seek=N' seek N bs-sized blocks at the start of output\n"
-           "  'conv=CONVS' do not truncate the output file\n"
+           "  'count=N'      copy only N input blocks\n"
+           "  'if=FILE'      read from FILE\n"
+           "  'of=FILE'      write to FILE\n"
+           "  'skip=N'       skip N bs-sized blocks at the start of input\n"
+           "  'seek=N'       seek N bs-sized blocks at the start of output\n"
+           "  'conv=CONVS'   do not truncate the output file\n"
            "  'iflags=FLAGS' read using the comma-separated flags list\n"
            "  'oflags=FLAGS' read using the comma-separated flags list\n"
            "  'status=LEVEL' the LEVEL of information to print to stderr\n\n"
            "List of LEVELS for dd:\n"
-           "  'none'   surpresses everything but error messages\n"
-           "  'noxfer' surpresses the final transfer statistics\n\n"
+           "  'none'         surpress everything but error messages\n"
+           "  'noxfer'       surpress the final transfer statistics\n\n"
            "List of CONVS for dd:\n"
-           "  'notrunc'   do not truncate the output file\n"
-           "  'noerror'   continue in the event of read errors\n"
-           "  'excl'      fail if output already exists\n"
-           "  'nocreat'   do not create the output file\n"
-           "  'fsync'     physically write output file data before finishing\n"
-           "  'fdatasync' physically write output file data before finishing\n"
-           "  'sync'      pad every input block with NULs\n"
-           "  'sparse'    seek rather than write the output for NUL input"
+           "  'notrunc'      do not truncate the output file\n"
+           "  'noerror'      continue in the event of read errors\n"
+           "  'excl'         fail if output already exists\n"
+           "  'nocreat'      do not create the output file\n"
+           "  'fsync'        physically write output file data before"
+           " finishing\n"
+           "  'fdatasync'    physically write output file data before"
+           " finishing\n"
+           "  'sync'         pad every input block with NULs\n"
+           "  'sparse'       seek rather than write the output for NUL input"
            " blocks\n\n"
            "List of FLAGS for dd:\n"
-           "  'direct'      use direct I/O for data\n"
-           "  'dsync'       use synchronized I/O for data\n"
-           "  'sync'        use synchronized I/O for data\n"
-           "  'count_bytes' use 'count=N' as a byte count (iflag only)\n"
-           "  'skip_bytes'  use 'skip=N' as a byte count (iflag only)\n"
-           "  'seek_bytes'  use 'seek=N' as a byte count (oflag only)\n";
+           "  'direct'       use direct I/O for data\n"
+           "  'dsync'        use synchronized I/O for data\n"
+           "  'sync'         use synchronized I/O for data\n"
+           "  'count_bytes'  use 'count=N' as a byte count (iflag only)\n"
+           "  'skip_bytes'   use 'skip=N' as a byte count (iflag only)\n"
+           "  'seek_bytes'   use 'seek=N' as a byte count (oflag only)\n";
 
     printf("%s\nSupported formats:", help_msg);
     bdrv_iterate_format(format_print, NULL);
diff --git a/qemu-img.texi b/qemu-img.texi
index c8905c6..a1a17f3 100644
--- a/qemu-img.texi
+++ b/qemu-img.texi
@@ -144,20 +144,20 @@  Parameters to dd subcommand:
 @table @option
 
 @item bs=@var{block_size}
-defines the block size
+Defines the block size
 @item count=@var{blocks}
-sets the number of input blocks to copy. In case 'iflags=count_bytes' is
+Sets the number of input blocks to copy. In case 'iflags=count_bytes' is
 specified, 'blocks' is interpreted as a byte count instead of a block count.
 @item if=@var{input}
-sets the input file
+Sets the input file
 @item of=@var{output}
-sets the output file. dd truncates the output file to zero if 'conv=notrunc'
+Sets the output file. dd truncates the output file to zero if 'conv=notrunc'
 is not specified.
 @item skip=@var{blocks}
-sets the number of input blocks to skip. In case 'iflags=skip_bytes' is
+Sets the number of input blocks to skip. In case 'iflags=skip_bytes' is
 specified, 'blocks' is interpreted as a byte count instead of a block count.
 @item seek=@var{blocks}
-sets the number of output blocks to skip. In case 'oflags=seek_bytes' is
+Sets the number of output blocks to skip. In case 'oflags=seek_bytes' is
 specified, 'blocks' is interpreted as a byte count instead of a block count.
 @item conv=@var{convs}
 Converts the input according to the conversions specified. The conversion list
@@ -165,49 +165,49 @@  is separated using commas.
 
 The conversion list:
 @item notrunc
-Make dd not truncate output file to zero.
+Makes dd not truncate output file to zero.
 @item sync
-Fill every input block size with trailing zero bytes.
+Fills every input block size with trailing zero bytes.
 @item noerror
-Continue after read failures.
+Continues after read failures.
 @item fdatasync
-Synchronize output data just before finishing. This forces a physical write of output data.
+Synchronizes output data just before finishing. This forces a physical write of output data.
 @item fsync
-Synchronize output data just before finishing. This forces a physical write of output data.
+Synchronizes output data just before finishing. This forces a physical write of output data.
 @item excl
-Err if the output file already exists.
+Errs if the output file already exists.
 @item nocreat
-Do not create the output file; the output file must already exist.
+Does not create the output file; the output file must already exist.
 @item sparse
-Seek rather than write NUL output blocks.
+Seeks rather than write NUL output blocks.
 
 @item iflag=@var{flags}
-defines the flags used to read the input file. The flag list is seprated using
+Defines the flags used to read the input file. The flag list is seprated using
 commas.
 @item oflag=@var{flags}
-defines the flags used to write the output file. The flag list is seprated
+Defines the flags used to write the output file. The flag list is seprated
 using commas.
 
 The flag list:
 @item direct
-direct I/O for data.
+Direct I/O for data.
 @item dsync
-synchronised I/O for data.
+Synchronised I/O for data.
 @item sync
-synchronised I/O for data.
+Synchronised I/O for data.
 @item count_bytes
-interpret 'count=blocks' as a byte count. Only iflag.
+Interprets 'count=blocks' as a byte count. Only iflag.
 @item skip_bytes
-interpret 'skip=blocks' as a byte count. Only iflag.
+Interprets 'skip=blocks' as a byte count. Only iflag.
 @item seek_bytes
-interpret 'seek=blocks' as a byte count. Only oflag.
+Interprets 'seek=blocks' as a byte count. Only oflag.
 
 @item status=@var{level}
-Define the level of information to print to stderr.
+Defines the level of information to print to stderr.
 @item none
 Only error messages are printed.
 @item noxfer
-Do not print the final transfer rate.
+Does not print the final transfer rate.
 
 @end table