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

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