[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]

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



On 8/24/20 5:39 PM, Pavel Hrdina wrote:
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 redhat com>
---
- 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.

Alright then, I'm changing the "domains" in the second sentence in the first hunk to "guests" then and merging the rest as is.

Reviewed-by: Michal Privoznik <mprivozn redhat com>

Michal


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]