Link to termkey(7) from other manpages, delete some of the duplicated sections

18 files changed, 49 insertions, 134 deletions

diff --git a/man/termkey_advisereadable.3 b/man/termkey_advisereadable.3
index 2d7ca4a..2c02c41 100644
--- a/man/termkey_advisereadable.3
+++ b/man/termkey_advisereadable.3
@@ -10,7 +10,7 @@ termkey_advisereadable \- read more bytes from the underlying terminal
 .sp
 Link with \fI-ltermkey\fP.
 .SH DESCRIPTION
-\fBtermkey_advisereadable\fP() informs the instance that new input may be available on the underlying file descriptor and so it should call \fBread\fP(2) to obtain it. If at least one more byte was read it will return \fBTERMKEY_RES_AGAIN\fP to indicate it may be useful to call \fBtermkey_getkey\fP(3) again. If no more input was read then \fBTERMKEY_RES_NONE\fP is returned. If there was no buffer space remaining, then \fBTERMKEY_RES_ERROR\fP is returned with \fIerrno\fP set to \fBENOMEM\fP. If no filehandle is associated with this instance, \fBTERMKEY_RES_ERROR\fP is returned with \fIerrno\fP set to \fBEBADF\fP.
+\fBtermkey_advisereadable\fP() informs the \fBtermkey\fP(7) instance that new input may be available on the underlying file descriptor and so it should call \fBread\fP(2) to obtain it. If at least one more byte was read it will return \fBTERMKEY_RES_AGAIN\fP to indicate it may be useful to call \fBtermkey_getkey\fP(3) again. If no more input was read then \fBTERMKEY_RES_NONE\fP is returned. If there was no buffer space remaining, then \fBTERMKEY_RES_ERROR\fP is returned with \fIerrno\fP set to \fBENOMEM\fP. If no filehandle is associated with this instance, \fBTERMKEY_RES_ERROR\fP is returned with \fIerrno\fP set to \fBEBADF\fP.
 .PP
 This function, along with \fBtermkey_getkey\fP(3) make it possible to use the termkey instance in an asynchronous program. To provide bytes without using a readable file handle, use \fBtermkey_push_bytes\fP(3).
 .PP
@@ -27,7 +27,7 @@ No nore bytes were read.
 .B TERMKEY_RES_ERROR
 An IO error occured. \fIerrno\fP will be preserved. If the error is \fBEINTR\fP then this will only be returned if \fBTERMKEY_FLAG_EINTR\fP flag is not set; if it is then the IO operation will be retried instead.
 .SH "SEE ALSO"
-.BR termkey_new (3),
 .BR termkey_getkey (3),
 .BR termkey_waitkey (3),
-.BR termkey_set_waittime (3)
+.BR termkey_set_waittime (3),
+.BR termkey (7)
diff --git a/man/termkey_canonicalise.3 b/man/termkey_canonicalise.3
index 980e400..47fb21f 100644
--- a/man/termkey_canonicalise.3
+++ b/man/termkey_canonicalise.3
@@ -10,18 +10,13 @@ termkey_canonicalise \- canonicalise a key event
 .sp
 Link with \fI-ltermkey\fP.
 .SH DESCRIPTION
-\fBtermkey_canonicalise\fP(3) modifies the key event structure given by \fIkey\fP according to the canonicalisation flags set on the given \fItk\fP instance. This operation is performed implicitly by \fBtermkey_getkey\fP(3), \fBtermkey_waitkey\fP(3) and \fBtermkey_strpkey\fP(3), and is also provided explicitly by this function.
+\fBtermkey_canonicalise\fP(3) modifies the key event structure given by \fIkey\fP according to the canonicalisation flags set on the given \fBtermkey\fP instance. This operation is performed implicitly by \fBtermkey_getkey\fP(3), \fBtermkey_waitkey\fP(3) and \fBtermkey_strpkey\fP(3), and is also provided explicitly by this function.
 .PP
