[libvirt PATCH] manpages/virsh: Clarify the meaning of the '--current' flag

[Kashyap Chamarthy]

Currently the documentation says:

    "If *--current* is specified, affect the current guest state."

It's not entirely clear what states can "current" imply.  E.g. `virsh
detach-device --current [...]`  — does this affect the live guest state
or offline state?

Answer: It affects the "current" state, which can either be live or
offline.

Spell that out; it's clearer that way.  Fix all occurrences (i.e. as
many as I could spot) of this.

(Thanks: Dan Berrangé on IRC for clarifying.)

Signed-off-by: Kashyap Chamarthy <kchamart at redhat.com>
---
For 'iothreadset', the documentation says:

    "If *--current* is specified or *--live* is not specified, then
    handle as if *--live* was specified."

Does the above make sense?  I don't know the implementation detail here.
So I just added a parenthetical note on what the word "current" means.
---
 docs/manpages/virsh.rst | 84 ++++++++++++++++++++++++++---------------
 1 file changed, 54 insertions(+), 30 deletions(-)

diff --git a/docs/manpages/virsh.rst b/docs/manpages/virsh.rst
index 1a2cf09fb7..3c8d0434ab 100644
--- a/docs/manpages/virsh.rst
+++ b/docs/manpages/virsh.rst
@@ -1090,7 +1090,8 @@ reset the value back to the default.
 
 If *--live* is specified, affect a running guest.
 If *--config* is specified, affect the next boot of a persistent guest.
-If *--current* is specified, affect the current guest state.
+If *--current* is specified, affect the current guest state, which can
+either be live or offline.
 When setting the disk io parameters both *--live* and *--config* flags may be
 given, but *--current* is exclusive. For querying only one of *--live*,
 *--config* or *--current* can be specified. If no flag is specified, behavior
@@ -1152,7 +1153,8 @@ any existing per-device write_bytes_sec for other devices remain unchanged.
 
 If *--live* is specified, affect a running guest.
 If *--config* is specified, affect the next boot of a persistent guest.
-If *--current* is specified, affect the current guest state.
+If *--current* is specified, affect the current guest state, which can
+either be live or offline.
 Both *--live* and *--config* flags may be given, but *--current* is
 exclusive. If no flag is specified, behavior is different depending
 on hypervisor.
@@ -1986,7 +1988,8 @@ respectfully with average value of zero.
 
 If *--live* is specified, affect a running guest.
 If *--config* is specified, affect the next boot of a persistent guest.
-If *--current* is specified, affect the current guest state.
+If *--current* is specified, affect the current guest state, which can
+either be live or offline.
 Both *--live* and *--config* flags may be given, but *--current* is
 exclusive. If no flag is specified, behavior is different depending
 on hypervisor.
@@ -2089,7 +2092,8 @@ The *--live*, *--config*, and *--current* flags are only valid when using
 the *--period* option in order to set the collection period for the balloon
 driver. If *--live* is specified, only the running guest collection period
 is affected. If *--config* is specified, affect the next boot of a persistent
-guest. If *--current* is specified, affect the current guest state.
+guest. If *--current* is specified, affect the current guest state,
+which can either be live or offline.
 
 Both *--live* and *--config* flags may be given, but *--current* is
 exclusive. If no flag is specified, behavior is different depending
@@ -2582,7 +2586,8 @@ See ``vcpupin`` for *cpulist*.
 
 If *--live* is specified, affect a running guest.
 If *--config* is specified, affect the next boot of a persistent guest.
-If *--current* is specified, affect the current guest state.
+If *--current* is specified, affect the current guest state, which can
+either be live or offline.
 Both *--live* and *--config* flags may be given if *cpulist* is present,
 but *--current* is exclusive.
 If no flag is specified, behavior is different depending on hypervisor.
@@ -2746,7 +2751,7 @@ If *--live* is specified, affect a running guest. If the guest is not
 running an error is returned.
 If *--config* is specified, affect the next boot of a persistent guest.
 If *--current* is specified or *--live* and *--config* are not specified,
-affect the current guest state.
+affect the current guest state, which can either be live or offline.
 
 
 iothreaddel
@@ -2767,7 +2772,7 @@ If *--live* is specified, affect a running guest. If the guest is not
 running an error is returned.
 If *--config* is specified, affect the next boot of a persistent guest.
 If *--current* is specified or *--live* and *--config* are not specified,
-affect the current guest state.
+affect the current guest state, which can either be live or offline.
 
 
 iothreadinfo
@@ -2787,7 +2792,8 @@ the guest is not running, an error is returned.
 If *--config* is specified, get the IOThreads data from the next boot of
 a persistent guest.
 If *--current* is specified or *--live* and *--config* are not specified,
-then get the IOThread data based on the current guest state.
+then get the IOThread data based on the current guest state, which can
+either be live or offline.
 
 
 iothreadpin
@@ -2814,7 +2820,7 @@ If *--live* is specified, affect a running guest. If the guest is not running,
 an error is returned.
 If *--config* is specified, affect the next boot of a persistent guest.
 If *--current* is specified or *--live* and *--config* are not specified,
-affect the current guest state.
+affect the current guest state, which can either be live or offline.
 Both *--live* and *--config* flags may be given if *cpulist* is present,
 but *--current* is exclusive.
 If no flag is specified, behavior is different depending on hypervisor.
@@ -2851,7 +2857,8 @@ next start, restore, etc.
 If *--live* is specified, affect a running guest. If the guest is not
 running an error is returned.
 If *--current* is specified or *--live* is not specified, then handle
-as if *--live* was specified.
+as if *--live* was specified.  (Where "current" here means whatever the
+present guest state is: live or offline.)
 
 
 managedsave
@@ -2998,7 +3005,8 @@ For example, vSphere/ESX rounds the parameter up to mebibytes (1024 kibibytes).
 
 If *--live* is specified, affect a running guest.
 If *--config* is specified, affect the next boot of a persistent guest.
-If *--current* is specified, affect the current guest state.
+If *--current* is specified, affect the current guest state, which can
+either be live or offline.
 Both *--live* and *--config* flags may be given, but *--current* is
 exclusive. If no flag is specified, behavior is different depending
 on hypervisor.
@@ -3393,7 +3401,8 @@ excluding a node.
 
 If *--live* is specified, set scheduler information of a running guest.
 If *--config* is specified, affect the next boot of a persistent guest.
-If *--current* is specified, affect the current guest state.
+If *--current* is specified, affect the current guest state, which can
+either be live or offline.
 
 For running guests in Linux hosts, the changes made in the domain's
 numa parameters does not imply that the guest memory will be moved to a
@@ -3486,7 +3495,8 @@ the *--perf* flag.
 
 If *--live* is specified, affect a running guest.
 If *--config* is specified, affect the next boot of a persistent guest.
-If *--current* is specified, affect the current guest state.
+If *--current* is specified, affect the current guest state, which can
+either be live or offline.
 Both *--live* and *--config* flags may be given, but *--current* is
 exclusive. If no flag is specified, behavior is different depending
 on hypervisor.
@@ -3715,7 +3725,8 @@ ESX (allocation scheduler): reservation, limit, shares
 
 If *--live* is specified, set scheduler information of a running guest.
 If *--config* is specified, affect the next boot of a persistent guest.
-If *--current* is specified, affect the current guest state.
+If *--current* is specified, affect the current guest state, which can
+either be live or offline.
 
 ``Note``: The cpu_shares parameter has a valid value range of 0-262144; Negative
 values are wrapped to positive, and larger values are capped at the maximum.
@@ -3957,7 +3968,8 @@ setmaxmem
 Change the maximum memory allocation limit for a guest domain.
 If *--live* is specified, affect a running guest.
 If *--config* is specified, affect the next boot of a persistent guest.
-If *--current* is specified, affect the current guest state.
+If *--current* is specified, affect the current guest state, which can
+either be live or offline.
 Both *--live* and *--config* flags may be given, but *--current* is
 exclusive. If no flag is specified, behavior is different depending
 on hypervisor.
@@ -3988,7 +4000,8 @@ setmem
 Change the memory allocation for a guest domain.
 If *--live* is specified, perform a memory balloon of a running guest.
 If *--config* is specified, affect the next boot of a persistent guest.
-If *--current* is specified, affect the current guest state.
+If *--current* is specified, affect the current guest state, which can
+either be live or offline.
 Both *--live* and *--config* flags may be given, but *--current* is
 exclusive. If no flag is specified, behavior is different depending
 on hypervisor.
@@ -4038,7 +4051,8 @@ specified together if supported by the hypervisor.  If this command is run
 before the guest has finished booting, the guest may fail to process
 the change.
 
-If *--current* is specified, affect the current guest state.
+If *--current* is specified, affect the current guest state, which can
+either be live or offline.
 
 When no flags are given, the *--live*
 flag is assumed and the guest domain must be active.  In this situation it
@@ -4084,9 +4098,9 @@ others.
 
 If *--live* is specified, affect a running domain.
 If *--config* is specified, affect the next startup of a persistent domain.
-If *--current* is specified, affect the current domain state. This is the
-default. Both *--live* and *--config* flags may be given, but *--current* is
-exclusive.
+If *--current* is specified, affect the current domain state, which can
+either be live or offline. This is the default. Both *--live* and
+*--config* flags may be given, but *--current* is exclusive.
 
 
 shutdown
@@ -4356,7 +4370,8 @@ also be allowed. The '-' denotes the range and the '^' denotes exclusive.
 For pinning the *vcpu* to all physical cpus specify 'r' as a *cpulist*.
 If *--live* is specified, affect a running guest.
 If *--config* is specified, affect the next boot of a persistent guest.
-If *--current* is specified, affect the current guest state.
+If *--current* is specified, affect the current guest state, which can
+either be live or offline.
 Both *--live* and *--config* flags may be given if *cpulist* is present,
 but *--current* is exclusive.
 If no flag is specified, behavior is different depending on hypervisor.
@@ -4411,7 +4426,8 @@ needed if the PCI device does not use managed mode.
 
 If *--live* is specified, affect a running domain.
 If *--config* is specified, affect the next startup of a persistent domain.
-If *--current* is specified, affect the current domain state.
+If *--current* is specified, affect the current domain state, which can
+either be live or offline.
 Both *--live* and *--config* flags may be given, but *--current* is
 exclusive. When no flag is specified legacy API is used whose behavior depends
 on the hypervisor driver.
@@ -4480,7 +4496,8 @@ is printed instead.
 
 If *--live* is specified, affect a running domain.
 If *--config* is specified, affect the next startup of a persistent domain.
-If *--current* is specified, affect the current domain state.
+If *--current* is specified, affect the current domain state, which can
+either be live or offline.
 Both *--live* and *--config* flags may be given, but *--current* is
 exclusive. When no flag is specified legacy API is used whose behavior depends
 on the hypervisor driver.
@@ -4568,7 +4585,8 @@ attached is printed instead.
 
 If ``--live`` is specified, affect a running domain.
 If ``--config`` is specified, affect the next startup of a persistent domain.
-If ``--current`` is specified, affect the current domain state.
+If ``--current`` is specified, affect the current domain state, which
+can either be live or offline.
 Both ``--live`` and ``--config`` flags may be given, but ``--current`` is
 exclusive.  When no flag is specified legacy API is used whose behavior
 depends on the hypervisor driver.
@@ -4615,7 +4633,8 @@ returns.
 
 If *--live* is specified, affect a running domain.
 If *--config* is specified, affect the next startup of a persistent domain.
-If *--current* is specified, affect the current domain state.
+If *--current* is specified, affect the current domain state, which can
+either be live or offline.
 Both *--live* and *--config* flags may be given, but *--current* is
 exclusive. When no flag is specified legacy API is used whose behavior depends
 on the hypervisor driver.
@@ -4643,7 +4662,8 @@ removal of the device is notified asynchronously via libvirt events
 
 If *--live* is specified, affect a running domain.
 If *--config* is specified, affect the next startup of a persistent domain.
-If *--current* is specified, affect the current domain state.
+If *--current* is specified, affect the current domain state, which can
+either be live or offline.
 Both *--live* and *--config* flags may be given, but *--current* is
 exclusive.
 
@@ -4663,7 +4683,8 @@ from the domain.
 
 If *--live* is specified, affect a running domain.
 If *--config* is specified, affect the next startup of a persistent domain.
-If *--current* is specified, affect the current domain state.
+If *--current* is specified, affect the current domain state, which can
+either be live or offline.
 Both *--live* and *--config* flags may be given, but *--current* is
 exclusive. When no flag is specified legacy API is used whose behavior depends
 on the hypervisor driver.
@@ -4699,7 +4720,8 @@ present on the domain.
 
 If *--live* is specified, affect a running domain.
 If *--config* is specified, affect the next startup of a persistent domain.
-If *--current* is specified, affect the current domain state.
+If *--current* is specified, affect the current domain state, which can
+either be live or offline.
 Both *--live* and *--config* flags may be given, but *--current* is
 exclusive. When no flag is specified legacy API is used whose behavior depends
 on the hypervisor driver.
@@ -4732,7 +4754,8 @@ libvirt XML format for a device.
 
 If *--live* is specified, affect a running domain.
 If *--config* is specified, affect the next startup of a persistent domain.
-If *--current* is specified, affect the current domain state.
+If *--current* is specified, affect the current domain state, which can
+either be live or offline.
 Both *--live* and *--config* flags may be given, but *--current* is
 exclusive. Not specifying any flag is the same as specifying *--current*.
 
@@ -5223,7 +5246,8 @@ instance of <ip> will get the modification.
 
 If *--live* is specified, affect a running network.
 If *--config* is specified, affect the next startup of a persistent network.
-If *--current* is specified, affect the current network state.
+If *--current* is specified, affect the current network state, which can
+either be live or offline.
 Both *--live* and *--config* flags may be given, but *--current* is
 exclusive. Not specifying any flag is the same as specifying *--current*.
 
-- 
2.26.2