Re: [Qemu-devel] [PATCH v2 0/5] Various option help readability improvement suggestions

[Kevin Wolf <kwolf@redhat.com>]

Am 19.10.2018 um 18:49 hat Max Reitz geschrieben:
> I noticed that with the (more or less) recent series from Marc-André the
> output of qemu-img amend -f qcow2 -o help changed to this:
> 
> $ ./qemu-img amend -f qcow2 -o help
> Creation options for 'qcow2':
> qcow2-create-opts.backing_file=str - File name of a base image
> qcow2-create-opts.backing_fmt=str - Image format of the base image
> qcow2-create-opts.cluster_size=size - qcow2 cluster size
> qcow2-create-opts.compat=str - Compatibility level (0.10 or 1.1)
> [...]
> 
> The types are a nice addition, but I didn't like having the list name
> printed in every single line (in fact, the list name does not make any
> sense here at all, because there already is a caption which reads
> "Creation options for 'qcow2'"), and I did not like the use of '=' for
> types.
> 
> In general, I don't like the robot-y appearance, which is even worse in
> things like -device virtio-blk,help, which gives you this (among
> other lines):
> 
> > virtio-blk-pci.iothread=link<iothread>
> 
> Sadly, there isn't much we can do about the "link<iothread>", so this
> series doesn't improve on that point.
> 
> What this series does do, however, is it changes these lists not to
> print the list name on every single line, but only as a caption (and for
> option lists, this caption is option, because the caller may want to
> print a custom caption that is more expressive -- as is the case for
> qemu-img amend -o help).
> 
> Consequentially, all list items are indented by two spaces to make clear
> they belong to the caption.  I can already see that some people might
> disagree on having this indentation, but I like it, so I have it in this
> series.
> 
> Furthermore, types are now enclosed by angle brackets, and the alignment
> we originally had for descriptions is restored (although now after 24
> instead of 16 characters, because every option name is now accompanied
> by indentation and a type).
> 
> 
> Thus, after this series, the amend output looks like this:
> 
> $ ./qemu-img amend -f qcow2 -o help
> Creation options for 'qcow2':
>   backing_file=<str>     - File name of a base image
>   backing_fmt=<str>      - Image format of the base image
>   cluster_size=<size>    - qcow2 cluster size
>   compat=<str>           - Compatibility level (0.10 or 1.1)
> [...]
> 
> 
> virtio-blk's list presents itself like so:
> 
> $ x86_64-softmmu/qemu-system-x86_64 -device virtio-blk,help
> virtio-blk-pci options:
>   iothread=<link<iothread>>
>   request-merging=<bool> - on/off
>   secs=<uint32>
> [...]
> 
> 
> And now we even print something when there are no options:
> 
> $ x86_64-softmmu/qemu-system-x86_64 -object can-bus,help
> There are no options for can-bus.
> 
> (Before this series, there just is no output.)
> 
> 
> As a side effect, patch 1 fixes iotest 082.

Thanks, applied to the block branch.

Kevin