-The canonicalisation operation is affected by the following flags:
-.TP
-.B TERMKEY_CANON_SPACESYMBOL
-If this flag is set then a Unicode space character is represented using the \fBTERMKEY_SYM_SPACE\fP symbol. If this flag is not set, it is represented by the U+0020 Unicode codepoint.
-.TP
-.B TERMKEY_CANON_DELBS
-If this flag is set then an ASCII DEL character is represented by the \fBTERMKEY_SYM_BACKSPACE\fP symbol. If not, it is represented by \fBTERMKEY_SYM_DEL\fP. An ASCII BS character is always represented by \fBTERMKEY_SYM_BACKSPACE\fP, regardless of this flag.
+See \fBtermkey\fP(7) for a list of canonicalisation flags.
 .SH "RETURN VALUE"
 \fBtermkey_canonicalise\fP() returns no value.
 .SH "SEE ALSO"
 .BR termkey_set_canonflags (3),
 .BR termkey_waitkey (3),
-.BR termkey_strpkey (3)
+.BR termkey_strpkey (3),
+.BR termkey (7)
diff --git a/man/termkey_get_buffer_remaining.3 b/man/termkey_get_buffer_remaining.3
index 6f85f99..09dfcb4 100644
--- a/man/termkey_get_buffer_remaining.3
+++ b/man/termkey_get_buffer_remaining.3
@@ -10,12 +10,12 @@ termkey_get_buffer_remaining \- returns the free buffer space
 .sp
 Link with \fI-ltermkey\fP.
 .SH DESCRIPTION
-A termkey instance contains a buffer of pending bytes that have been read by \fBtermkey_advisereadable\fP(3) or provided by \fBtermkey_push_bytes\fP(3) but not yet consumed by \fBtermkey_getkey\fP(3). \fBtermkey_get_buffer_remaining\fP() returns the number of bytes of buffer space currently free in the termkey instance.
+\fBtermkey_get_buffer_remaining\fP() returns the number of bytes of buffer space currently free in the \fBtermkey\fP(7) instance. These bytes are free to use by \fBtermkey_push_bytes\fP(3), or may be filled by \fBtermkey_advisereadable\fP(3).
 .PP
 .SH "RETURN VALUE"
 \fBtermkey_get_buffer_remaining\fP() returns a size in bytes.
 .SH "SEE ALSO"
-.BR termkey_new (3),
 .BR termkey_push_bytes (3),
 .BR termkey_advisereadable (3),
-.BR termkey_getkey (3)
+.BR termkey_getkey (3),
+.BR termkey (7)
diff --git a/man/termkey_get_fd.3 b/man/termkey_get_fd.3
index d94de5f..86b60b6 100644
--- a/man/termkey_get_fd.3
+++ b/man/termkey_get_fd.3
@@ -10,9 +10,10 @@ termkey_get_fd \- obtain the file descriptor for the terminal
 .sp
 Link with \fI-ltermkey\fP.
 .SH DESCRIPTION
-\fBtermkey_get_fd\fP() returns the file descriptor that was passed as the \fIfd\fP argument to \fBtermkey_new\fP(3).
+\fBtermkey_get_fd\fP() returns the file descriptor that the \fBtermkey\fP(7) instance is using to read bytes from.
 .SH "RETURN VALUE"
 \fBtermkey_get_fd\fP() returns the current file descriptor, or -1 if no file descriptor is associated with this instance.
 .SH "SEE ALSO"
 .BR termkey_new (3),
-.BR termkey_get_flags (3)
+.BR termkey_get_flags (3),
+.BR termkey (7)
diff --git a/man/termkey_get_keyname.3 b/man/termkey_get_keyname.3
index 5f0119f..42c9ecd 100644
--- a/man/termkey_get_keyname.3
+++ b/man/termkey_get_keyname.3
@@ -10,13 +10,11 @@ termkey_get_keyname \- return a string name for a symbolic key
 .sp
 Link with \fI-ltermkey\fP.
 .SH DESCRIPTION
