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?
Otherwise I like it.
> * tools/virsh.pod: Use "[name]" rather than "optional name" for
> optional arguments.
> ---
>
> I finally did something to address a pet peeve of mine.
>
> tools/virsh.pod | 199 ++++++++++++++++++++++++++++++-------------------------
> 1 files changed, 108 insertions(+), 91 deletions(-)
>
> diff --git a/tools/virsh.pod b/tools/virsh.pod
> index 1a98ec1..c6549f1 100644
> --- a/tools/virsh.pod
> +++ b/tools/virsh.pod
...
> +=item B<migrate> [I<--live>] [I<--direct>] [I<--p2p> [I<--tunnelled>]]
> +[I<--persistent>] [I<--undefinesource>] [I<--suspend>] [I<--copy-storage-all>]
> +[I<--copy-storage-inc>] [I<--verbose>] I<domain-id> I<desturi> [I<migrateuri>]
> +[I<dname>] [I<timeout>]
Shouldn't [I<timeout>] be specified as [I<--timeout> B<seconds>]?
>
> Migrate domain to another host. Add I<--live> for live migration; I<--p2p>
> for peer-2-peer migration; I<--direct> for direct migration; or I<--tunnelled>
> @@ -544,7 +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, which
> also usually can be omitted.
>
> -I<--timeout> forces guest to suspend when live migration exceeds timeout, and
> +I<--timeout number> forces guest to suspend when live migration exceeds
> +I<number> seconds, and
> then the migration will complete offline. It can only be used with I<--live>.
...
> -=item B<schedinfo> optional I<--set> B<parameter=value> I<domain-id> I<--config>
> -I<--live> I<--current>
> +=item B<schedinfo> [I<--set> B<parameter=value>] I<domain-id> {[I<--config>]
> +[I<--live>] | I<--current>}
Make it more obvious that neither or --config, --live, --current need to be
specified as mentioned above.
...
> -=item B<setmem> I<domain-id> B<kilobytes> optional I<--config> I<--live>
> -I<--current>
> +=item B<setmem> I<domain-id> B<kilobytes> {[I<--config>] [I<--live>] |
> +I<--current>}
The same here.
...
> -=item B<setmaxmem> I<domain-id> B<kilobytes> optional I<--config> I<--live>
> -I<--current>
> +=item B<setmaxmem> I<domain-id> B<kilobytes> {[I<--config>] [I<--live>] |
> +I<--current>}
And here.
...
> -=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.
> Print information about the virtual cpu counts of the given
> I<domain-id>. If no flags are specified, all possible counts are
> @@ -830,8 +832,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> optional 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>}
Ditto.
...
> 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
> @@ -876,9 +878,9 @@ See the documentation to learn about libvirt XML format for a device.
> For cdrom and floppy devices, this command only replaces the media within
> the single existing device; consider using B<update-device> for this usage.
>
> -=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.
ACK with those nits fixed.
Jirka
--
libvir-list mailing list
libvir-list@xxxxxxxxxx
https://www.redhat.com/mailman/listinfo/libvir-list