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

[Daniel P. Berrange]

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


Daniel
-- 
|: Red Hat, Engineering, London   -o-   http://people.redhat.com/berrange/ :|
|: http://libvirt.org  -o-  http://virt-manager.org  -o-  http://ovirt.org :|
|: http://autobuild.org       -o-         http://search.cpan.org/~danberr/ :|
|: GnuPG: 7D3B9505  -o-  F3C9 553F A1DA 4AC2 5648 23C1 B3DF F742 7D3B 9505 :|