Hello Michael, Such changes are long overdue. However given the complexity of commands and arguments, maybe it'd be a good idea to write a code generator for the command line interface, This way you could also generate --help outputs, manpages, shell completions just from the command line spec we'd use to generate the argv parsing routines.
On Wed, 7 Feb 2024 at 19:58, Michael Tokarev <m...@tls.msk.ru> wrote: > > This is an incomplete first attempt only, there's a lot left to do. > > All the options in qemu-img is a complete mess, - no, inconsistent or > incomplete syntax in documentation, many undocumented options, option > names are used inconsistently and differently for different commands, > no long options exists for many short options, --help output is a huge > mess by its own, and the way how it all is generated is another story. > docs/tools/qemu-img.rst with qemu-img-opts.hx is yet another. > > I hoped to fix just an option or two, but it ended up in a large task, > and I need some help and discussion, hence the RFC. > > The idea is: > > - create more or less consistent set of options between different > subcommands > - provide long options which can be used without figuring out which > -T/-t, -f|-F|-O etc to use for which of the two images given > - have qemu-img --help provide just a list of subcommands > - have qemu-img COMMAND --help to describe just this subcommand > - get rid of qemu-img-opts.hx, instead finish documentation in > qemu-img.rst based on the actual options implemented in > qemu-img.c. > > I started converting subcommands one by one, providing long options > and --help output. And immediately faced some questions which needs > wider discussion. > > o We have --image-opts and --target-image-opts. Do we really need both? > In my view, --image-opts should be sort of global, turning *all* > filenames on this command line into complete image specifications, > there's no need to have separate image-opts and --target-image-opts. > Don't know what to do wrt compatibility though. It shouldn't be made > this way from the beginning. As a possible solution, introduce a new > option and deprecate current set. > > o For conversion (convert, dd, etc), we've source and destination, > so it's easy to distinguish using long options, like --source-format > --target-cache etc (-t/-T -f/-F is a mess here already). What to > do with compare? --format1 --format2 is ugly, maybe --a-format and > --b-format? Maybe we can get off with --source (a) and --target (b) > instead of filename1 & filename2? > (--cache in this context is global for both). > > o qemu-img convert. It's the most messy one, and it is not really > documented (nor in qemu-img.rst , eg there's nothing in there about > FILENAME2, -B is difficult to understand, etc). > At the very least, I'd say the options should be > --source-format, --source-cache etc > --target-format, --target-options > --target-image-opts - this shold go IMHO > > o check and commit - inconsistent cache flags? > In convert, cache is backwards (source/target)? > > At first, I tried to have more or less common option descriptions, > using various parameters, variables or #defines, but in different > commands the same options has slightly different wording, and in > some option names are different, so it looks like it's best to > have complete text in each subcommand. > > > Michael Tokarev (8): > qemu-img: pass current cmdname into command handlers > qemu-img: refresh options/--help for "create" subcommand > qemu-img: factor out parse_output_format() and use it in the code > (this one has been sent in a separate patch, here it is just for > completness) > qemu-img: refresh options/--help for "check" command > qemu-img: simplify --repair error message > qemu-img: refresh options/--help for "commit" command > qemu-img: refresh options/--help for "compare" command > qemu-img: refresh options/--help for "convert" command > > qemu-img.c | 352 ++++++++++++++++++++++++++++++++++------------------- > 1 file changed, 226 insertions(+), 126 deletions(-) > > -- > 2.39.2 > > -- Manos Pitsidianakis Emulation and Virtualization Engineer at Linaro Ltd