[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Qemu-devel] [PATCH v2 0/5] Various option help readability improvem
From: |
Kevin Wolf |
Subject: |
Re: [Qemu-devel] [PATCH v2 0/5] Various option help readability improvement suggestions |
Date: |
Mon, 5 Nov 2018 15:18:38 +0100 |
User-agent: |
Mutt/1.10.1 (2018-07-13) |
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