-\fBtermkey_get_keyname\fP() returns a human-readable string name for the symbolic key value given by \fBsym\fP. The returned string is owned by the termkey instance \fItk\fP so should not be modified or freed. The returned pointer is guaranteed to be valid until the termkey instance is released using \fBtermkey_destroy\fP(3). This function is the inverse of \fBtermkey_keyname2sym\fP(3).
+\fBtermkey_get_keyname\fP() returns a human-readable string name for the symbolic key value given by \fBsym\fP. The returned string is owned by the \fBtermkey\fP(7) instance \fItk\fP so should not be modified or freed. The returned pointer is guaranteed to be valid until the instance is released using \fBtermkey_destroy\fP(3). This function is the inverse of \fBtermkey_keyname2sym\fP(3).
 .SH "RETURN VALUE"
 \fBtermkey_get_key\fP() returns a pointer to a string.
 .SH "SEE ALSO"
-.BR termkey_new (3),
-.BR termkey_getkey (3),
-.BR termkey_waitkey (3),
 .BR termkey_lookup_keyname (3),
 .BR termkey_keyname2sym (3),
-.BR termkey_strfkey (3)
+.BR termkey_strfkey (3),
+.BR termkey (7)
diff --git a/man/termkey_getkey.3.sh b/man/termkey_getkey.3.sh
index e5f5a31..f95a439 100644
--- a/man/termkey_getkey.3.sh
+++ b/man/termkey_getkey.3.sh
@@ -13,7 +13,7 @@ termkey_getkey, termkey_getkey_force \- retrieve the next key event
 .sp
 Link with \fI-ltermkey\fP.
 .SH DESCRIPTION
-\fBtermkey_getkey\fP() attempts to retrieve a single keypress event from the buffer, and put it in the structure referred to by \fIkey\fP. It returns one of the following values:
+\fBtermkey_getkey\fP() attempts to retrieve a single keypress event from the \fBtermkey\fP(7) instance buffer, and put it in the structure referred to by \fIkey\fP. It returns one of the following values:
 .in
 .TP
 .B TERMKEY_RES_KEY
@@ -33,48 +33,10 @@ no bytes are waiting in the buffer.
 Neither of these functions will block or perform any IO operations on the underlying filehandle. To use the instance in an asynchronous program, see \fBtermkey_advisereadable\fP(3). For a blocking call suitable for use in a synchronous program, use \fBtermkey_waitkey\fP(3) instead of \fBtermkey_getkey\fP(). For providing input without a readable filehandle, use \fBtermkey_push_bytes\fP(3).
 .PP
 Before returning, this function canonicalises the \fIkey\fP structure according to the rules given for \fBtermkey_canonicalise\fP(3).
-.PP
-The \fITermKeyKey\fP structure is defined as follows:
-.PP
-.in +4n
-.nf
-typedef struct {
-    TermKeyType type;
-    union {
-        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];
-} TermKeyKey;
-.fi
-.in
-.PP
-The \fItype\fP field indicates the type of event, and determines which of the members of the \fIcode\fP union is valid. It will be one of the following constants:
-.TP
-.B TERMKEY_TYPE_UNICODE
-a Unicode codepoint. This value indicates that \fIcode.codepoint\fP is valid, and will contain the codepoint number of the keypress. In Unicode mode (if the \fBTERMKEY_FLAG_UTF8\fP bit is set) this will be its Unicode character number. In raw byte mode, this will contain a single 8-bit byte.
-.TP
-.B TERMKEY_TYPE_FUNCTION
-a numbered function key. This value indicates that \fIcode.number\fP is valid, and contains the number of the numbered function key.
-.TP
-.B TERMKEY_TYPE_KEYSYM
-a symbolic key. This value indicates that \fIcode.sym\fP is valid, and contains the symbolic key value. This is an opaque value which may be passed to \fBtermkey_get_keyname\fP(3).
-.TP
-.B TERMKEY_TYPE_MOUSE
-a mouse button press, release, or movement. The \fIcode.mouse\fP array should be considered opaque. Use \fBtermkey_interpret_mouse\fP(3) 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
-The \fIutf8\fP field is only set on events whose \fItype\fP is \fBTERMKEY_TYPE_UNICODE\fP. It should not be read for other events.
-.PP
-To convert the \fIsym\fP to a symbolic name, see \fBtermkey_get_keyname\fP(3) function. It may instead be easier to convert the entire key event structure to a string, using \fBtermkey_strfkey\fP(3).
 .SH "RETURN VALUE"
 \fBtermkey_getkey\fP() returns an enumeration of one of \fBTERMKEY_RES_KEY\fP, \fBTEMRKEY_RES_AGAIN\fP, \fBTERMKEY_RES_NONE\fP or \fBTERMKEY_RES_EOF\fP. \fBtermkey_getkey_force\fP() returns one of the above, except for \fBTERMKEY_RES_AGAIN\fP.
 .SH EXAMPLE
