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

[Eric Blake]

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