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