-The following example program prints details of every keypress until the user presses "Ctrl-C". It demonstrates how to use the termkey instance in a typical \fBpoll\fP()-driven asynchronous program, which may include mixed IO with other file handles.
+The following example program prints details of every keypress until the user presses "Ctrl-C". It demonstrates how to use the \fBtermkey\fP instance in a typical \fBpoll\fP()-driven asynchronous program, which may include mixed IO with other file handles.
 .PP
 .in +4n
 .nf
@@ -84,13 +46,8 @@ cat <<EOF
 .in
 .fi
 .SH "SEE ALSO"
-.BR termkey_new (3),
 .BR termkey_advisereadable (3),
-.BR termkey_push_bytes (3),
 .BR termkey_waitkey (3),
-.BR termkey_set_waittime (3),
-.BR termkey_get_keyname (3),
-.BR termkey_interpret_mouse (3),
-.BR termkey_strfkey (3),
-.BR termkey_keycmp (3)
+.BR termkey_get_waittime (3),
+.BR termkey (7)
 EOF
diff --git a/man/termkey_interpret_mouse.3 b/man/termkey_interpret_mouse.3
index 6963054..c817441 100644
--- a/man/termkey_interpret_mouse.3
+++ b/man/termkey_interpret_mouse.3
@@ -38,6 +38,6 @@ If passed a \fIkey\fP event of the type \fBTERMKEY_TYPE_MOUSE\fP, this function
 .PP
 For other event types it will return \fBTERMKEY_RES_NONE\fP, and its effects on any variables whose pointers were passed in, are undefined.
 .SH "SEE ALSO"
-.BR termkey_new (3),
 .BR termkey_waitkey (3),
 .BR termkey_getkey (3),
+.BR termkey (7)
diff --git a/man/termkey_keycmp.3 b/man/termkey_keycmp.3
index 3eed66c..2993f2b 100644
--- a/man/termkey_keycmp.3
+++ b/man/termkey_keycmp.3
@@ -19,7 +19,6 @@ Two structures of differing type are ordered \fBTERMKEY_TYPE_UNICODE\fP, \fBTERM
 .SH NOTES
 This function does not perform any canonicalisation of the key structures, and performs a simple comparison of the fields in the structures. In particular, it will not consider as equal \fBTERMKEY_TYPE_UNICODE\fP containing the Space codepoint (U+0020) vs. \fBTERMKEY_TYPE_KEYSYM\fP containing \fBTERMKEY_SYM_SPACE\fP. 
 .SH "SEE ALSO"
-.BR termkey_new (3),
-.BR termkey_getkey (3),
 .BR termkey_strpkey (3),
-.BR termkey_canonicalise (3)
+.BR termkey_canonicalise (3),
+.BR termkey (7)
diff --git a/man/termkey_keyname2sym.3 b/man/termkey_keyname2sym.3
index 095a465..cd75140 100644
--- a/man/termkey_keyname2sym.3
+++ b/man/termkey_keyname2sym.3
@@ -16,7 +16,7 @@ Because the key names are stored in an array indexed by the symbol number, this
 .SH "RETURN VALUE"
 \fBtermkey_keyname2sym\fP() returns a symbolic key constant, or \fBTERMKEY_SYM_UNKNOWN\fP.
 .SH "SEE ALSO"
