[libvirt] [PATCH] docs: improve virsh man page synopses

Eric Blake eblake at redhat.com
Mon Jul 18 17:01:50 UTC 2011

On 07/18/2011 01:38 AM, Jiri Denemark wrote:
> On Thu, Jul 14, 2011 at 11:38:54 -0600, Eric Blake wrote:
>> "optional" is not a very good meta-syntactic construct in our man
>> page.  I scrubbed this, and additionally improved some documentation
>> on mutually exclusive options.  For example,
>> {[--live] [--config] | --current}
>> implies that the set must be satisfied ({}), and within the set, you
>> either have a mandatory --current, or an optional combination of 0,
>> 1, or both --live and --config.
> Hmm, why not [[--live] [--config] | --current] to make it more obvious that
> none of the options is in fact required?

That works for me as well, so I'll go ahead and make that change.

> ...
>> > -=item B<vcpucount> I<domain-id>  optional I<--maximum> I<--current>
>> > -I<--config> I<--live>
>> > +=item B<vcpucount> I<domain-id>  [I<--maximum>] {I<--current> |
>> > +[I<--config>] [I<--live>]}
> And here.

vcpucount is the oddball; our current semantics are either no flags, or 
exactly two flags (one from the set of maximum/current, and one from the 
set config/live).  See more here:

For now, I'm representing that as:
  [{I<--maximum> | I<--current>} {I<--config> | I<--live>}]
but I have done some additional thinking on whether it might be possible 
to introduce a new flag --active, as well as some backwards 
compatibility modes where the existing valid use cases are still honored 
but where the new preferred way would treat --current more like other 
APIs - more thoughts in reply to that mail, since it can come as a later 

>> -=item B<attach-disk>  I<domain-id>  I<source>  I<target>  optional
>> -I<--driver driver>  I<--subdriver subdriver>  I<--type type>
>> -I<--mode mode>  I<--persistent>  I<--sourcetype soucetype>
>> +=item B<attach-disk>  I<domain-id>  I<source>  I<target>
>> +[I<--driver driver>] [I<--subdriver subdriver>] [I<--type type>]
>> +[I<--mode mode>] [I<--persistent>] [I<--sourcetype soucetype>]
> Probably [I<--driver>  B<driver>] instead of [I<--driver driver>] to be more
> consistent with with other places, but this would probably better fit in a
> follow-up patch.

Indeed, there's quite a few places where we could spell things out more 
consistently, but I agree with saving them for a separate patch.

> ACK with those nits fixed.

Here's what I squashed in before pushing.

diff --git i/tools/virsh.pod w/tools/virsh.pod
index 7f035ee..5afa1f2 100644
--- i/tools/virsh.pod
+++ w/tools/virsh.pod
@@ -528,7 +528,7 @@ type attribute for the <domain> element of XML.
  =item B<migrate> [I<--live>] [I<--direct>] [I<--p2p> [I<--tunnelled>]]
  [I<--persistent>] [I<--undefinesource>] [I<--suspend>] 
  [I<--copy-storage-inc>] [I<--verbose>] I<domain-id> I<desturi> 
-[I<dname>] [I<timeout>]
+[I<dname>] [I<--timeout> B<seconds>]

  Migrate domain to another host.  Add I<--live> for live migration; 
  for peer-2-peer migration; I<--direct> for direct migration; or 
@@ -545,8 +545,8 @@ I<migrateuri> is the migration URI, which usually 
can be omitted.
  I<dname> is used for renaming the domain to new name during migration, 
  also usually can be omitted.

-I<--timeout number> forces guest to suspend when live migration exceeds
-I<number> seconds, and
+I<--timeout> B<seconds> forces guest to suspend when live migration exceeds
+that many seconds, and
  then the migration will complete offline. It can only be used with 

  B<Note>: The I<desturi> parameter for normal migration and peer2peer 
@@ -609,8 +609,8 @@ between the creation and restore point.  For a more 
complete system
  restore point, where the disk state is saved alongside the memory
  state, see the B<snapshot> family of commands.

-=item B<schedinfo> [I<--set> B<parameter=value>] I<domain-id> 
-[I<--live>] | I<--current>}
+=item B<schedinfo> [I<--set> B<parameter=value>] I<domain-id> 
+[I<--live>] | [I<--current>]]

  =item B<schedinfo> [I<--weight> B<number>] [I<--cap> B<number>]
