[libvirt] [PATCH] virsh: improve send-key documentation

[Eric Blake]

The 'virsh man' description of send-key was incomplete and used the
old style (literal 'optional name' instead of '[name]' metasyntax).
Meanwhile, none of the other virsh help texts include examples, so
I moved it out of virsh help and into the man page.

* tools/virsh.pod (send-key): Give better details.
* tools/virsh.c (info_send_key): Drop example from here.
---

Red Hat QE found this: https://bugzilla.redhat.com/show_bug.cgi?id=699847

 tools/virsh.c   |   13 ++++---------
 tools/virsh.pod |   20 +++++++++++++++++---
 2 files changed, 21 insertions(+), 12 deletions(-)

diff --git a/tools/virsh.c b/tools/virsh.c
index 49034ae..8500a03 100644
--- a/tools/virsh.c
+++ b/tools/virsh.c
@@ -3718,21 +3718,16 @@ cmdInjectNMI(vshControl *ctl, const vshCmd *cmd)
  */
 static const vshCmdInfo info_send_key[] = {
     {"help", N_("Send keycodes to the guest")},
-    {"desc", N_("Send keycodes to the guest, the keycodes must be integers\n"
-                "    Examples:\n\n"
-                "        virsh # send-key <domain> 37 18 21\n"
-                "        virsh # send-key <domain> KEY_RIGHTCTRL KEY_C\n"
-                "        virsh # send-key <domain> --codeset xt 37 18 21\n"
-                "        virsh # send-key <domain> --holdtime 1000 0x15 18 0xf\n"
-                )},
+    {"desc", N_("Send keycodes (integers or symbolic names) to the guest")},
     {NULL, NULL}
 };

 static const vshCmdOptDef opts_send_key[] = {
     {"domain", VSH_OT_DATA, VSH_OFLAG_REQ, N_("domain name, id or uuid")},
-    {"codeset", VSH_OT_STRING, VSH_OFLAG_REQ_OPT, N_("the codeset of keycodes, default:linux")},
+    {"codeset", VSH_OT_STRING, VSH_OFLAG_REQ_OPT,
+     N_("the codeset of keycodes, default:linux")},
     {"holdtime", VSH_OT_INT, VSH_OFLAG_REQ_OPT,
-                 N_("the time (in millsecond) how long the keys will be held")},
+     N_("the time (in millseconds) how long the keys will be held")},
     {"keycode", VSH_OT_ARGV, VSH_OFLAG_REQ, N_("the key code")},
     {NULL, 0, 0, NULL}
 };
diff --git a/tools/virsh.pod b/tools/virsh.pod
index 2cd0f73..5c417f9 100644
--- a/tools/virsh.pod
+++ b/tools/virsh.pod
@@ -310,9 +310,23 @@ running B<virsh suspend>.  When in a paused state the domain will still
 consume allocated resources like memory, but will not be eligible for
 scheduling by the hypervisor.

-=item B<send-key> I<domain-id> optional I<--codeset> B<codeset> optional I<--holdtime> B<holdtime> B<keycode>...
-
-Send keys to the guest
+=item B<send-key> I<domain-id> [I<--codeset> B<codeset>]
+[I<--holdtime> B<holdtime>] I<keycode>...
+
+Parse the I<keycode> sequence as keystrokes to send to I<domain-id>.
+Each I<keycode> can either be a numeric value or a symbolic name from
+the corresponding codeset.  The default code set is B<linux>, but
+use of I<--codeset> can specify B<xt>, B<atset1>, B<atset2>, B<atset3>,
+B<os_x>, B<xt_kbd>, B<usb>, B<win32>, or B<rfb> instead.  If I<--holdtime>
+is given, each keystroke will be held for that many milliseconds.
+
+B<Examples>
+  # send three strokes 'k', 'e', 'y', using xt codeset
+  virsh send-key dom --codeset xt 37 18 21
+  # send one stroke 'right-ctrl+C'
+  virsh send-key dom KEY_RIGHTCTRL KEY_C
+  # send a tab, held for 1 second
+  virsh send-key --holdtime 1000 0xf

 =item B<shutdown>

-- 
1.7.4.4