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

[Eric Blake <eblake@redhat.com>]

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.

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3226
Virtualization:  qemu.org | libvirt.org