Re: [PATCH 23/23] qemu-img: inline list of supported commands, remove qemu-img-cmds.h include

[Daniel P . Berrangé]

On Wed, Feb 21, 2024 at 07:31:42PM +0300, Michael Tokarev wrote:
> 20.02.2024 21:48, Daniel P. Berrangé:
> 
> > This ends up looking a bit muddled together. I don't think we
> > need repeat 'qemu-img <cmd>' twice, and could add a little
> > more whitespace
> > 
> > eg instead of:
> > 
> > $ ./build/qemu-img check --help
> > qemu-img check: Check basic image integrity.  Usage:
> > qemu-img check [-f FMT | --image-opts] [-T CACHE_MODE] [-r] [-u]
> >          [--output human|json] [--object OBJDEF] FILENAME
> > Arguments:
> > ...snip...
> > 
> > have it look like
> > 
> > $ ./build/qemu-img check --help
> > Check basic image integrity.
> > 
> > Usage:
> > 
> >    qemu-img check [-f FMT | --image-opts] [-T CACHE_MODE] [-r] [-u]
> >          [--output human|json] [--object OBJDEF] FILENAME
> > 
> > Arguments:
> > ...snip...
> 
> Here's the current way how `create' help text looks like:
> 
> $ ./qemu-img create --help
> Create and format qemu image file.  Usage:
>   qemu-img create [-f FMT] [-o FMT_OPTS] [-b BACKING_FILENAME [-F 
> BACKING_FMT]]
>         [--object OBJDEF] [-u] FILENAME [SIZE[bkKMGTPE]]
> Arguments:
>   -h, --help
>      print this help and exit
>   -q, --quiet
>      quiet operations
>   -f, --format FMT
>      specifies format of the new image, default is raw
>   -o, --options FMT_OPTS
>      format-specific options ('-o list' for list)
>   -b, --backing BACKING_FILENAME
>      stack new image on top of BACKING_FILENAME
>      (for formats which support stacking)
>   -F, --backing-format BACKING_FMT
>      specify format of BACKING_FILENAME
>   -u, --backing-unsafe
>      do not fail if BACKING_FMT can not be read
>   --object OBJDEF
>      QEMU user-creatable object (eg encryption key)
>   FILENAME
>      image file to create.  It will be overridden if exists
>   SIZE
>      image size with optional suffix (multiplies in 1024)
>      SIZE is required unless BACKING_IMG is specified,
>      in which case it will be the same as size of BACKING_IMG
> 
> Maybe it's a good idea to add newlines around the "syntax" part,
> ie, after "Usage:" and before "Arguments:".  I don't think it needs
> extra newlines between each argument description though, - this way
> it becomes just too long.
> 
> What do you think?

I still prefer to have more vertical whitespace, as I find it harder
to read through without it. I was using the typical man page option
/ usage formatting as a guide in my feedback.

Still, it would be useful to see what other maintainers think, as I'm
just one data point.

With regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|