From 1cdeff872f2a85cd97e8758447e7591eaebf7646 Mon Sep 17 00:00:00 2001
From: Paul LeoNerd Evans <leonerd@leonerd.org.uk>
Date: Fri, 30 Nov 2012 17:06:14 +0000
Subject: [PATCH] Further documentation clarifications on the 'code' field of a
 key event

---
 man/termkey.7 | 11 +++++------
 1 file changed, 5 insertions(+), 6 deletions(-)

diff --git a/man/termkey.7 b/man/termkey.7
index 01ad69c..deae880 100644
--- a/man/termkey.7
+++ b/man/termkey.7
@@ -28,7 +28,6 @@ typedef struct {
         long       codepoint; /* TERMKEY_TYPE_UNICODE  */
         int        number;    /* TERMKEY_TYPE_FUNCTION */
         TermKeySym sym;       /* TERMKEY_TYPE_KEYSYM   */
-        char       mouse[4]   /* TERMKEY_TYPE_MOUSE    */
     } code;
     int modifiers;
     char utf8[7];
@@ -48,16 +47,16 @@ a numbered function key. This value indicates that \fIcode.number\fP is valid, a
 a symbolic key. This value indicates that \fIcode.sym\fP is valid, and contains the symbolic key value.
 .TP
 .B TERMKEY_TYPE_MOUSE
-a mouse button press, release, or movement. The \fIcode.mouse\fP array should be considered opaque.
+a mouse button press, release, or movement. The \fIcode\fP structure should be considered opaque; \fBtermkey_interpret_mouse\fP(3) may be used to interpret it.
 .TP
 .B TERMKEY_TYPE_POSITION
-a cursor position report. The structure should be considered opaque; \fBtermkey_interpret_position\fP(3) may be used to interpret it.
+a cursor position report. The \fIcode\fP structure should be considered opaque; \fBtermkey_interpret_position\fP(3) may be used to interpret it.
 .TP
 .B TERMKEY_TYPE_MODEREPORT
-an ANSI or DEC mode value report. The structure should be considered opaque; \fBtermkey_interpret_modereport\fP(3) may be used to interpret it.
+an ANSI or DEC mode value report. The \fIcode\fP structure should be considered opaque; \fBtermkey_interpret_modereport\fP(3) may be used to interpret it.
 .TP
 .B TERMKEY_TYPE_UNKNOWN_CSI
-an unrecognised CSI sequence. The structure should be considered opaque; \fBtermkey_interpret_csi\fP(3) may be used to interpret it.
+an unrecognised CSI sequence. The \fIcode\fP structure should be considered opaque; \fBtermkey_interpret_csi\fP(3) may be used to interpret it.
 .PP
 The \fImodifiers\fP bitmask is composed of a bitwise-or of the constants \fBTERMKEY_KEYMOD_SHIFT\fP, \fBTERMKEY_KEYMOD_CTRL\fP and \fBTERMKEY_KEYMOD_ALT\fP.
 .PP
@@ -139,7 +138,7 @@ The \fBTERMKEY_TYPE_POSITION\fP event type indicates a cursor position report. T
 .SS Mode Reports
 The \fBTERMKEY_TYPE_MODEREPORT\fP event type indicates an ANSI or DEC mode report. This is typically sent by a terminal in response to the Request Mode command (\f(CWCSI $p\fP or \f(CWCSI ? $p\fP). The event bytes are opaque, but can be obtained by calling \fBtermkey_interpret_modereport\fP(3) passing the event structure and pointers to integers to store the result in.
 .SS Unrecognised CSIs
-The \fBTERMKEY_TYPE_UNKNOWN_CSI\fP event type indicates a CSI sequence that the \fBtermkey\fP does not recognise. It will have been extracted from the stream, but is available to the application to inspect by calling \fBtermkey_interpret_csi\fP(3). It is important that if the application wishes to inspect this sequence it is done immediately, before any other IO operations on the \fBtermkey\fP instance (specifically, before calling \fBtermkey_waitkey\fP() or \fBtermkey_getkey\fP() again), otherwise the buffer space consumed by the sequence will be overwritten.
+The \fBTERMKEY_TYPE_UNKNOWN_CSI\fP event type indicates a CSI sequence that the \fBtermkey\fP does not recognise. It will have been extracted from the stream, but is available to the application to inspect by calling \fBtermkey_interpret_csi\fP(3). It is important that if the application wishes to inspect this sequence it is done immediately, before any other IO operations on the \fBtermkey\fP instance (specifically, before calling \fBtermkey_waitkey\fP() or \fBtermkey_getkey\fP() again), otherwise the buffer space consumed by the sequence will be overwritten. Other types of key event do not suffer this limitation as the \fBTermKeyKey\fP structure is sufficient to contain all the information required.
 .SH "SEE ALSO"
 .BR termkey_new (3),
 .BR termkey_waitkey (3),