@@ -644,8 +644,8 @@ of screen. In case of multiple graphics cards, heads 
are enumerated before
  devices, e.g. having two graphics cards, both with four heads, screen ID 5
  addresses the second head on the second card.

-=item B<setmem> I<domain-id> B<kilobytes> {[I<--config>] [I<--live>] |
+=item B<setmem> I<domain-id> B<kilobytes> [[I<--config>] [I<--live>] |

  Change the memory allocation for a guest domain.
  If I<--live> is specified, perform a memory balloon of a running guest.
@@ -663,8 +663,8 @@ rounds the parameter up unless the kB argument is 
evenly divisible by 1024
  For Xen, you can only adjust the memory of a running domain if the 
domain is
  paravirtualized or running the PV balloon driver.

-=item B<setmaxmem> I<domain-id> B<kilobytes> {[I<--config>] [I<--live>] |
+=item B<setmaxmem> I<domain-id> B<kilobytes> [[I<--config>] [I<--live>] |

  Change the maximum memory allocation limit for a guest domain.
  If I<--live> is specified, affect a running guest.
@@ -685,7 +685,7 @@ of 4MB, while 266240 (260MB) is valid without rounding.

  =item B<memtune> I<domain-id> [I<--hard-limit> B<kilobytes>]
  [I<--soft-limit> B<kilobytes>] [I<--swap-hard-limit> B<kilobytes>]
-[I<--min-guarantee> B<kilobytes>]
+[I<--min-guarantee> B<kilobytes>] [[I<--config>] [I<--live>] | 

  Allows you to display or set the domain memory parameters. Without
  flags, the current settings are displayed; with a flag, the
@@ -729,7 +729,8 @@ value are kilobytes (i.e. blocks of 1024 bytes).


-=item B<blkiotune> I<domain-id> [I<--weight> B<weight>]
+=item B<blkiotune> I<domain-id> [I<--weight> B<weight>] [[I<--config>]
+[I<--live] | [I<--current>]]

  Display or set the blkio parameters. QEMU/KVM supports I<--weight>.
  I<--weight> is in range [100, 1000].
@@ -741,8 +742,8 @@ Both I<--live> and I<--current> flags may be given, 
but I<--current> is
  exclusive. If no flag is specified, behavior is different depending
  on hypervisor.

-=item B<setvcpus> I<domain-id> I<count> [I<--maximum>] {[I<--config>]
-[I<--live>] | I<--current}
+=item B<setvcpus> I<domain-id> I<count> [I<--maximum>] [[I<--config>]
+[I<--live>] | [I<--current]]

  Change the number of virtual CPUs active in a guest domain.  By default,
  this command works on active guest domains.  To change the settings for an
@@ -814,8 +815,8 @@ is not available the processes will provide an exit 
code of 1.
  Undefine the configuration for an inactive domain. Since it's not running
  the domain name or UUID must be used as the I<domain-id>.

-=item B<vcpucount> I<domain-id>  [I<--maximum>] {I<--current> |
-[I<--config>] [I<--live>]}
+=item B<vcpucount> I<domain-id>  [{I<--maximum> | I<--current>}
+{I<--config> | I<--live>}]

  Print information about the virtual cpu counts of the given
  I<domain-id>.  If no flags are specified, all possible counts are
@@ -834,8 +835,8 @@ values; these two flags cannot both be specified.
  Returns basic information about the domain virtual CPUs, like the 
number of
  vCPUs, the running time, the affinity to physical processors.

-=item B<vcpupin> I<domain-id> [I<vcpu>] [I<cpulist>] {[I<--live>]
-[I<--config>] | I<--current>}
+=item B<vcpupin> I<domain-id> [I<vcpu>] [I<cpulist>] [[I<--live>]
+[I<--config>] | [I<--current>]]

  Query or change the pinning of domain VCPUs to host physical CPUs.  To
  pin a single I<vcpu>, specify I<cpulist>; otherwise, you can query one

Eric Blake   eblake at redhat.com    +1-801-349-2682
Libvirt virtualization library http://libvirt.org

More information about the libvir-list mailing list