From 085d241531e6b28363dd2f117c6cf4646cf9e626 Mon Sep 17 00:00:00 2001
From: Eric Blake <eblake@redhat.com>
Date: Wed, 6 Jul 2011 15:42:47 -0600
Subject: [PATCH] virsh: make destroy sound less scary

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 2e776ec2f1..3cdf043946 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}
 };
 
@@ -4877,8 +4878,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}
 };
 
@@ -5724,7 +5725,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}
 };
 
@@ -6283,9 +6284,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}
 };
 
@@ -6573,8 +6574,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 736b919118..8b820d2b6e 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>