Re: [PATCH 00/23] qemu-img: refersh options and --help handling

[Daniel P . Berrangé]

On Sat, Feb 10, 2024 at 12:22:21AM +0300, Michael Tokarev wrote:
> Quite big patchset implementing normal, readable qemu-img --help
> (and qemu-img COMMAND --help) output with readable descriptions,
> and adding many long options in the process.
> 
> In the end I stopped using qemu-img-opts.hx in qemu-img.c, perhaps
> this can be avoided, with only list of commands and their desrciptions
> kept there, but I don't see big advantage here.  The same list should
> be included in docs/tools/qemu-img.rst, - this is not done now.

I think it'd be nice for qemu-img.c to be the canonical source
of truth, so we have the getopt short arg, long args, and
help all in the same place & thus much less likely to get
out of sync.  Thus I like the approach you've taken here
to stop using the .hx file.

As a later work, it wouldn't be too terrible to have a python
script that parses qemu-img.c to look for 'cmd_help(...)' calls
and extra the help text, which could be used to feed into the
qemu-img.rxt man page generation, thus fully eliminating the
.hx file.

> 
> Also each command syntax isn't reflected in the doc for now, because
> I want to give good names for options first, - and there, we've quite
> some inconsistences and questions.  For example, measure --output=OFMT
> -O OFMT, - this is priceless :)  I've no idea why we have this ugly
> --output=json thing, why not have --json? ;)  I gave the desired
> format long name --target-format to avoid clash with --output.
> 
> For rebase, src vs tgt probably should be renamed in local variables
> too, and I'm not even sure I've got the caches right. For caches,
> the thing is inconsistent across commands.
> 
> For compare, I used --a-format/--b-format (for -f/-F), - this can
> be made --souce-format and --target-format, to compare source (file1)
> with target (file2).
> 
> For bitmap, things are scary, I'm not sure what -b SRC_FILENAME
> really means, - for now I gave it --source option, but this does
> not make it more clear, suggestions welcome.
> 
> There are many other inconsistencies, I can't fix them all in one
> go.. :)

This is already a massive improvement on the status quo. My
comments were mostly around whitespace/layout tweaks to the
help output.


With regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|