Re: [Qemu-trivial] [Qemu-block] [PATCH 0/5] qemu-img: make subcommand usage docstrings consistent

[Max Reitz <mreitz@redhat.com>]

[-- Attachment #1.1: Type: text/plain, Size: 4666 bytes --]

On 2018-05-04 03:03, John Snow wrote:
> On 05/03/2018 06:56 PM, John Snow wrote:
>> I'm working on a project to attempt to autogenerate all of this, but
>> until then let's just do a bit of the usual kinds of tidying.
>>
>> ________________________________________________________________________________
>>
>> For convenience, this branch is available at:
>> https://github.com/jnsnow/qemu.git branch trivial-qemu-img
>> https://github.com/jnsnow/qemu/tree/trivial-qemu-img
>>
>> This version is tagged trivial-qemu-img-v1:
>> https://github.com/jnsnow/qemu/releases/tag/trivial-qemu-img-v1
>>
>> John Snow (5):
>>   qemu-img-commands.hx: argument ordering fixups
>>   qemu-img.texi: fix command ordering
>>   qemu-img: remove references to GEN_DOCS
>>   qemu-img: Make documentation between .texi and .hx consistent
>>   qemu-img-cmds.hx: add passive-aggressive note
>>
>>  qemu-img-cmds.hx       | 13 +++++----
>>  qemu-img.c             |  2 --
>>  qemu-img.texi          | 78 ++++++++++++++++++++++++++------------------------
>>  qemu-options-wrapper.h |  1 -
>>  4 files changed, 48 insertions(+), 46 deletions(-)
>>
> 
> Possessed by some kind of malevolent phantasm, I documented the following:
> 
> amend	 [--object objectdef] [--image-opts] [-q] [-f fmt]      filename
> bench                                        [-q] [-f fmt] [-U] filename
> check    [--object objectdef] [--image-opts] [-q] [-f fmt] [-U] filename
> commit   [--object objectdef] [--image-opts] [-q] [-f fmt]      filename
> compare  [--object objectdef] [--image-opts] [-q] [-f fmt] [-U] filename
> convert  [--object objectdef] [--image-opts] [-q] [-f fmt] [-U] filename
> create   [--object objectdef]                [-q] [-f fmt]      filename
> dd                            [--image-opts]      [-f fmt] [-U]
> info     [--object objectdef] [--image-opts]      [-f fmt] [-U] filename
> map      [--object objectdef] [--image-opts]      [-f fmt] [-U] filename
> measure  [--object objectdef] [--image-opts]      [-f fmt]      filename
> snapshot [--object objectdef] [--image-opts] [-q]          [-U] filename
> rebase   [--object objectdef] [--image-opts] [-q] [-f fmt] [-U] filename
> resize   [--object objectdef] [--image-opts] [-q] [-f fmt]      filename
> 
> These are the largely universal set of options we support on most
> commands, except sometimes some commands don't support them. Maybe
> that's intentional, Maybe it isn't:
> 
> - Maybe we don't really want -U on commands that are opened RDWR.

Sounds reasonable to me.

> - Maybe -f fmt isn't useful on snapshot or amend (which only work for
> qcow2?)

But amend does have -f fmt.  I suppose snapshot should as well.

> - Maybe -q is inherently pretty useless for commands like info, map, or
> measure whose job is to show you something.

I suppose so, too.  If it was an option, it just wouldn’t do anything.
That’s OK to me if you plan to add it as a global option, but it isn’t
really useful.

> Less clear to me:
> 
> - Is there no place for --image-opts for create?

Not yet.  When x-blockdev-create loses its x-, it might be the time to
change that.

The same holds true for convert, by the way.  Its --image-opts is only
usable for the source, but there is no --target-image-opts.  That’s
because currently you always need a filename for image creation, and you
just can give some creation options in addition (through -o).

It might be useful for bench, but that’s debugging anyway, so I don’t
really care.

> - Or --object for dd?

I’d rather not see any changes to dd.  Actually, I’d rather not see dd
at all, but that’s a personal opinion.

I’ve always wanted to merge dd’s functionality into convert, so the less
it can do until then, the better, I suppose.  (Though of course I’ve
never had the time to attack this issue, as usual.)

> - Or either of these two for bench?

Again, it’s solely for debugging, so feel free to go wild, but there’s
no actual need to support it until any of us developers wants to use it
with luks.

Shouldn’t be that hard, anyway.

Max

> The thought, though, is to define some core set of options that will
> always apply to all commands. It might not always be perfect, but the
> arguments listed here are a start for what probably makes sense for most
> commands. Maybe it's a bad idea; but maybe individual parsers could opt
> out of the common set of arguments on an as-needed basis instead.
> 
> Might help the documentation along to be able to point to some
> definitely universal core group of options.
> 
> --js
> 
> 



[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 488 bytes --]