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

[Max Reitz <mreitz@redhat.com>]

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, '=' for types is changed to ': '.


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
[...]

(which is still not perfect, but at least it no longer looks like it's
been generated for consumption by libvirt)


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.


Max Reitz (5):
  option: Make option help nicer to read
  chardev: Indent list of chardevs
  qdev-monitor: Make device options help nicer
  object: Make option help nicer to read
  fw_cfg: Drop newline in @file description

 include/qemu/option.h      |   2 +-
 chardev/char.c             |   2 +-
 qdev-monitor.c             |   7 +-
 qemu-img.c                 |   4 +-
 util/qemu-option.c         |  31 +-
 vl.c                       |  14 +-
 tests/qemu-iotests/082.out | 956 ++++++++++++++++++-------------------
 7 files changed, 521 insertions(+), 495 deletions(-)

-- 
2.17.1