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

[John Snow <jsnow@redhat.com>]

On 1/13/21 5:15 PM, Eric Blake wrote:
> 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.
> 

Yes, this makes sense.

>>>
>>> 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.
> 

At that point, it's a guessing game as to which binaries support which 
flags and using which spellings -- maybe some will pick up new flags 
later and so on.

Skip the fuss and just insist on the double dash, I think.

--js