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

[Eric Blake]

On 1/13/21 3:42 PM, John Snow wrote:
> On 1/13/21 4:48 AM, Stefan Hajnoczi wrote:
>>> QEMU options are single dash with double dash accepted for
>>> compatibility but
>>> help and other docs have single dash so these (and below) should be
>>> -trace.
>>> (Also a bit less typing for otherwise already way too long command
>>> lines.)
>> Is this documented somewhere?
>>
>> I was under the impression that '-' is legacy syntax and '--' is the
>> preferred syntax. There are examples of '--' on the QEMU man page.

Historically, uses of 'getopt_long()' support only double dash, while
'getopt_long_only()' support both single and double.  While qemu does
not use getopt_long_only() (because it rolls its own parser instead), it
certainly tries to behave as if it does.  Meanwhile, our other tools
like qemu-img or qemu-storage-daemon use getopt_long().  I'm in favor of
preferring the double-dash in documentation, even when single-dash
works, especially for any option (like --trace) that is used for more
tools than just qemu proper, because it makes for easier copy-paste
between options that work for all tools in the qemu suite rather than
just qemu.

>>
>> Let's reach agreement, document it, and then make the documentation
>> consistent.
>>
>> Stefan
> 
> My naive impression was that double-dash is the preferred idiom in
> linuxdom in general for any multi-character option.
> 
> We might hang on to single-dash for backwards compatibility, but I doubt
> we want to enshrine that as our preferred way.
> 
> Is there a reasoning I am unaware of?

Continuing to document '-machine' instead of '--machine' for qemu is
debatable because we don't support 'qemu-img --machine' or
'qemu-storage-daemon --machine'; but since 'qemu-img -trace' is an error
while 'qemu-img --trace' works, I'm definitely in favor of preferring
'--trace' everywhere in our docs.

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