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

[Programmingkid <programmingkidx@gmail.com>]

> 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