[libvirt PATCH] manpages/virsh: Clarify the meaning of the '--current' flag
Peter Krempa
pkrempa at redhat.com
Fri Jul 17 08:46:22 UTC 2020
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:
>
> [...]
>
> > > ---
> > > 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.
I still don't think that with your addition it's more clear what's
meant than it was before.
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
> Aside: it's not clear if you're objecting only to this occurrence, or to
> edit throughout the doc.
All of them.
> > 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.
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)
More information about the libvir-list
mailing list