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

[Daniel P. Berrange]

On Wed, Aug 31, 2011 at 08:49:28AM -0600, Eric Blake wrote:
> 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


I think we have to describe the codesets a bit more too....



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> 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 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.

Daniel
-- 
|: http://berrange.com      -o-    http://www.flickr.com/photos/dberrange/ :|
|: http://libvirt.org              -o-             http://virt-manager.org :|
|: http://autobuild.org       -o-         http://search.cpan.org/~danberr/ :|
|: http://entangle-photo.org       -o-       http://live.gnome.org/gtk-vnc :|