Introduction
============

The libt3key library provides functions for retrieving the character sequences
used by terminals to represent keys pressed by the user. Although the terminfo
database provides part of this information, it lacks information for the
sequences returned by modern terminals/terminal emulators for many combinations
of modifiers with other keys. For example, many terminal emulators provide
separate character sequences for Control combined with the cursor keys, which
is not stored in the terminfo database.

Many programs contain their own databases with this information. This library
tries to be a database usable by many programs, such that all programs can
benefit from the information collected.

libt3key is part of the Tilde Terminal Toolkit (T3) [https://os.ghalkes.nl/t3/]

libt3key is licensed under the GNU General Public License version 3. See the
file COPYING for details.


Documentation
=============

The full documentation for libt3key can be generated using doxygen. The
documentation for the current version can be found at
https://os.ghalkes.nl/doc/libt3key.


Prerequisites and installation
==============================

libt3key requires GNU libtool to be compiled. Furthermore, it requires
libt3config and the (n)curses library, or ncurses's libtinfo for access to the
terminfo database. The t3learnkeys program may be compiled with X11 support, in
which case either the XCB or Xlib libraries and headers are also required.

There are two ways in which to compile libt3key:

Using the configure script:
---

$ ./configure
or
$ ./configure --prefix=/usr
(see ./configure --help for more tuning options)
$ make all
$ make install
(assumes working install program)

Manually editing the Makefile to suit your computer:
---

$ cp Makefile.in Makefile

Edit the values for the different variables, using the comments in the
Makefile for guidance, to suit your environment.

$ make all
$ make install
(assumes working install program)

The t3keyc utility uses the following non-ANSI functions: symlink. Furhtermore
The (optional but recommended) t3learnkeys program uses the following non-ANSI
functions: select, usleep, isatty, read, lfind, tcgetattr, tcsetattr and
snprintf. All these should be available on a recent Un*x system.

The Makefiles in the distribution should work on all POSIX compatible make's.
They have been tested using both GNU make and BSD make.


Reporting bugs
==============

If you think you have found a bug, please check that you are using the latest
version of libt3key [https://os.ghalkes.nl/t3/libt3key.html]. When
reporting bugs, please include a minimal example that demonstrates the problem.


Author
======

Gertjan Halkes <libt3key@ghalkes.nl>
