[Qemu-devel] [PATCH] qemu-img.c: increase spacing between commands in documentation

[Qemu-devel] [PATCH] qemu-img.c: increase spacing between commands in documentation

[Programmingkid]

When the user uses the --help option in qemu-img, the output for the commands is very hard to read due to being so close to each other. With this patch the help for the commands is double spaced making things easier to read.

Signed-off-by: John Arbuckle <programmingkidx@gmail.com>
---
qemu-img.c | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/qemu-img.c b/qemu-img.c
index 9b7506b8ae..6a7e63435e 100644
--- a/qemu-img.c
+++ b/qemu-img.c
@@ -120,7 +120,7 @@ static void QEMU_NORETURN help(void)
           "\n"
           "Command syntax:\n"
#define DEF(option, callback, arg_string)        \
-           "  " arg_string "\n"
+           "  " arg_string "\n\n"
#include "qemu-img-cmds.h"
#undef DEF
           "\n"
-- 
2.14.3 (Apple Git-98)

Re: [Qemu-devel] [PATCH] qemu-img.c: increase spacing between commands in documentation

[Max Reitz]

[-- Attachment #1: Type: text/plain, Size: 1282 bytes --]

On 2018-07-30 23:22, John Arbuckle wrote:
> When the user uses the --help option in qemu-img, the output for the commands is very hard to read due to being so close to each other. With this patch the help for the commands is double spaced making things easier to read.
> 
> Signed-off-by: John Arbuckle <programmingkidx@gmail.com>
> ---
>  qemu-img.c | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/qemu-img.c b/qemu-img.c
> index 9b7506b8ae..6a7e63435e 100644
> --- a/qemu-img.c
> +++ b/qemu-img.c
> @@ -120,7 +120,7 @@ static void QEMU_NORETURN help(void)
>             "\n"
>             "Command syntax:\n"
>  #define DEF(option, callback, arg_string)        \
> -           "  " arg_string "\n"
> +           "  " arg_string "\n\n"
>  #include "qemu-img-cmds.h"
>  #undef DEF
>             "\n"

Ah, hm, so much for that.  Hm...  I don't quite know what to think of
this.  It does indeed improve legibility.  But the question is whether
--help should be as condensed as possible, and if the user finds it hard
to read, whether they should not just open the man page...

Then again, our --help text already has 102 lines.

Let me just think about it for a bit longer. :-)
(And see whether others have opinions.)

Max


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: [Qemu-devel] [PATCH] qemu-img.c: increase spacing between commands in documentation

[Eric Blake]

On 08/13/2018 11:56 AM, Max Reitz wrote:
> 
> Ah, hm, so much for that.  Hm...  I don't quite know what to think of
> this.  It does indeed improve legibility.  But the question is whether
> --help should be as condensed as possible, and if the user finds it hard
> to read, whether they should not just open the man page...
> 
> Then again, our --help text already has 102 lines.
> 
> Let me just think about it for a bit longer. :-)
> (And see whether others have opinions.)

And I've already expressed my opinion that it is already rather long, 
where making it longer is not necessarily making it smarter.

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | libvirt.org

Re: [Qemu-devel] [PATCH] qemu-img.c: increase spacing between commands in documentation

[Kevin Wolf]

Am 13.08.2018 um 20:19 hat Eric Blake geschrieben:
> On 08/13/2018 11:56 AM, Max Reitz wrote:
> > 
> > Ah, hm, so much for that.  Hm...  I don't quite know what to think of
> > this.  It does indeed improve legibility.  But the question is whether
> > --help should be as condensed as possible, and if the user finds it hard
> > to read, whether they should not just open the man page...
> > 
> > Then again, our --help text already has 102 lines.
> > 
> > Let me just think about it for a bit longer. :-)
> > (And see whether others have opinions.)
> 
> And I've already expressed my opinion that it is already rather long, where
> making it longer is not necessarily making it smarter.

I think if we want to improve the help text, we should split it up.

$ qemu-img --help
qemu-img version 2.12.94 (v3.0.0-rc4-5-g4fe9c3e13d-dirty)
Copyright (c) 2003-2017 Fabrice Bellard and the QEMU Project developers
usage: qemu-img [standard options] command [command options]
QEMU disk image utility

    '-h', '--help'       display this help and exit
    '-V', '--version'    output version information and exit
    '-T', '--trace'      [[enable=]<pattern>][,events=<file>][,file=<file>]
                         specify tracing options

Commands:

    amend               Change options of an existing disk image
    bench               Run benchmarks on a given disk image
    check               Check the disk image for consistency or repair it
    commit              Merge the disk image into its backing file
    ...

Run 'qemu-img <command> --help' for details.

See <https://qemu.org/contribute/report-a-bug> for how to report bugs.
More information on the QEMU project at <https://qemu.org>.

