Re: [PATCH 07/27] qemu-img: check: refresh options/--help

[Kevin Wolf <kwolf@redhat.com>]

Am 15.05.2025 um 08:50 hat Michael Tokarev geschrieben:
> On 13.05.2025 18:54, Kevin Wolf wrote:
> > Am 27.09.2024 um 08:11 hat Michael Tokarev geschrieben:
> 
> > > +            cmd_help(ccmd,
> > > +"[-f FMT | --image-opts] [-T CACHE_MODE] [-r] [-u]\n"
> > > +"        [--output human|json] [--object OBJDEF] FILENAME\n"
> > > +,
> > > +"  -q, --quiet\n"
> > > +"     quiet operations\n"
> > 
> > Let's keep the help text more in line with the terminology used in the
> > man page, even if shorter at times.
> 
> I haven't touched the man page for a reason, - I wasn't sure I
> understood all the options correctly.  And the man pages were the
> next planning step.  Unfortunately it's been quite some time ago
> and I don't remember details anymore.  It can be done either way,
> and I tried to make the whole thing as short as possible in the
> --help output.

Yes, we definitely need to shorten the descriptions from the man page
for --help. I think as long as it fits on a single line, it's okay, but
I understand if you want to keep it even shorter in some cases.

> > I would use the first sentence from it here: "Quiet mode - do not print
> > any output (except errors)"
> 
> Ok.

If this is too wordy for your liking, just "quiet mode" could be enough,
but I would keep the terminology the same (i.e. not "operations" here
and "mode" there").

> > > +"  -f, --format FMT\n"
> > > +"     specifies format of the image explicitly\n"
> > 
> > Maybe "format of the image (default: probing is used)"?
> 
> Yeah, makes sense.
> 
> Not wanting to risk going into an endless wording discussion,
> let's do it this way here and elsewhere.

The nature of your series is that a big part of the review is actually
the new help text, so it's unavoidable to have some wording discussions
here and there. Don't necessarily take my suggestions as the final word,
they are just suggestions on which we can iterate and find the best
wording for users. I think refining help texts is worth some thought and
back and forth between multiple people. So if you don't like my
suggestions, or you prefer a mix of yours and mine, or you have
additional improvements to them, feel free to say so.

Kevin