From c2d4b4f70495c64befd02d38e63eb16d5ab17cca Mon Sep 17 00:00:00 2001
From: Eric Blake <eblake@redhat.com>
Date: Wed, 31 Aug 2011 08:47:48 -0600
Subject: [PATCH] virsh: improve send-key documentation

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.
---
 tools/virsh.c   | 13 +++-----
 tools/virsh.pod | 81 +++++++++++++++++++++++++++++++++++++++++++++++--
 2 files changed, 83 insertions(+), 11 deletions(-)

diff --git a/tools/virsh.c b/tools/virsh.c
index e0b52b490e..d43123c6e4 100644
--- a/tools/virsh.c
+++ b/tools/virsh.c
@@ -3749,21 +3749,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 b3cbff84ac..b90c26eecf 100644
--- a/tools/virsh.pod
+++ b/tools/virsh.pod
@@ -310,9 +310,86 @@ 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>...
+=item B<send-key> I<domain-id> [I<--codeset> B<codeset>]
+[I<--holdtime> B<holdtime>] I<keycode>...
 
-Send keys to the guest
+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.  If I<--holdtime> is given, each keystroke
+will be held for that many milliseconds.  The default codeset is
+B<linux>, but use of the I<--codeset> option allows other codesets to
+be chosen.
+
+=over 4
+
+=item B<linux>
+
+The numeric values are those defined by the Linux generic input
+event subsystem. The symbolic names match the corresponding
+Linux key constant macro names.
+
+=item B<xt>
+
+The numeric values are those defined by the original XT keyboard
+controller. No symbolic names are provided
+
+=item B<atset1>
+
+The numeric values are those defined by the AT keyboard controller,
+set 1 (aka XT compatible set). Extended keycoes from B<atset1>
+may differ from extended keycodes in the B<xt> codeset. No symbolic
+names are provided
+
+=item B<atset2>
+
+The numeric values are those defined by the AT keyboard controller,
+set 2. No symbolic names are provided
+
+=item B<atset3>
+
+The numeric values are those defined by the AT keyboard controller,
+set 3 (aka PS/2 compatible set). No symbolic names are provided
+
+=item B<os_x>
+
+The numeric values are those defined by the OS-X keyboard input
+subsystem. The symbolic names match the corresponding OS-X key
+constant macro names
+
+=item B<xtkbd>
+
+The numeric values are those defined by the Linux KBD device.
+These are a variant on the original XT codeset, but often with
+different encoding for extended keycodes. No symbolic names are
+provided.
+
+=item B<win32>
+
+The numeric values are those defined by the Win32 keyboard input
+subsystem. The symbolic names match the corresponding Win32 key
+constant macro names
+
+=item B<usb>
+
+The numeric values are those defined by the USB HID specification
+for keyboard input. No symbolic names are provided
+
+=item B<rfb>
+
+The numeric values are those defined by the RFB extension for sending
+raw keycodes. These are a variant on the XT codeset, but extended
+keycodes have the low bit of the second byte set, instead of the high
+bit of the first byte. No symbolic names are provided.
+
+=back
+
+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>