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

[Eric Blake <eblake@redhat.com>]

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