-.BR termkey_new (3),
 .BR termkey_get_keyname (3),
 .BR termkey_lookup_keyname (3),
-.BR termkey_strpkey (3)
+.BR termkey_strpkey (3),
+.BR termkey (7)
diff --git a/man/termkey_lookup_keyname.3 b/man/termkey_lookup_keyname.3
index bd44411..4525a95 100644
--- a/man/termkey_lookup_keyname.3
+++ b/man/termkey_lookup_keyname.3
@@ -17,7 +17,7 @@ Because the key names are stored in an array indexed by the symbol number, this
 .SH "RETURN VALUE"
 \fBtermkey_lookup_keyname\fP() returns a pointer to the first character after a recognised name, or \fBNULL\fP if the string does not begin with the name of a recognised symbolic key.
 .SH "SEE ALSO"
-.BR termkey_new (3),
 .BR termkey_get_keyname (3),
 .BR termkey_keyname2sym (3),
-.BR termkey_strpkey (3)
+.BR termkey_strpkey (3),
+.BR termkey (7)
diff --git a/man/termkey_new.3 b/man/termkey_new.3
index c4e5783..5e35ff1 100644
--- a/man/termkey_new.3
+++ b/man/termkey_new.3
@@ -12,42 +12,10 @@ termkey_new, termkey_destroy \- create or destroy new termkey instance
 .sp
 Link with \fI\-ltermkey\fP.
 .SH DESCRIPTION
-\fBtermkey_new\fP() creates a new termkey instance connected to the file handle opened by \fIfd\fP using the \fIflags\fP. The \fITermKey\fP structure should be considered opaque; its contents are not intended for use outside of the library. If \fIfd\fP is given the value -1, then no file handle will be associated.
+\fBtermkey_new\fP() creates a new \fBtermkey\fP(7) instance connected to the file handle opened by \fIfd\fP using the \fIflags\fP. The \fITermKey\fP structure should be considered opaque; its contents are not intended for use outside of the library. If \fIfd\fP is given the value -1, then no file handle will be associated.
 .PP
 \fBtermkey_destroy\fP() destroys the given instance and releases any resources controlled by it. It will not close the underlying filehandle given as the \fIfd\fP argument to \fBtermkey_new\fP().
 .PP
