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

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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:
https://www.redhat.com/archives/libvir-list/2011-July/msg01030.html

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 patch.

-=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-all>] [I<--copy-storage-inc>] [I<--verbose>] I<domain-id> I<desturi> [I<migrateuri>]
-[I<dname>] [I<timeout>]
+[I<dname>] [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> @@ -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, which
 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 I<--live>.

B<Note>: The I<desturi> parameter for normal migration and peer2peer migration @@ -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<--config>]
-[I<--live>] | I<--current>}
+=item B<schedinfo> [I<--set> B<parameter=value>] I<domain-id> [[I<--config>]
+[I<--live>] | [I<--current>]]

 =item B<schedinfo> [I<--weight> B<number>] [I<--cap> B<number>]
 I<domain-id>
@@ -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>] |
-I<--current>}
+=item B<setmem> I<domain-id> B<kilobytes> [[I<--config>] [I<--live>] |
+[I<--current>]]

 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>] |
-I<--current>}
+=item B<setmaxmem> I<domain-id> B<kilobytes> [[I<--config>] [I<--live>] |
+[I<--current>]]

 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>] | [I<--current>]]

 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).

 =back

-=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@xxxxxxxxxx    +1-801-349-2682
Libvirt virtualization library http://libvirt.org

--
libvir-list mailing list
libvir-list@xxxxxxxxxx
https://www.redhat.com/mailman/listinfo/libvir-list


[Index of Archives]     [Virt Tools]     [Libvirt Users]     [Lib OS Info]     [Fedora Users]     [Fedora Desktop]     [Fedora SELinux]     [Big List of Linux Books]     [Yosemite News]     [KDE Users]     [Fedora Tools]