From dc5ce2331628be2a59eb849e07040d5e76a1f49c Mon Sep 17 00:00:00 2001 From: Paul LeoNerd Evans Date: Sat, 21 Jan 2012 00:52:13 +0000 Subject: Link to termkey(7) from other manpages, delete some of the duplicated sections --- man/termkey_advisereadable.3 | 6 ++--- man/termkey_canonicalise.3 | 13 +++------- man/termkey_get_buffer_remaining.3 | 6 ++--- man/termkey_get_fd.3 | 5 ++-- man/termkey_get_keyname.3 | 8 +++--- man/termkey_getkey.3.sh | 51 +++----------------------------------- man/termkey_interpret_mouse.3 | 2 +- man/termkey_keycmp.3 | 5 ++-- man/termkey_keyname2sym.3 | 4 +-- man/termkey_lookup_keyname.3 | 4 +-- man/termkey_new.3 | 37 +++------------------------ man/termkey_push_bytes.3 | 8 +++--- man/termkey_set_canonflags.3 | 6 ++--- man/termkey_set_flags.3 | 7 +++--- man/termkey_set_waittime.3 | 4 +-- man/termkey_strfkey.3 | 3 ++- man/termkey_strpkey.3 | 3 ++- man/termkey_waitkey.3.sh | 11 +++----- 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 <