-A termkey instance contains a buffer of bytes representing keypresses yet to be returned to the application. This buffer may be fed bytes directly by calling \fBtermkey_push_bytes\fP(3), or by calling \fBtermkey_advisereadable\fP(3) which itself will \fBread\fP(3) them from the filehandle given by \fIfd\fP. Once in the buffer, these bytes can be returned as key press events by calling \fBtermkey_getkey\fP(3). The read and get operations are combined in a single function \fBtermkey_waitkey\fP(3), which may be more convenient to use in the standard case of blocking reads from the \fIstdin\fP filehandle.
-.PP
-The following values may be given as the \fIflags\fP bitmask:
-.TP
-.B TERMKEY_FLAG_NOINTERPRET
-Do not attempt to interpret \fBC0\fP codes into keysyms. Instead report them as plain "Ctrl-letter" events.
-.TP
-.B TERMKEY_FLAG_CONVERTKP
-Convert xterm's alternative keypad symbols into the plain
-.SM ASCII
-codes they would represent.
-.TP
-.B TERMKEY_FLAG_RAW
-Ignore locale settings; do not attempt to recombine UTF-8 sequences. Instead report only raw values.
-.TP
-.B TERMKEY_FLAG_UTF8
-Ignore locale settings; force UTF-8 recombining on. This flag overrides \fBTERMKEY_FLAG_RAW\fP.
-.TP
-.B TERMKEY_FLAG_NOTERMIOS
-Even if the terminal file descriptor \fIfd\fP represents a
-.SM TTY
-device, do not call the \fBtcsetattr\fP(3) \fBtermios\fP function on it to set it to canonical input mode.
-.TP
-.B TERMKEY_FLAG_SPACESYMBOL
-Report space as being a symbolic key rather than a Unicode codepoint.
-.TP
-.B TERMKEY_FLAG_CTRLC
-Disable the \fBSIGINT\fP behaviour of \fICtrl-C\fP. If this flag is provided, then \fICtrl-C\fP will be available as a normal keypress, rather than sending the process group a \fBSIGINT\fP. This flag only takes effect without \fBTERMKEY_FLAG_NOTERMIOS\fP; with it, none of the signal keys are disabled anyway.
-.TP
-.B TERMKEY_FLAG_EINTR
-Without this flag, IO operations are retried when interrupted by a signal (\fBEINTR\fP). With this flag the \fBTERMKEY_RES_ERROR\fP result is returned instead.
-.PP
 When the constructor is invoked, it attempts to detect if the current locale is UTF-8 aware or not, and sets either the \fBTERMKEY_FLAG_UTF8\fP or \fBTERMKEY_FLAG_RAW\fP flag. One of these two bits will always be in effect. The current flags in effect can be obtained by \fBtermkey_get_flags\fP(3).
 .PP
 If a file handle is provided, the terminfo driver may send a string to the terminal before \fBtermkey_new\fP() returns to initialise it, or set the state correctly. This will not be done if no file handle is provided, or if the file handle is a pipe (\fBS_ISFIFO\fP()). In this case it will be the caller's responsibility to ensure the terminal is in the correct mode.
@@ -61,4 +29,5 @@ If successful, \fBtermkey_new\fP() returns a pointer to the new instance. On fai
 .BR termkey_getkey (3),
 .BR termkey_get_flags (3),
 .BR termkey_get_fd (3),
-.BR termkey_get_buffer_remaining (3)
+.BR termkey_get_buffer_remaining (3),
+.BR termkey (7)
diff --git a/man/termkey_push_bytes.3 b/man/termkey_push_bytes.3
index b4e0048..3761034 100644
--- a/man/termkey_push_bytes.3
+++ b/man/termkey_push_bytes.3
@@ -10,14 +10,14 @@ termkey_push_bytes \- supply more bytes to the input buffer
 .sp
 Link with \fI-ltermkey\fP.
 .SH DESCRIPTION
-\fBtermkey_push_bytes\fP() allows more bytes of input to be supplied directly into the input buffer of the termkey instance. If there was no buffer space remaining then -1 is returned with \fIerrno\fP set to \fBENOMEM\fP.
+\fBtermkey_push_bytes\fP() allows more bytes of input to be supplied directly into the input buffer of the \fBtermkey\fP(7) instance. If there was no buffer space remaining then -1 is returned with \fIerrno\fP set to \fBENOMEM\fP.
 .PP
-This function, along with \fBtermkey_getkey\fP(3), makes it possible to use the termkey instance with a source of bytes other than from reading a filehandle.
+This function, along with \fBtermkey_getkey\fP(3), makes it possible to use the \fBtermkey\fP instance with a source of bytes other than from reading a filehandle.
 .PP
 For synchronous usage, \fBtermkey_waitkey\fP(3) performs the input blocking task. For use against a regular stream filehandle that supports \fBread\fP(2), see \fBtermkey_advisereadable\fP(3).
 .SH "RETURN VALUE"
 \fBtermkey_push_bytes\fP() the number of bytes consumed from the input (which may be smaller than the length provided, if the buffer runs out of space) or -1 cast to \fBsize_t\fP if an error occurs, in which case \fIerrno\fP is set accordingly.
 .SH "SEE ALSO"
-.BR termkey_new (3),
 .BR termkey_getkey (3),