$ qemu-img check --help
usage: qemu-img check [--object objectdef] [--image-opts] [-q] [-f fmt] [--output=ofmt] [-r [leaks | all]] [-T src_cache] [-U] filename

Command parameters:
  -f        'fmt' is the disk image format. It is guessed automatically
            in most cases.

  -q        use Quiet mode - do not print any output (except errors).

  -r        tries to repair any inconsistencies that are found during the
            check. '-r leaks' repairs only cluster leaks, whereas '-r
            all' fixes all kinds of errors, with a higher risk of
            choosing the wrong fix or hiding corruption that has already
            occurred.

  -T        'src_cache' is the cache mode used to read input disk images,
            the valid options are the same as for the 'cache' option.

  --object  'objectdef' is a QEMU user creatable object definition. See
            the qemu(1) manual page for a description of the object
            properties. The most common object type is a 'secret', which
            is used to supply passwords and/or encryption keys.

  --output  'ofmt' is 'human' for human-readable output (default) or
            'json' for JSON output.

Examples:

    ...

Kevin

Re: [Qemu-devel] [PATCH] qemu-img.c: increase spacing between commands in documentation

[Eric Blake]

On 08/14/2018 03:40 AM, Kevin Wolf wrote:
>> And I've already expressed my opinion that it is already rather long, where
>> making it longer is not necessarily making it smarter.
> 
> I think if we want to improve the help text, we should split it up.
> 
> $ qemu-img --help
> qemu-img version 2.12.94 (v3.0.0-rc4-5-g4fe9c3e13d-dirty)
> Copyright (c) 2003-2017 Fabrice Bellard and the QEMU Project developers
> usage: qemu-img [standard options] command [command options]
> QEMU disk image utility
> 
>      '-h', '--help'       display this help and exit
>      '-V', '--version'    output version information and exit
>      '-T', '--trace'      [[enable=]<pattern>][,events=<file>][,file=<file>]
>                           specify tracing options
> 
> Commands:
> 
>      amend               Change options of an existing disk image
>      bench               Run benchmarks on a given disk image
>      check               Check the disk image for consistency or repair it
>      commit              Merge the disk image into its backing file
>      ...
> 
> Run 'qemu-img <command> --help' for details.
> 
> See <https://qemu.org/contribute/report-a-bug> for how to report bugs.
> More information on the QEMU project at <https://qemu.org>.

