[libvirt] [PATCH 0/4] generate SYNTAX section of "virsh help CMD" output

[Jim Meyering]

"Daniel P. Berrange" <berrange at redhat.com> wrote:
> On Fri, Dec 05, 2008 at 07:24:31PM +0100, Jim Meyering wrote:
>> This started when I noticed that a lot of virsh help output was
>> out of date.  Dan Berrange suggested to generate the SYNTAX line
>> automatically based on existing option descriptions, since they tell us
>> what arguments/types each command accepts and can (usually) tell us when
>> options or arguments are optional.
>
> ACK to all these changes since they're a significant improvement on
> what we have.
>
>> --- attach-disk.orig
>> +++ attach-disk.new
>> @@ -2,7 +2,7 @@
>>      attach-disk - attach disk device
>>
>>    SYNOPSIS
>> -    attach-disk <domain> <source> <target> [--driver <driver>] [--subdriver <subdriver>] [--type <type>] [--mode <mode>]
>> +    attach-disk <domain> <source> <target> [--driver <string>] [--subdriver <string>] [--type <string>] [--mode <string>]
>
>
> I'm wondering if we ought to go further and make ths SYNOPSIS
> follow the style used in manpages more explicitly. So leave
> out explicit listing of optional flags, and get rid of the
> angle brackets since they look rather wierd then you then
> combine with square brackets.
>
> To quote 'chmod(1)'
>
> SYNOPSIS
>        chmod [OPTION]... MODE[,MODE]... FILE...
>        chmod [OPTION]... OCTAL-MODE FILE...
>        chmod [OPTION]... --reference=RFILE FILE...
>
>
> So getting a style like
>
>     attach-disk [OPTIONS]... DOMAIN SOURCE TARGET
>
>> --- connect.orig
>> +++ connect.new
>> @@ -2,7 +2,7 @@
>>      connect - (re)connect to hypervisor
>>
>>    SYNOPSIS
>> -    connect [name] [--readonly]
>> +    connect [<name>] [--readonly]
>
>      connect [OPTIONS]... [NAME]
>
>> --- create.orig
>> +++ create.new
>> @@ -2,7 +2,7 @@
>>      create - create a domain from an XML file
>>
>>    SYNOPSIS
>> -    create a domain from an XML <file>
>> +    create <file>
>
>      create FILE

I agree: that'd be a fine improvement (but I'm biased ;-)
I'll do it if no one objects.