Re: [libvirt PATCH v2] manpages/virsh: A couple of small clarifications

On Mon, Aug 24, 2020 at 05:33:21PM +0200, Peter Krempa wrote: > On Mon, Aug 24, 2020 at 17:01:50 +0200, Michal Privoznik wrote: >> On 8/4/20 4:04 PM, Kashyap Chamarthy wrote: >>> Changes: >>> >>> - Update the descriptions of --current & --config flags. >>> >>> For --config, the reason to rephrase "next boot" to "next start" >>> is: "Next boot may still imply somebody selecting "reboot" in the >>> guest OS and fully expecting the changes to be applied." (per Peter >>> Krempa) >>> >>> For --current, existing documentation says: >>> >>> "If *--current* is specified, affect the current guest state." >>> >>> It's not entirely clear what states can "current" mean or imply. So >>> rephrase it in context of the other two related flags --live and >>> --config. >>> >>> - While at it, I also took the liberty to replace the few occurrences >>> of "peristent domain[s]" with "persistent guest[s]" >>> >>> Fix all occurrences (i.e. as many as I could spot) of this. >>> >>> (Thanks: Dan Berrangé on IRC.) >>> >>> Signed-off-by: Kashyap Chamarthy <kchamart(a)redhat.com&gt; >>> --- >>> - v2: Address Peter Krempa's feedback >>> (https://www.redhat.com/archives/libvir-list/2020-July/msg01274.html) >>> --- >>> docs/manpages/virsh.rst | 163 +++++++++++++++++++++++----------------- >>> 1 file changed, 95 insertions(+), 68 deletions(-) >>> >>> diff --git a/docs/manpages/virsh.rst b/docs/manpages/virsh.rst >>> index 1a2cf09fb7..561b1f038e 100644 >>> --- a/docs/manpages/virsh.rst >>> +++ b/docs/manpages/virsh.rst >>> @@ -710,7 +710,7 @@ groups: >>> Persistence >>> ........... >>> -Flag *--persistent* is used to include persistent domains in the returned >>> +Flag *--persistent* is used to include persistent guests in the returned >>> list. To include transient domains specify *--transient*. >> >> So this changes "domains" to "guests", but only for the first sentence. The >> second one still refers to "domains". IMO this is not desirable change >> because it's not aligned with our terminology. We call them "domains" (I >> wish we would call them guests too, but too late for that). And we are not >> consistent, I know. >> >>> Existence of managed save image >>> @@ -1089,8 +1089,9 @@ then the default value of 1 second will be displayed. Supplying a 0 will >>> 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 *--config* is specified, affect the next start of a persistent guest. >> >> s/next start/next cold start/? >> s/guest/domain/ (here and for the rest of the lines you're changing) > > To be fair, I'm not very fond of sticking too much to the XEN > terminology, especially since most of the virtualization world uses > 'guest' to refer to it. +1 or VM (virtual machine) which is commonly used as well. Our API obviously have to stick with `domain` but everywhere else I would prefer using guest/VM.