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

[Max Reitz]

On 05.11.18 15:18, Kevin Wolf wrote:
> 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.

Thank you both for the quick pong. :-)

Max

signature.asc
Description: OpenPGP digital signature