Added manpages for (most of) the external API functions

7 files changed, 248 insertions, 3 deletions

diff --git a/Makefile b/Makefile
index 754bafc..84f2e13 100644
--- a/Makefile
+++ b/Makefile
@@ -8,6 +8,8 @@ SONAME=libtermkey.so.0
 PREFIX=/usr/local
 LIBDIR=$(PREFIX)/lib
 INCDIR=$(PREFIX)/include
+MANDIR=$(PREFIX)/share/man
+MAN3DIR=$(MANDIR)/man3
 
 ifeq ($(DEBUG),1)
   CFLAGS_DEBUG=-ggdb -DDEBUG
@@ -29,11 +31,24 @@ clean:
 	rm -f *.o demo
 
 .PHONY: install
-install:
+install: install-inc install-lib install-man
+
+install-inc:
 	install -d $(DESTDIR)$(INCDIR)
 	install -m644 termkey.h $(DESTDIR)$(INCDIR)
+	install -d $(DESTDIR)$(LIBDIR)/pkgconfig
+	sed "s,@PREFIX@,$(PREFIX)," <termkey.pc.in >$(DESTDIR)$(LIBDIR)/pkgconfig/termkey.pc
+
+install-lib:
 	install -d $(DESTDIR)$(LIBDIR)
 	install libtermkey.so $(DESTDIR)$(LIBDIR)/$(SONAME)
 	ln -sf $(SONAME) $(DESTDIR)$(LIBDIR)/libtermkey.so
