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

[Kashyap Chamarthy]

On Thu, Jul 16, 2020 at 06:34:21PM +0200, Peter Krempa wrote:
> On Thu, Jul 16, 2020 at 17:45:21 +0200, Kashyap Chamarthy wrote:

[...]

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

I was asked clarification at least a couple of times on what "--current"
means.  If you look up online, you'll also see people asking the
difference between "--live" and "--current".  So it's better to be
explicit about it.

Aside: it's not clear if you're objecting only to this occurrence, or to
edit throughout the doc.

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

Hmm, then let's fix that too. "Hypervisor state" is fuzzy.  Do you
suggest a specific phrasing as a replacement?

I thought the meaning fo --config meant what it says on the tin: for a
persistent guest, the change from --config will take effect on its next
boot.

-- 
/kashyap