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

[Eric Blake <eblake@redhat.com>]

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