-	install -d $(DESTDIR)$(LIBDIR)/pkgconfig
-	sed "s,@PREFIX@,$(PREFIX)," <termkey.pc.in >$(DESTDIR)$(LIBDIR)/pkgconfig/termkey.pc
+
+install-man:
+	install -d $(DESTDIR)$(MAN3DIR)
+	for F in *.3; do \
+	  gzip <$$F >$(DESTDIR)$(MAN3DIR)/$$F.gz; \
+	done
+	ln -sf termkey_new.3.gz $(DESTDIR)$(MAN3DIR)/termkey_free.3.gz
+	ln -sf termkey_getkey.3.gz $(DESTDIR)$(MAN3DIR)/termkey_getkey_force.3.gz
+	ln -sf termkey_setwaittime.3.gz $(DESTDIR)$(MAN3DIR)/termkey_getwaittime.3.gz
diff --git a/termkey_get_keyname.3 b/termkey_get_keyname.3
new file mode 100644
index 0000000..cc46460
--- /dev/null
+++ b/termkey_get_keyname.3
@@ -0,0 +1,20 @@
+.TH TERMKEY_GET_KEYNAME 3
+.SH NAME
+termkey_get_keyname \- return a string name for a symbolic key
+.SH SYNOPSIS
+.nf
+.B #include <termkey.h>
+.sp
+.BI "const char *termkey_get_keyname(termkey_t *" tk ", termkey_keysym " sym );
+.fi
+.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_free\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_snprint_key (3)
diff --git a/termkey_getkey.3 b/termkey_getkey.3
new file mode 100644
index 0000000..064dda7
--- /dev/null
+++ b/termkey_getkey.3
@@ -0,0 +1,73 @@
+.TH TERMKEY_GETKEY 3
+.SH NAME
+termkey_getkey, termkey_getkey_force \- retrieve the next key event
+.SH SYNOPSIS
+.nf
+.B #include <termkey.h>
+.sp
+.BI "termkey_result termkey_getkey(termkey_t *" tk ", termkey_key *" key );
+.br
+.BI "termkey_result termkey_getkey_force(termkey_t *" tk ", termkey_key *" key );
+.fi
+.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. 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 return \fBTERMKEY_RES_NONE\fP. If the buffer contains a partial keypress event which does not yet contain all the bytes required, it will return \fBTERMKEY_RES_AGAIN\fP. If no events are ready and the input stream is now closed, will return \fBTERMKEY_RES_EOF\fP.
+.PP
+\fBtermkey_getkey_force\fP is similar to \fBtermkey_getkey\fP but will not return \fBTERMKEY_RES_AGAIN\fP if a partial match is found. Instead, it will force an interpretation of the bytes, even if this means interpreting the start of an Escape-prefixed multi-byte sequence as a literal "Escape" key followed by normal letters.
+.PP
+Neither of these functions will block or perform any IO operations on the underlying filehandle. For a blocking wait, see \fBtermkey_waitkey\fP.
+.PP
+The \fItermkey_key\fP structure is defined as follows:
+.PP
+.in +4n
+.nf
+typedef struct {
+    termkey_type type;
+    union {
+        long           codepoint; /* TERMKEY_TYPE_UNICODE  */
+        int            number;    /* TERMKEY_TYPE_FUNCTION */
+        termkey_keysym sym;       /* TERMKEY_TYPE_KEYSYM   */
+    } code;
+    int modifiers;
+    char utf8[7];
+} termkey_key;
+.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
+.TP
+.B TERMKEY_TYPE_FUNCTION
+a numbered function key
+.TP
+.B TERMKEY_TYPE_KEYSYM
+a symbolic key
+.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_snprint_key\fP(3).
+.SH "RETURN VALUE"
+\fBtermkey_getkey\fP() and \fBtermkey_getkey_force\fP() return one of the following constants:
+.TP
+.B TERMKEY_RES_NONE
+No key event is ready.
+.TP
+.B TERMKEY_RES_KEY
+A key event as been provided.
+.TP
+.B TERMKEY_RES_EOF
+No key events are ready and the terminal has been closed, so no more will arrive.
+.TP
+.B TERMKEY_RES_AGAIN
+No key event is ready yet, but a partial one has been found. This is only returned by \fBtermkey_getkey\fP(). To obtain the partial result even if it never completes, use \fBtermkey_getkey_force\fP().
+.SH "SEE ALSO"
+.BR termkey_new (3),
+.BR termkey_waitkey (3),
+.BR termkey_setwaittime (3),
+.BR termkey_get_keyname (3),
+.BR termkey_snprint_key (3)
diff --git a/termkey_new.3 b/termkey_new.3
new file mode 100644
index 0000000..549be14
--- /dev/null
+++ b/termkey_new.3
@@ -0,0 +1,43 @@
+.TH TERMKEY_NEW 3
+.SH NAME
+termkey_new, termkey_free \- create or destroy new termkey instance
+.SH SYNOPSIS
+.nf
+.B #include <termkey.h>
+.sp
+.BI "termkey_tk *termkey_new(int " fd ", int " flags );
+.br
+.BI "void termkey_free(termkey_t *" tk );
+.fi
+.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 \fBtermkey_tk\fP structure should be considered opaque; its contents are not intended for use outside of the library.
+.PP
+\fBtermkey_free\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
+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() \fBtermios\fP function on it to set it to canonical input mode.
+.SH "RETURN VALUE"
+If successful, \fBtermkey_new\fP() returns a pointer to the new instance. On failure, \fBNULL\fP is returned. \fBtermkey_free\fP() returns no value.
+.SH "SEE ALSO"
+.BR termkey_waitkey (3),
+.BR termkey_getkey (3)
diff --git a/termkey_setwaittime.3 b/termkey_setwaittime.3
new file mode 100644
index 0000000..d97e3ea
--- /dev/null
+++ b/termkey_setwaittime.3
@@ -0,0 +1,23 @@
+.TH TERMKEY_SETWAITTIME 3
+.SH NAME
+termkey_setwaittime, termkey_getwaittime \- control the wait time for multibyte sequences
+.SH SYNOPSIS
+.nf
+.B #include <termkey.h>
+.sp
+.BI "void termkey_setwaittime(termkey_t *" tk ", int " msec );
+.br
+.BI "int termkey_getwaittime(termkey_t *" tk );
+.fi
+.sp
+Link with \fI-ltermkey\fP.
+.SH DESCRIPTION
+\fBtermkey_setwaittime\fP sets the number of miliseconds that \fBtermkey_wait\fP(3) will wait for the remaining bytes of a multibyte sequence if it detects the start of a partially-complete one.
+.PP
+\fBtermkey_getwaittime\fP returns the value set by the last call to \fBtermkey_setwaittime\fP(), or the default value if a different has not been set.
+.SH "RETURN VALUE"
+\fBtermkey_setwaittime\fP() returns no value. \fBtermkey_getwaittime\fP() returns the current wait time in miliseconds.
+.SH "SEE ALSO"
+.BR termkey_new (3),
+.BR termkey_getkey (3),
+.BR termkey_waitkey (3)
diff --git a/termkey_snprint_key.3 b/termkey_snprint_key.3
new file mode 100644
index 0000000..4c67f9d
--- /dev/null
+++ b/termkey_snprint_key.3
@@ -0,0 +1,40 @@
+.TH TERMKEY_SNPRINT_KEY 3
+.SH NAME
+termkey_snprint_key \- format a string representing a key event
+.SH SYNOPSIS
+.nf
+.B #include <termkey.h>
+.sp
+.BI "size_t termkey_snprint_key(termkey_t *" tk ", char *" buffer ", size_t " len ",
+.BI "            termkey_key " key ", termkey_format " format );
+.fi
+.sp
+Link with \fI-ltermkey\fP.
+.SH DESCRIPTION
+\fBtermkey_snprint_key\fP formats a string buffer to contain a human-readable representation of a key event. It fills the \fIbuffer\fP in a way analogous to the \fBsnprintf\fP(3) standard library function.
+.PP
+The \fIformat\fP argument specifies the format of the output, as a bitmask of the following constants:
+.TP
+.B TERMKEY_FORMAT_LONGMOD
+Print full modifier names e.g. "Shift-" instead of abbreviating to "S-".
+.TP
+.B TERMKEY_FORMAT_CARETCTRL
+If the only modifier is \fBTERMKEY_MOD_CTRL\fP on a plain letter, render it as "^X" rather than "Ctrl-X".
+.TP
+.B TERMKEY_FORMAT_ALTISMETA
+Use the name "Meta" or the letter "M" instead of "Alt" or "A".
+.TP
+.B TERMKEY_FORMAT_WRAPBRACKET
+If the key event is a special key instead of unmodified Unicode, wrap it in "<brackets>".
+.PP
+The following shortcuts are provided for common combinations of format bits:
+.TP
+.B TERMKEY_FORMAT_VIM
+Shortcut to set \fBALTISMETA\fP and \fBWRAPBRACKET\fP, to give an output close to the format the \fIvim\fP editor uses.
+.SH "RETURN VALUE"
+\fBtermkey_snprint_key\fP() returns the number of characters written to \fIbuffer\fP.
+.SH "SEE ALSO"
+.BR termkey_new (3),
+.BR termkey_getkey (3),
+.BR termkey_waitkey (3),
+.BR termkey_get_keyname (3)
diff --git a/termkey_waitkey.3 b/termkey_waitkey.3
new file mode 100644
index 0000000..9079dcb
--- /dev/null
+++ b/termkey_waitkey.3
@@ -0,0 +1,31 @@
+.TH TERMKEY_WAITKEY 3
+.SH NAME
+termkey_waitkey \- wait for and retrieve the next key event
+.SH SYNOPSIS
+.nf
+.B #include <termkey.h>
+.sp
+.BI "termkey_result termkey_waitkey(termkey_t *" tk ", termkey_key *" key );
+.fi
+.sp
+Link with \fI-ltermkey\fP.
+.SH DESCRIPTION
+\fBtermkey_waitkey\fP 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.
+.PP
+For details of the \fBtermkey_key\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_setwaittime\fP(3).
+.SH "RETURN VALUE"
+\fBtermkey_waitkey\fP() returns one of the following constants:
+.TP
+.B TERMKEY_RES_KEY
+A key event as been provided.
+.TP
+.B TERMKEY_RES_EOF
+No key events are ready and the terminal has been closed, so no more will arrive.
+.SH "SEE ALSO"
+.BR termkey_new (3),
+.BR termkey_getkey (3),
+.BR termkey_setwaittime (3),
+.BR termkey_get_keyname (3),
+.BR termkey_snprint_key (3)