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

[Peter Krempa]

On Thu, Jul 16, 2020 at 17:45:21 +0200, Kashyap Chamarthy wrote:
> 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.

After explaining both --live and --config ...

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

I don't think that --current requires any explanation in that context.

If anything "next boot of a persistent guest" is IMO less clear as it
in fact relates to the hypervisor state (starting the VM) rather than
the guest OS state.