Indeed, that matches the approach that 'cvs --help' and 'git --help' 
have taken. I could live with a split along those lines as being 
something smarter.  When you want to learn the options for 'create', you 
may have to ask two different --help commands to learn everything you 
need ['--help' didn't give me enough, but told me to use 'create 
--help'], but at least you are not inundated with answers irrelevant to 
the question you are asking, so you don't have to scroll through a wall 
of text.

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | libvirt.org

Re: [Qemu-devel] [PATCH] qemu-img.c: increase spacing between commands in documentation

[Programmingkid]

> On Aug 14, 2018, at 8:55 AM, Eric Blake <eblake@redhat.com> wrote:
> 
> On 08/14/2018 03:40 AM, Kevin Wolf wrote:
>>> And I've already expressed my opinion that it is already rather long, where
>>> making it longer is not necessarily making it smarter.
>> I think if we want to improve the help text, we should split it up.
>> $ qemu-img --help
>> qemu-img version 2.12.94 (v3.0.0-rc4-5-g4fe9c3e13d-dirty)
>> Copyright (c) 2003-2017 Fabrice Bellard and the QEMU Project developers
>> usage: qemu-img [standard options] command [command options]
>> QEMU disk image utility
>>     '-h', '--help'       display this help and exit
>>     '-V', '--version'    output version information and exit
>>     '-T', '--trace'      [[enable=]<pattern>][,events=<file>][,file=<file>]
>>                          specify tracing options
>> Commands:
>>     amend               Change options of an existing disk image
>>     bench               Run benchmarks on a given disk image
>>     check               Check the disk image for consistency or repair it
>>     commit              Merge the disk image into its backing file
>>     ...
>> Run 'qemu-img <command> --help' for details.
>> See <https://qemu.org/contribute/report-a-bug> for how to report bugs.
>> More information on the QEMU project at <https://qemu.org>.
> 
> Indeed, that matches the approach that 'cvs --help' and 'git --help' have taken. I could live with a split along those lines as being something smarter.  When you want to learn the options for 'create', you may have to ask two different --help commands to learn everything you need ['--help' didn't give me enough, but told me to use 'create --help'], but at least you are not inundated with answers irrelevant to the question you are asking, so you don't have to scroll through a wall of text.

I also like the idea. It seems very organized and neat.

Re: [Qemu-devel] [PATCH] qemu-img.c: increase spacing between commands in documentation

[Programmingkid]

> On Aug 14, 2018, at 4:40 AM, Kevin Wolf <kwolf@redhat.com> wrote:
> 
> Am 13.08.2018 um 20:19 hat Eric Blake geschrieben:
>> On 08/13/2018 11:56 AM, Max Reitz wrote:
>>> 
>>> Ah, hm, so much for that.  Hm...  I don't quite know what to think of
>>> this.  It does indeed improve legibility.  But the question is whether
>>> --help should be as condensed as possible, and if the user finds it hard
>>> to read, whether they should not just open the man page...
>>> 
>>> Then again, our --help text already has 102 lines.
>>> 
>>> Let me just think about it for a bit longer. :-)
>>> (And see whether others have opinions.)
>> 
>> And I've already expressed my opinion that it is already rather long, where
>> making it longer is not necessarily making it smarter.
> 
> I think if we want to improve the help text, we should split it up.
> 
> $ qemu-img --help
> qemu-img version 2.12.94 (v3.0.0-rc4-5-g4fe9c3e13d-dirty)
> Copyright (c) 2003-2017 Fabrice Bellard and the QEMU Project developers
> usage: qemu-img [standard options] command [command options]
> QEMU disk image utility
> 
>    '-h', '--help'       display this help and exit
>    '-V', '--version'    output version information and exit
>    '-T', '--trace'      [[enable=]<pattern>][,events=<file>][,file=<file>]
>                         specify tracing options
> 
> Commands:
> 
>    amend               Change options of an existing disk image
>    bench               Run benchmarks on a given disk image
>    check               Check the disk image for consistency or repair it
>    commit              Merge the disk image into its backing file
>    ...
> 
> Run 'qemu-img <command> --help' for details.
> 
> See <https://qemu.org/contribute/report-a-bug> for how to report bugs.
> More information on the QEMU project at <https://qemu.org>.
> 
> $ qemu-img check --help
> usage: qemu-img check [--object objectdef] [--image-opts] [-q] [-f fmt] [--output=ofmt] [-r [leaks | all]] [-T src_cache] [-U] filename
> 
> Command parameters:
>  -f        'fmt' is the disk image format. It is guessed automatically
>            in most cases.
> 
>  -q        use Quiet mode - do not print any output (except errors).
> 
>  -r        tries to repair any inconsistencies that are found during the
>            check. '-r leaks' repairs only cluster leaks, whereas '-r
>            all' fixes all kinds of errors, with a higher risk of
>            choosing the wrong fix or hiding corruption that has already
>            occurred.
> 
>  -T        'src_cache' is the cache mode used to read input disk images,
>            the valid options are the same as for the 'cache' option.
> 
>  --object  'objectdef' is a QEMU user creatable object definition. See
>            the qemu(1) manual page for a description of the object
>            properties. The most common object type is a 'secret', which
>            is used to supply passwords and/or encryption keys.
> 
>  --output  'ofmt' is 'human' for human-readable output (default) or
>            'json' for JSON output.
> 
> Examples:
> 
>    ...
> 
> Kevin


I am by no means an expert at qemu-img. But I did try my best to create what I think should be the new output for qemu-img <command> --help. This is just the text I plan on using in a future patch. It is easier to read right now than it will be in patch form, so please let me know if there are any errors in this documentation. Thank you.


<amend>

usage: qemu-img amend [--object objectdef] [--image-opts] [-p] [-q] [-f fmt]
[-t cache] -o options filename

Command parameters:
 -f             'fmt' is the disk image format. It is guessed automatically
                in most cases.

--image-opts    Treat filename as a set of image options, instead of a plain
                filename.

 -o             Used with a comma separated list of format specific options in a
                name=value format. Use "-o ?" for an overview of the options
                supported by the used format

--object        'objectdef' is a QEMU user creatable object definition. See the
                qemu(1) manual page for a description of the object properties.
                The most common object type is a 'secret', which is used to
                supply passwords and/or encryption keys.

 -p             Display progress bar. If the -p option is not used for a command
                that supports it, the progress is reported when the process
                receives a "SIGUSR1" signal.

 -q             Quiet mode - do not print any output (except errors). There's no
                progress bar in case both -q and -p options are used.

 -t             Specifies the cache mode that should be used with the
                destination file.

Example:
    qemu-img amend -o compat=0.10 -f qcow2 image.qcow2


<bench>

usage: qemu-img bench [-c count] [-d depth] [-f fmt]
[--flush-interval=flush_interval] [-n] [--no-drain] [-o offset]
[--pattern=pattern] [-q] [-s buffer_size] [-S step_size] [-t cache] [-w] [-U]
filename

Command parameters:
 -c                  Number of I/O requests to perform.

 -d                  Number of I/O requests done in parallel.

 -f                  fmt' is the disk image format. It is guessed automatically
                     in most cases.

 --flush-interval    How often a flush should take place.

 -n                  Use native AIO backend if possible.

 --no-drain          Issue a flush without draining the request queue first.

 -o                  The starting position.

 --pattern           The byte pattern used to in write tests.

 -q                  Quiet mode - do not print any output (except errors).
                     There's no progress bar in case both -q and -p options are
                     used.

 -s                  buffer_size in bytes.

 -S                  Increases current position by step_size.

 -t                  Specifies the cache mode that should be used with the
                     destination file.

 -w                  Perform write test.

 -U                  Open the image in shared mode, allowing other QEMU
                     processes to open it in write mode. This option is only
                     allowed when opening images in read-only mode.

Example:
    qemu-img bench -c 20000 -d 50000 -f qcow2 image.qcow2


<check>

usage: qemu-img check [--object objectdef] [--image-opts] [-q] [-f fmt]
[--output=ofmt] [-r [leaks | all]] [-T src_cache] [-U] filename

Command parameters:
 -f         'fmt' is the disk image format. It is guessed automatically in most
            cases.

 -q         Use Quiet mode - do not print any output (except errors).

 -r         Tries to repair any inconsistencies that are found during the check.
            '-r leaks' repairs only cluster leaks, whereas '-r all' fixes all
            kinds of errors, with a higher risk of choosing the wrong fix or
            hiding corruption that has already occurred.

 -T         'src_cache' is the cache mode used to read input disk images, the
            valid options are the same as for the 'cache' option.

 --object   'objectdef' is a QEMU user creatable object definition. See the
            qemu(1) manual page for a description of the object properties. The
            most common object type is a 'secret', which is used to supply
            passwords and/or encryption keys.

 --output   'ofmt' is 'human' for human-readable output (default) or 'json' for
            JSON output.

Example:
    qemu-img check image.qcow2


<commit>

usage: qemu-img commit [--object objectdef] [--image-opts] [-q] [-f fmt]
[-t cache] [-b base] [-d] [-p] filename

Command parameters:
 -b            The base image or backing file.

 -d            Skip emptying filename.

 -f            'fmt' is the disk image format. It is guessed automatically
               in most cases.

 --image-opts  Treat filename as a set of image options, instead of a plain
               filename.

 --object      'objectdef' is a QEMU user creatable object definition. See the
               qemu(1) manual page for a description of the object properties.
               The most common object type is a 'secret', which is used to
               supply passwords and/or encryption keys.

 -p            Display progress bar. If the -p option is not used for a command
               that supports it, the progress is reported when the process
               receives a "SIGUSR1" signal.

 -q            Quiet mode - do not print any output (except errors). There's no
               progress bar in case both -q and -p options are used.

 -t            Specifies the cache mode that should be used with the
               destination file.

Example:
    qemu-img commit image.qcow2


<compare>

usage: qemu-img compare [--object objectdef] [--image-opts] [-f fmt] [-F fmt]
[-T src_cache] [-p] [-q] [-s] [-U] filename1 filename2

Command parameters:
 -f                 First image format.

 -F                 Second image format.

 --image-opts       Treat filename as a set of image options, instead of a plain
                    filename.

 -T                 Specifies the cache mode that should be used with the source
                    file.

 --object           'objectdef' is a QEMU user creatable object definition. See
                    the qemu(1) manual page for a description of the object
                    properties. The most common object type is a 'secret', which
                    is used to supply passwords and/or encryption keys.

 -p                 Display progress bar. If the -p option is not used for a
                    command that supports it, the progress is reported when the
                    process receives a "SIGUSR1" signal.

 -q                 Quiet mode - do not print any output (except errors).
                    There's no progress bar in case both -q and -p options are
                    used.

 -s                 Enable strict mode. Comparisons differ when image sizes
                    differ or if a sector is allocated in one image and not
                    allocated in the other image.

 -U                 Open the image in shared mode, allowing other QEMU
                    processes to open it in write mode. This option is only
                    allowed when opening images in read-only mode.

Example:
    qemu-img compare image1.qcow image2.qcow2


<convert>

usage: qemu-img convert [--object objectdef] [--image-opts]
[--target-image-opts] [-U] [-c] [-p] [-q] [-n] [-f fmt] [-t cache]
[-T src_cache] [-O output_fmt] [-B backing_file] [-o options]
[-s snapshot_id_or_name] [-l snapshot_param] [-S sparse_size]
[-m num_coroutines] [-W] filename [filename2 [...]] output_filename

Command parameters:
 -B                      Force the output image to be created as a copy on write
                         image of the specified base image.

 -c                      Compress the output image file.

 -f                      'fmt' is the disk image format. It is guessed
                         automatically in most cases.

 --image-opts            Indicates that the source filename parameter is to be
                         interpreted as a full option string, not a plain
                         filename.

 -l                      Specifies a snapshot parameter.

 -m                      Number of parallel coroutines for the convert process

 -n                      Skip the creation of the target volume.

 -O                      Format of the output file.

 -o                      Allows for specifying options like virtual disk size.

 --object                'objectdef' is a QEMU user creatable object definition.
                         See the qemu(1) manual page for a description of the
                         object properties. The most common object type is a
                         'secret', which is used to supply passwords and/or
                         encryption keys.

 -p                      Display progress bar. If the -p option is not used for
                         a command that supports it, the progress is reported
                         when the process receives a "SIGUSR1" signal.

 -q                      Quiet mode - do not print any output (except errors).
                         There's no progress bar in case both -q and -p options
                         are used.

 -S                      The consecutive number of bytes (defaults to 4k) that
                         must contain only zeros for qemu-img to create a sparse
                         image during conversion.

 -s                      The name or ID of the snapshot to use.

 -T                      Specifies the cache mode that should be used with the
                         source file.

 -t                      Specifies the cache mode that should be used with the
                         destination file.

--target-image-opts      Indicates whether the source filename includes options.

 -U                      Open the image in shared mode, allowing other QEMU
                         processes to open it in write mode. This option is only
                         allowed when opening images in read-only mode.

 -W                      Allow out-of-order writes to the destination. This
                         option improves performance, but is only recommended
                         for preallocated devices like host devices or other raw
                         block devices.

Example:
    qemu-img convert -f raw -O qcow2 image.img image.qcow2


<create>

usage: qemu-img create [--object objectdef] [-q] [-f fmt] [-b backing_file]
[-F backing_fmt] [-u] [-o options] filename [size]

Command parameters:
 -b             The backing file used to base the output file on.

 -f             The format of the output file.

 -F             The format of the backing file.

 -u             Create the image file even if the backing file cannot be opened.

 -o             Allows for specifying options like virtual disk size.

--object        'objectdef' is a QEMU user creatable object definition.
                See the qemu(1) manual page for a description of the
                object properties. The most common object type is a
                'secret', which is used to supply passwords and/or
                encryption keys.

Example:
    qemu-img create -f qcow2 image.qcow2 10G


<dd>

usage: qemu-img dd [-f fmt] [-O output_fmt] [bs=block_size] [count=blocks]
[skip=blocks] if=input of=output

Command parameters:
 bs                 Size of the blocks used in reading and writing (512 bytes is
                    the default).

 count              The limit to how many blocks to read.

 -f                 Format of the input file.

 if                 The input file.

 -O                 Format of the output file.

 of                 The output file.

 skip               Number of blocks to skip.

Example:
    qemu-img dd if=/dev/cdrom -O raw of=cd.iso


<info>

usage: qemu-img info [-f fmt] [--output=ofmt] [--backing-chain] filename

Command parameters:
 --backing-chain            Recursively enumerate thru each disk image in the
                            chain for information.

 -f                         The format of image file specified by filename.

--output                    The output format of this command. Can be "human" or
                            "json".

Example:
    qemu-img info image.qcow2


<map>

usage: qemu-img map [-f fmt] [--output=ofmt] filename

Command parameters:
 -f                 The format of the image file specified by filename.

--output            The output format of this command. Can be "human" or "json".

Example:
    qemu-img map image.qcow2


<measure>

usage: qemu-img measure [--output=ofmt] [-O output_fmt] [-o options] [--size N ]
[--object objectdef] [--image-opts] [-f fmt] [-l snapshot_param]
filename

Command parameters:
 -f                 'fmt' is the disk image format. It is guessed
                    automatically in most cases.

 --image-opts       Indicates that the source filename parameter is to be
                    interpreted as a full option string, not a plain
                    filename.

 -l                 Specifies a snapshot parameter.

 -O                 Format of the output file.

 -o                 Allows for specifying options.

 --object           'objectdef' is a QEMU user creatable object definition. See
                    the qemu(1) manual page for a description of the object
                    properties. The most common object type is a 'secret',
                    which is used to supply passwords and/or encryption keys.

 --output           'ofmt' is 'human' for human-readable output (default) or
                    'json' for JSON output.

 --size             If given act as if creating a new empty image file using
                    qemu-img create.

Example:
    qemu-img measure -O qcow2 --size 5G


<Snapshot>

usage: qemu-img snapshot [-l | -a snapshot | -c snapshot | -d snapshot ]
filename

Command parameters:
 -a                 Applies the snapshot.

 -c                 Create a snapshot.

 -d                 Deletes a snapshot.

 -l                 Lists all snapshots

Example:
    qemu-img snapshot -l image.qcow2


<Rebase>

usage: qemu-img rebase [-f fmt] [-t cache] [-T src_cache] [-p] [-u] -b
backing_file [-F backing_fmt] filename

Command parameters:
 -b         The new backing file.

 -F         The format for the new backing file.

 -f         'fmt' is the disk image format. It is guessed automatically in most
            cases.

 -T         Specifies the cache mode that should be used with the source file.

 -t         Specifies the cache mode that should be used with the destination
            file.

 -p         Display progress bar. If the -p option is not used for a command
            that supports it, the progress is reported when the process
            receives a "SIGUSR1" signal.

 -u         Operate in unsafe mode.

Example:
    qemu-img rebase -b backing.img diff.qcow2


<Resize>

usage: qemu-img resize [--shrink] [--preallocation=prealloc] filename
[+ | -] size

Command parameters:
 --preallocation    When growing an image, specify how the additional image
                    area should be allocated on the host.

 --shrink           Informs qemu-img that the user acknowledges all loss of
                    data beyond the truncated image's end.

Example:
    qemu-img resize image.qcow2 20G

Re: [Qemu-devel] [PATCH] qemu-img.c: increase spacing between commands in documentation

[Eric Blake]

On 08/16/2018 08:27 PM, Programmingkid wrote:

> I am by no means an expert at qemu-img. But I did try my best to create what I think should be the new output for qemu-img <command> --help. This is just the text I plan on using in a future patch. It is easier to read right now than it will be in patch form, so please let me know if there are any errors in this documentation. Thank you.
> 
> 
> <amend>
> 

Just reviewing the first for now, to give you a feel for what to consider.

> usage: qemu-img amend [--object objectdef] [--image-opts] [-p] [-q] [-f fmt]
> [-t cache] -o options filename
> 
> Command parameters:
>   -f             'fmt' is the disk image format. It is guessed automatically
>                  in most cases.

Bad advice. We WANT users to use -f (if you don't, and the automatic 
guessing sees something that is not raw, but your image SHOULD have been 
-f raw, then you have a security hole: the guest can write anything into 
a raw image to make the host access files it shouldn't based on 
interpreting the raw file as something else).  I'd drop the last 
sentence, and use just the first.

> 
> --image-opts    Treat filename as a set of image options, instead of a plain
>                  filename.
> 
>   -o             Used with a comma separated list of format specific options in a
>                  name=value format. Use "-o ?" for an overview of the options

Please spell that "-o help", not "-o ?".   Otherwise, the user has to 
quote the ? to avoid it globbing into any single-byte file lying around 
in the current directory.

>                  supported by the used format
> 
> --object        'objectdef' is a QEMU user creatable object definition. See the
>                  qemu(1) manual page for a description of the object properties.
>                  The most common object type is a 'secret', which is used to
>                  supply passwords and/or encryption keys.
> 
>   -p             Display progress bar. If the -p option is not used for a command
>                  that supports it, the progress is reported when the process
>                  receives a "SIGUSR1" signal.
> 
>   -q             Quiet mode - do not print any output (except errors). There's no
>                  progress bar in case both -q and -p options are used.

Not your fault, but I don't like it when interfaces take mutually 
exclusive operations but the last one does not win.  Either '-p -q' 
should behave like '-q', and '-q -p' behave like '-p' (because we accept 
the mutual exclusion but last one wins), or both forms should error 
(because they are incompatible).  But having both forms silently behave 
like '-q' is evil.  So, as long as you're willing to patch up 
interfaces, that's a project to consider.

> 
>   -t             Specifies the cache mode that should be used with the
>                  destination file.

And what are those modes?  If you're going to be wordy, then give the 
user enough information to be useful.  Otherwise, being terse in --help 
is fine (and let the man page be wordy instead).
> 
> Example:
>      qemu-img amend -o compat=0.10 -f qcow2 image.qcow2

Where's an example with --image-opts and --object secret?

We're trying to move away from compat=0.10 (also spelled compat=v2), and 
instead start encouraging compat=v3.

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | libvirt.org

Re: [Qemu-devel] [PATCH] qemu-img.c: increase spacing between commands in documentation

[Programmingkid]

> On Aug 17, 2018, at 9:44 AM, Eric Blake <eblake@redhat.com> wrote:
> 
> On 08/16/2018 08:27 PM, Programmingkid wrote:
> 
>> I am by no means an expert at qemu-img. But I did try my best to create what I think should be the new output for qemu-img <command> --help. This is just the text I plan on using in a future patch. It is easier to read right now than it will be in patch form, so please let me know if there are any errors in this documentation. Thank you.
>> <amend>
> 
> Just reviewing the first for now, to give you a feel for what to consider.
> 
>> usage: qemu-img amend [--object objectdef] [--image-opts] [-p] [-q] [-f fmt]
>> [-t cache] -o options filename
>> Command parameters:
>>  -f             'fmt' is the disk image format. It is guessed automatically
>>                 in most cases.
> 
> Bad advice. We WANT users to use -f (if you don't, and the automatic guessing sees something that is not raw, but your image SHOULD have been -f raw, then you have a security hole: the guest can write anything into a raw image to make the host access files it shouldn't based on interpreting the raw file as something else).  I'd drop the last sentence, and use just the first.

Ok. 

> 
>> --image-opts    Treat filename as a set of image options, instead of a plain
>>                 filename.
>>  -o             Used with a comma separated list of format specific options in a
>>                 name=value format. Use "-o ?" for an overview of the options
> 
> Please spell that "-o help", not "-o ?".   Otherwise, the user has to quote the ? to avoid it globbing into any single-byte file lying around in the current directory.

"-o ?" and "-o help" does not appear to work for this command. Maybe it should be removed.
This is what I tried:
	qemu-img amend -o help
	qemu-img amend -o ?

This is what I see in both instances: qemu-img: Expecting one image file name

> 
>>                 supported by the used format
>> --object        'objectdef' is a QEMU user creatable object definition. See the
>>                 qemu(1) manual page for a description of the object properties.
>>                 The most common object type is a 'secret', which is used to
>>                 supply passwords and/or encryption keys.
>>  -p             Display progress bar. If the -p option is not used for a command
>>                 that supports it, the progress is reported when the process
>>                 receives a "SIGUSR1" signal.
>>  -q             Quiet mode - do not print any output (except errors). There's no
>>                 progress bar in case both -q and -p options are used.
> 
> Not your fault, but I don't like it when interfaces take mutually exclusive operations but the last one does not win.  Either '-p -q' should behave like '-q', and '-q -p' behave like '-p' (because we accept the mutual exclusion but last one wins), or both forms should error (because they are incompatible).  But having both forms silently behave like '-q' is evil.  So, as long as you're willing to patch up interfaces, that's a project to consider.
> 
>>  -t             Specifies the cache mode that should be used with the
>>                 destination file.
> 
> And what are those modes?  If you're going to be wordy, then give the user enough information to be useful.  Otherwise, being terse in --help is fine (and let the man page be wordy instead).

I don't know what the modes are. Anyone care to fill us in? 


>> Example:
>>     qemu-img amend -o compat=0.10 -f qcow2 image.qcow2
> 
> Where's an example with --image-opts and --object secret?

I prefer examples that I think a user would actually use. The --image-opts and -object options are not necessary to use this command.

> We're trying to move away from compat=0.10 (also spelled compat=v2), and instead start encouraging compat=v3.

So you want this: qemu-img amend -o compat=v3 -f qcow2 image.qcow2

Thank you for reviewing my documentation.

Re: [Qemu-devel] [PATCH] qemu-img.c: increase spacing between commands in documentation

[Eric Blake]

On 08/17/2018 02:28 PM, Programmingkid wrote:

>>>   -o             Used with a comma separated list of format specific options in a
>>>                  name=value format. Use "-o ?" for an overview of the options
>>
>> Please spell that "-o help", not "-o ?".   Otherwise, the user has to quote the ? to avoid it globbing into any single-byte file lying around in the current directory.
> 
> "-o ?" and "-o help" does not appear to work for this command. Maybe it should be removed.
> This is what I tried:
> 	qemu-img amend -o help
> 	qemu-img amend -o ?

The set of options depends on the file format being amended.  So, you 
have to try:

qemu-img amend -o help -f qcow2

or supply an image name, as in:

qemu-img amend -o help myimage.qcow2

(of course, the latter relies on image probing, which I just said is 
potentially unsafe if you didn't use -f).  But the point is the option 
-o does work, just not in isolation.


>>>   -t             Specifies the cache mode that should be used with the
>>>                  destination file.
>>
>> And what are those modes?  If you're going to be wordy, then give the user enough information to be useful.  Otherwise, being terse in --help is fine (and let the man page be wordy instead).
> 
> I don't know what the modes are. Anyone care to fill us in?

The source code is your friend. qemu-img.c has:

        case 'T':
             cache = optarg;
...
     ret = bdrv_parse_cache_mode(cache, &flags, &writethrough);

then you search for bdrv_parse_cache_mode(), in block.c:

     if (!strcmp(mode, "off") || !strcmp(mode, "none")) {
         *writethrough = false;
         *flags |= BDRV_O_NOCACHE;
     } else if (!strcmp(mode, "directsync")) {
         *writethrough = true;
         *flags |= BDRV_O_NOCACHE;
     } else if (!strcmp(mode, "writeback")) {
         *writethrough = false;
     } else if (!strcmp(mode, "unsafe")) {
         *writethrough = false;
         *flags |= BDRV_O_NO_FLUSH;
     } else if (!strcmp(mode, "writethrough")) {
         *writethrough = true;

So six different aliases, for five different modes.  We can either 
improve --help output to document these directly, or add a '-t help' 
option (the way we have '-o help') to dynamically print the list.

> 
> 
>>> Example:
>>>      qemu-img amend -o compat=0.10 -f qcow2 image.qcow2
>>
>> Where's an example with --image-opts and --object secret?
> 
> I prefer examples that I think a user would actually use. The --image-opts and -object options are not necessary to use this command.

Umm, they ARE necessary if you want to amend a LUKS-encrypted image, and 
that IS something I would actually use.  What's more, it's the complex 
examples (like a LUKS-encrypted image) where seeing something spelled 
out will save a LOT of hair-pulling from someone reading the docs (but, 
alongside it should ALSO be a short-and-simple example).

> 
>> We're trying to move away from compat=0.10 (also spelled compat=v2), and instead start encouraging compat=v3.
> 
> So you want this: qemu-img amend -o compat=v3 -f qcow2 image.qcow2

Yes, that's one reasonable example, but should not be the only example.

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | libvirt.org

Re: [Qemu-devel] [PATCH] qemu-img.c: increase spacing between commands in documentation

[Programmingkid]

> On Aug 17, 2018, at 4:59 PM, Eric Blake <eblake@redhat.com> wrote:
> 
> On 08/17/2018 02:28 PM, Programmingkid wrote:
> 
>>>>  -o             Used with a comma separated list of format specific options in a
>>>>                 name=value format. Use "-o ?" for an overview of the options
>>> 
>>> Please spell that "-o help", not "-o ?".   Otherwise, the user has to quote the ? to avoid it globbing into any single-byte file lying around in the current directory.
>> "-o ?" and "-o help" does not appear to work for this command. Maybe it should be removed.
>> This is what I tried:
>> 	qemu-img amend -o help
>> 	qemu-img amend -o ?
> 
> The set of options depends on the file format being amended.  So, you have to try:
> 
> qemu-img amend -o help -f qcow2
> 
> or supply an image name, as in:
> 
> qemu-img amend -o help myimage.qcow2
> 
> (of course, the latter relies on image probing, which I just said is potentially unsafe if you didn't use -f).  But the point is the option -o does work, just not in isolation.
> 
> 
>>>>  -t             Specifies the cache mode that should be used with the
>>>>                 destination file.
>>> 
>>> And what are those modes?  If you're going to be wordy, then give the user enough information to be useful.  Otherwise, being terse in --help is fine (and let the man page be wordy instead).
>> I don't know what the modes are. Anyone care to fill us in?
> 
> The source code is your friend. qemu-img.c has:
> 
>       case 'T':
>            cache = optarg;
> ...
>    ret = bdrv_parse_cache_mode(cache, &flags, &writethrough);
> 
> then you search for bdrv_parse_cache_mode(), in block.c:
> 
>    if (!strcmp(mode, "off") || !strcmp(mode, "none")) {
>        *writethrough = false;
>        *flags |= BDRV_O_NOCACHE;
>    } else if (!strcmp(mode, "directsync")) {
>        *writethrough = true;
>        *flags |= BDRV_O_NOCACHE;
>    } else if (!strcmp(mode, "writeback")) {
>        *writethrough = false;
>    } else if (!strcmp(mode, "unsafe")) {
>        *writethrough = false;
>        *flags |= BDRV_O_NO_FLUSH;
>    } else if (!strcmp(mode, "writethrough")) {
>        *writethrough = true;
> 
> So six different aliases, for five different modes.  We can either improve --help output to document these directly, or add a '-t help' option (the way we have '-o help') to dynamically print the list.
> 
>>>> Example:
>>>>     qemu-img amend -o compat=0.10 -f qcow2 image.qcow2
>>> 
>>> Where's an example with --image-opts and --object secret?
>> I prefer examples that I think a user would actually use. The --image-opts and -object options are not necessary to use this command.
> 
> Umm, they ARE necessary if you want to amend a LUKS-encrypted image, and that IS something I would actually use.  What's more, it's the complex examples (like a LUKS-encrypted image) where seeing something spelled out will save a LOT of hair-pulling from someone reading the docs (but, alongside it should ALSO be a short-and-simple example).
> 
>>> We're trying to move away from compat=0.10 (also spelled compat=v2), and instead start encouraging compat=v3.
>> So you want this: qemu-img amend -o compat=v3 -f qcow2 image.qcow2
> 
> Yes, that's one reasonable example, but should not be the only example.

Here is an improved version of the amend documentation:

usage: qemu-img amend [--object objectdef] [--image-opts] [-p] [-q] [-f fmt]
[-t cache] -o options filename

Command parameters:
 -f             The format of the image file.

--image-opts    Treat filename as a set of image options, instead of a plain
                filename.

 -o             Used with a comma separated list of format specific options in a
                name=value format. Use "-o help" for an overview of the options
                supported by the used format.

--object        'objectdef' is a QEMU user creatable object definition. See the
                qemu(1) manual page for a description of the object properties.
                The most common object type is a 'secret', which is used to
                supply passwords and/or encryption keys.

 -p             Display progress bar. If the -p option is not used for a command
                that supports it, the progress is reported when the process
                receives a "SIGUSR1" signal. Avoid using with the -q option.

 -q             Quiet mode - do not print any output (except errors). Avoid
                using with the -p option.

 -t             Specifies the cache mode that should be used with the
                destination file. Options are: none, writeback, writethrough,
                directsync, and unsafe.

Example:
    qemu-img amend -o compat=v3 -f qcow2 image.qcow2
    qemu-img amend --object secret,id=sec0,data=test --image-opts \
    driver=luks,key-secret=sec0,file.filename=test.luks -o size=2G