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

[Programmingkid <programmingkidx@gmail.com>]

> 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.