-.BR termkey_advisereadable (3)
+.BR termkey_advisereadable (3),
+.BR termkey (7)
diff --git a/man/termkey_set_canonflags.3 b/man/termkey_set_canonflags.3
index 2bc125c..7aa3349 100644
--- a/man/termkey_set_canonflags.3
+++ b/man/termkey_set_canonflags.3
@@ -11,11 +11,11 @@ termkey_set_canonflags, termkey_get_canonflags \- control the canonicalisation f
 .sp
 Link with \fI-ltermkey\fP.
 .SH DESCRIPTION
-\fBtermkey_set_canonflags\fP() changes the set of canonicalisation flags in the termkey instance to those given by \fInewflags\fP. For detail on the available flags and their meaning, see \fBtermkey_set_canonflags\fP(3).
+\fBtermkey_set_canonflags\fP() changes the set of canonicalisation flags in the \fBtermkey\fP(7) instance to those given by \fInewflags\fP. For detail on the available flags and their meaning, see the \fBtermkey\fP manpage.
 .PP
 \fBtermkey_get_canonflags\fP() returns the value set by the last call to \fBtermkey_canonicalise\fP().
 .SH "RETURN VALUE"
 \fBtermkey_set_flags\fP() returns no value. \fBtermkey_get_flags\fP() returns the current canonicalisation flags.
 .SH "SEE ALSO"
-.BR termkey_new (3),
-.BR termkey_canonicalise (3)
+.BR termkey_canonicalise (3),
+.BR termkey (7)
diff --git a/man/termkey_set_flags.3 b/man/termkey_set_flags.3
index 1d8f4e8..10bdcac 100644
--- a/man/termkey_set_flags.3
+++ b/man/termkey_set_flags.3
@@ -11,12 +11,11 @@ termkey_set_flags, termkey_get_flags \- control the operational flags
 .sp
 Link with \fI-ltermkey\fP.
 .SH DESCRIPTION
-\fBtermkey_set_flags\fP() changes the set of operation flags in the termkey instance to those given by \fInewflags\fP.
+\fBtermkey_set_flags\fP() changes the set of operation flags in the \fBtermkey\fP(7) instance to those given by \fInewflags\fP.
 .PP
 \fBtermkey_get_flags\fP() returns the value set by the last call to \fBtermkey_set_flags\fP(), or the value given to the constructor.
-.PP
-When the constructor is invoked, it attempts to detect if the current locale is UTF-8 aware or not, and sets either the \fBTERMKEY_FLAG_UTF8\fP or \fBTERMKEY_FLAG_RAW\fP flag. One of these two bits will always be returned by \fBtermkey_get_flags\fP().
 .SH "RETURN VALUE"
 \fBtermkey_set_flags\fP() returns no value. \fBtermkey_get_flags\fP() returns the current operational flags.
 .SH "SEE ALSO"
-.BR termkey_new (3)
+.BR termkey_new (3),
+.BR termkey (7)
diff --git a/man/termkey_set_waittime.3 b/man/termkey_set_waittime.3
index 0cc042f..972c03f 100644
--- a/man/termkey_set_waittime.3
+++ b/man/termkey_set_waittime.3
@@ -17,6 +17,6 @@ Link with \fI-ltermkey\fP.
 .SH "RETURN VALUE"
 \fBtermkey_set_waittime\fP() returns no value. \fBtermkey_get_waittime\fP() returns the current wait time in miliseconds.
 .SH "SEE ALSO"
-.BR termkey_new (3),
 .BR termkey_getkey (3),
-.BR termkey_waitkey (3)
+.BR termkey_waitkey (3),
+.BR termkey (7)
diff --git a/man/termkey_strfkey.3 b/man/termkey_strfkey.3
index 7767952..f712405 100644
--- a/man/termkey_strfkey.3
+++ b/man/termkey_strfkey.3
@@ -43,4 +43,5 @@ When formatting a \fBTERMKEY_TYPE_UNICODE\fP key structure, this function uses t
 .BR termkey_getkey (3),
 .BR termkey_waitkey (3),
 .BR termkey_get_keyname (3),
