Re: [PATCH 1/2] trace: document how to specify multiple --trace patterns

[Stefan Hajnoczi]

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