[libvirt] [PATCH] virsh: make destroy sound less scary

[Eric Blake]

Destroy has a rather negative English connotation.  Try to reduce
the impact, so newbies aren't as scared to use it.

* tools/virsh.c: Tweak all destroy documentation.
* tools/virsh.pod: Likewise.
---
 tools/virsh.c   |   20 +++++++++++---------
 tools/virsh.pod |   16 +++++++++-------
 2 files changed, 20 insertions(+), 16 deletions(-)

diff --git a/tools/virsh.c b/tools/virsh.c
index 9a189fd..3b6f0ff 100644
--- a/tools/virsh.c
+++ b/tools/virsh.c
@@ -2264,8 +2264,9 @@ cmdReboot(vshControl *ctl, const vshCmd *cmd)
  * "destroy" command
  */
 static const vshCmdInfo info_destroy[] = {
-    {"help", N_("destroy a domain")},
-    {"desc", N_("Destroy a given domain.")},
+    {"help", N_("destroy (stop) a domain")},
+    {"desc",
+     N_("Forcefully stop a given domain, but leave its resources intact.")},
     {NULL, NULL}
 };

@@ -4887,8 +4888,8 @@ cmdNetworkDefine(vshControl *ctl, const vshCmd *cmd)
  * "net-destroy" command
  */
 static const vshCmdInfo info_network_destroy[] = {
-    {"help", N_("destroy a network")},
-    {"desc", N_("Destroy a given network.")},
+    {"help", N_("destroy (stop) a network")},
+    {"desc", N_("Forcefully stop a given network.")},
     {NULL, NULL}
 };

@@ -5734,7 +5735,7 @@ cmdInterfaceStart(vshControl *ctl, const vshCmd *cmd)
  */
 static const vshCmdInfo info_interface_destroy[] = {
     {"help", N_("destroy a physical host interface (disable it / \"if-down\")")},
-    {"desc", N_("destroy a physical host interface.")},
+    {"desc", N_("forcefully stop a physical host interface.")},
     {NULL, NULL}
 };

@@ -6293,9 +6294,9 @@ cmdNodeDeviceCreate(vshControl *ctl, const vshCmd *cmd)
  * "nodedev-destroy" command
  */
 static const vshCmdInfo info_node_device_destroy[] = {
-    {"help", N_("destroy a device on the node")},
+    {"help", N_("destroy (stop) a device on the node")},
     {"desc", N_("Destroy a device on the node.  Note that this "
-                          "command destroys devices on the physical host ")},
+                "command destroys devices on the physical host")},
     {NULL, NULL}
 };

@@ -6583,8 +6584,9 @@ cmdPoolBuild(vshControl *ctl, const vshCmd *cmd)
  * "pool-destroy" command
  */
 static const vshCmdInfo info_pool_destroy[] = {
-    {"help", N_("destroy a pool")},
-    {"desc", N_("Destroy a given pool.")},
+    {"help", N_("destroy (stop) a pool")},
+    {"desc",
+     N_("Forcefully stop a given pool. Raw data in the pool is untouched")},
     {NULL, NULL}
 };

diff --git a/tools/virsh.pod b/tools/virsh.pod
index 736b919..8b820d2 100644
--- a/tools/virsh.pod
+++ b/tools/virsh.pod
@@ -405,7 +405,9 @@ but not started.
 Immediately terminate the domain domain-id.  This doesn't give the domain
 OS any chance to react, and it's the equivalent of ripping the power
 cord out on a physical machine.  In most cases you will want to use
-the B<shutdown> command instead.
+the B<shutdown> command instead.  However, this does not delete any
+storage volumes used by the guest, and if the domain is persistent, it
+can be restarted later.

 =item B<domblkstat> I<domain> I<block-device>

@@ -506,7 +508,7 @@ variables, and defaults to C<vi>.

 =item B<managedsave> I<domain-id>

-Save and destroy a running domain, so it can be restarted from the same
+Save and destroy (stop) a running domain, so it can be restarted from the same
 state at a later time.  When the virsh B<start> command is next run for
 the domain, it will automatically be started from this saved state.

@@ -957,8 +959,8 @@ not instantiated.

 =item B<net-destroy> I<network>

-Destroy a given virtual network specified by its name or UUID. This takes
-effect immediately.
+Destroy (stop) a given virtual network specified by its name or UUID. This
+takes effect immediately.

 =item B<net-dumpxml> I<network>

@@ -1032,7 +1034,7 @@ not started.

 =item B<iface-destroy> I<interface>

-Destroy a given host interface, such as by running "if-down" to
+Destroy (stop) a given host interface, such as by running "if-down" to
 disable that interface from active use. This takes effect immediately.

 =item B<iface-dumpxml> I<interface> optional I<--inactive>
@@ -1162,7 +1164,7 @@ I<type>.

 =item B<pool-destroy> I<pool-or-uuid>

-Destroy a given I<pool> object. Libvirt will no longer manage the
+Destroy (stop) a given I<pool> object. Libvirt will no longer manage the
 storage described by the pool object, but the raw data contained in
 the pool is not changed, and can be later recovered with
 B<pool-create>.
@@ -1171,7 +1173,7 @@ B<pool-create>.

 Destroy the resources used by a given I<pool> object. This operation
 is non-recoverable.  The I<pool> object will still exist after this
-command.
+command, ready for the creation of new storage volumes.

 =item B<pool-dumpxml> I<pool-or-uuid>

-- 
1.7.4.4