-.BR termkey_strpkey (3)
+.BR termkey_strpkey (3),
+.BR termkey (7)
diff --git a/man/termkey_strpkey.3 b/man/termkey_strpkey.3
index f9de839..74665b8 100644
--- a/man/termkey_strpkey.3
+++ b/man/termkey_strpkey.3
@@ -32,4 +32,5 @@ After a successful parse, \fBtermkey_strpkey\fP() returns a pointer to the first
 .SH "SEE ALSO"
 .BR termkey_new (3),
 .BR termkey_strfkey (3),
-.BR termkey_keycmp (3)
+.BR termkey_keycmp (3),
+.BR termkey (7)
diff --git a/man/termkey_waitkey.3.sh b/man/termkey_waitkey.3.sh
index 9155656..ff6ea38 100644
--- a/man/termkey_waitkey.3.sh
+++ b/man/termkey_waitkey.3.sh
@@ -12,13 +12,11 @@ termkey_waitkey \- wait for and retrieve the next key event
 .sp
 Link with \fI-ltermkey\fP.
 .SH DESCRIPTION
-\fBtermkey_waitkey\fP(3) attempts to retrieve a single keypress event from the buffer, and put it in the structure referred to by \fIkey\fP. If successful it will return \fBTERMKEY_RES_KEY\fP to indicate that the structure now contains a new keypress event. If nothing is in the buffer it will block until one is available. If no events are ready and the input stream is now closed, will return \fBTERMKEY_RES_EOF\fP. If no filehandle is associated with this instance, \fBTERMKEY_RES_ERROR\fP is returned with \fIerrno\fP set to \fBEBADF\fP.
+\fBtermkey_waitkey\fP(3) attempts to retrieve a single keypress event from the \fBtermkey\fP(7) instance buffer, and put it in the structure referred to by \fIkey\fP. If successful it will return \fBTERMKEY_RES_KEY\fP to indicate that the structure now contains a new keypress event. If nothing is in the buffer it will block until one is available. If no events are ready and the input stream is now closed, will return \fBTERMKEY_RES_EOF\fP. If no filehandle is associated with this instance, \fBTERMKEY_RES_ERROR\fP is returned with \fIerrno\fP set to \fBEBADF\fP.
 .PP
 Before returning, this function canonicalises the \fIkey\fP structure according to the rules given for \fBtermkey_canonicalise\fP(3).
 .PP
-For details of the \fITermKeyKey\fP structure, see \fBtermkey_getkey\fP(3).
-.PP
-Some keypresses generate multiple bytes from the terminal. Because there may be network or other delays between the terminal and an application using termkey, \fBtermkey_waitkey\fP() will attempt to wait for the remaining bytes to arrive if it detects the start of a multibyte sequence. If no more bytes arrive within a certain time, then the bytes will be reported as they stand, even if this results in interpreting a partially-complete Escape sequence as a literal Escape key followed by some normal letters or other symbols. The amount of time to wait can be set by \fBtermkey_set_waittime\fP(3).
+Some keypresses generate multiple bytes from the terminal. Because there may be network or other delays between the terminal and an application using \fBtermkey\fP, \fBtermkey_waitkey\fP() will attempt to wait for the remaining bytes to arrive if it detects the start of a multibyte sequence. If no more bytes arrive within a certain time, then the bytes will be reported as they stand, even if this results in interpreting a partially-complete Escape sequence as a literal Escape key followed by some normal letters or other symbols. The amount of time to wait can be set by \fBtermkey_set_waittime\fP(3).
 .SH "RETURN VALUE"
 \fBtermkey_waitkey\fP() returns one of the following constants:
 .TP
@@ -41,10 +39,7 @@ cat <<EOF
 .in
 .fi
 .SH "SEE ALSO"
-.BR termkey_new (3),
 .BR termkey_getkey (3),
 .BR termkey_set_waittime (3),
-.BR termkey_get_keyname (3),
-.BR termkey_strfkey (3),
-.BR termkey_keycmp (3)
+.BR termkey (7)
 EOF