On Tue, Jan 19, 2021 at 10:31:49AM -0600, Eric Blake wrote: > On 1/14/21 8:18 AM, BALATON Zoltan wrote: > > >> I wasn't aware of the fact that some of the utilities are sensitive to > >> '--' vs '-'! I'm in favor of consistently using '--' in documentation > >> but allowing both for backwards compatibility where '-' is currently > >> supported. > >> > >> If we are in agreement, then let's: > >> > >> 1. Add a section to CODING_STYLE.rst or other developer documentation > >> documenting this. > > Seems reasonable to me. > > > > > I'd be more in favour of documenting that QEMU accepts - options but > > also -- as alternative and fixing the tools that currently use > > getopt_long to use getopt_long_only to keep it consistent with main QEMU > > executable. Otherwise this will get more and more inconsistent with new > > options added with -- and old ones only exist in - form so to keep > > consistency we should standardise on - not --. > > I've got less practical experience with getopt_long_only(); I know there > are some utilities like gcc that have to use it, but GNU coding > standards prefer getopt_long() over getopt_long_only(). I think one of > the reasons is the potential for ambiguity: if you have a program that > accepts a series of short options without arguments, you can combine > them together (think 'ls -lF'), but what happens when your combination > of letters then resembles a long option? A bit contrived, but 'ls --no' > is short for 'ls --no-group' (aka 'ls -G'), while 'ls -no' is the same > as 'ls -n -o', which has different behavior. ls uses getopt_long(), > hence the use of -- matters; but if it were to use getopt_long_only(), > you would have changed the behavior of 'ls -no' (it would now favor > --no-group over -n -o). > > That's not to say we can't switch qemu-img, qemu-storage-daemon, > qemu-io, and friends to use getopt_long_only(), but merely that we have > to be careful of what it will do to their command line parsing, and > whether it will introduce any unintended regressions. > > So the conservative answer from me is to prefer documenting '--' options > everywhere, rather than trying to figure out when '-' is acceptable with > long option names. > > > > >> 2. Convert existing documentation to use '--'. This will make it more > >> consistent and also avoid confusion about '-' vs '--'. > > > > You could still use -- in documentation but what's the problem with - if > > -- is also accepted if one wants to type that? > > Supporting lazy typists is one thing, but our documentation should stick > to the preferred form, even when shorter forms are possible.
I lost track of this email thread. Do we have agreement on that QEMU documentation should consistently use '--' for long options? Stefan
signature.asc
Description: PGP signature
