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

[Programmingkid]

> On Aug 17, 2018, at 9:44 AM, Eric Blake <address@hidden> 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.