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

[Kashyap Chamarthy]

On Fri, Jul 17, 2020 at 10:46:22AM +0200, Peter Krempa wrote:
> On Fri, Jul 17, 2020 at 10:38:32 +0200, Kashyap Chamarthy wrote:
> > 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:

[...]

> > > > -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.
> 
> I still don't think that with your addition it's more clear what's
> meant than it was before.

I was only trying to make it explicit that "current state" can mean live
or offline, because as it stands, reading the description of "--current"
in isolation is similar to this tautology: "What is foo config system?
It is a system to config foo." :-)

But I like your suggestion below.

> If you want to clarify it IMO it needs a direct reference to --live and
> --config:
> 
> *--current* selects either *--live*, or *--config* depending on the
> current state of the VM.
>
> Or alternatively s/selects/is equivalent to/ in the above

Okay, so with your suggestion here (and for "--config" below), I'll
re-send the patch with this:

  - "If *--config* is specified, affect the next start of a persistent
    guest."

  - "*--current* is equivalent to either *--live* or *--config*,
    depending on the current state of the VM."

[...]

> > 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.
> 
> Next boot may still imply somebody selecting "reboot" in the guest OS and
> fully expecting the changes to be applied.
> 
> Perhaps:
> 
> If *--config* is specified, affect the next start of a persistent
> domain.
> 
> (alternatively s/domain/VM/ if we exclude LXC)

Yep, sounds good.

s/VM/guest/  ("guest" is most consistently used in virsh.rst.)


-- 
/kashyap