The file format syntax is defined by libt3config. Strings are stored as text delimted by double or single quotes, with quote duplication to include literal quotes and with backslash escaping to include special characters. All values are stored as key-value pairs. Keys start with either a letter (lowercase) or an underscore. Second and later key characters can be a letter, a number or an underscore. Keys starting with a percent sign indicate items in a list, and may occur multiple times. Any characters after a hash (#) character that is not part of a string up to the end of the line are considered comments and are ignored.
For a more thorough description of the syntax, please refer to the libt3config documentation.
When describing keyboard keys, modifiers are encoded in the key-value key by by adding a minus sign (-) followed by one or more of the letters c, m and s (in that order, for control, meta and shift respectively).
A map is defined by a key-value key followed by an open brace, a set of key-value pairs and finaly a closing brace. The key-value pairs in the map are specified as key = value. The permissable keys consist of the special keys %_use, _enter and _leave, and the names for the different keys on the keyboard (as specified in a later section), optionally with modifiers.
Maps may only be defined in the maps section. For example:
maps {
kx {
home = "\e[O"
}
}
The %_use special key can be used to include the key-value pairs of the named map into the current map. The value for %_use should be a list of map quoted names. _enter and _leave keys need not be present in the included map. Maps whose name begins with and underscore are internal maps, and should only be used for inclusion in other maps. %_use may occur multiple times to include different maps.
The _enter key defines the string to send to the terminal to switch the terminal to the mode for which this map defines the keys. The _leave key defines the string to reset the terminal to its original state. For the _enter and _leave keys, the value can be either a terminfo name or a string literal starting with a backslash.
Normal keys should have a string as their value. If a non-keypad and a keypad key share both function and string, only the non-keypad key should be included.
Many terminals provide a so-called Application Keypad (kx) Mode. In this mode, the keys that form the keypad (the numeric entry block, but with NumLock disabled) may send different sequences from the regular cursor keys. Although it is generally inadvisable to rely on the distinction between these keys, switching on Application Keypad Mode for some terminals results in richer information about keys being pressed. For example, the terminal may report modifiers like shift or control in combination with arrow keys.
For this reason, it is advisable to record the keys for both the regular mode (a.k.a. nokx) and Application Keypad (kx) mode.
The "best map", as indicated by the best key, should indicate the map that gives access to the most useful set of key mappings. What "most useful" means is unfortunately not easy to define. Being able to distinghuish between as many combinations of keys and modifiers is of course desirable, but not always the only consideration.
The value associated with the best key is the quoted name of a map defined in the file. The best key should be defined outside any map and is mandatory. Most commonly, it will be set to "kx" (see Application Keypad Mode above).
Many maps are shared by different terminals. For example, the same map is used by both xterm and xterm-256color. By including an aka list, these shared maps can be included under different names. The practical implementation is that a (symbolic) link will be created from the original name to each name specified in the aka list, when using t3keyc (see below).
The values in an aka list should be additional names under which this map should be known.
Some terminals map (a limited range of) shifted function keys to higher numbered functions keys. For example, pressing shift-F1 in rxvt produces the same escape sequence as pressing F11. Because not all terminals do this, or use the same mapping, this information can be specified through the shiftfn key.
The shiftfn key expects a list with three comma separated numbers. The first number represents the base of the mapped range. This is usually 1. The second number represents the end of the mapped range. Common values for this are 10 and 12. The third number represents the mapping of the first function key as indicated by the first number. For example, the list ( 1, 10, 11 ) indicates that pressing shift-F1 will be mapped to F11, shift-F2 will be mapped to F12, up to shift-F10, which will be mapped to F20.
The reason to include this information is to indicate to client programs that the terminal does not produce separate escape sequences for the indicated range of shifted function keys, but it may use the mapped range as an alternative if it so desires. Most current keyboards do not provide more than 12 function keys, but pressing shift in combination with a function key is a common operation. So a client program can choose to interpret the higher numbered function keys as shifted low-numbered function keys instead, thereby providing the expected behavior when the user presses a shifted function key.
Several terminal emulators support the XTerm mouse reporting protocol, or a subset. There are three different things that a terminal emulator may support:
If any of these is supported, you can add xterm_mouse = true to the description of the terminal emulator.
When enabling the mouse modes from a client program (provided the terminal emulator supports it) the enable strings should be sent, in the above order: ESC [?1000h ESC [?1002h ESC [?1005h ESC [?1015h ESC [?1006h
This will ensure that the best mode is automatically selected.
The following is a list of valid names for keyboard keys, followed by a short description of the key.
t3keyc, or the t3key compiler, is a small program to validate keymaps and to create symbolic links based on the aka directives. Typical usage is:
t3keyc --link <file>
t3learnkeys is a program which can be used to create new keymaps. When run, it will ask the user to press the different keys to detect the sequences produced by the terminal. They will be written to a file named after the value of the TERM environment variable.
The first question which is asked is if there are extra modes to include. This can be used if the terminal provides alternate keyboard modes which are not included by default. The default is to record for normal mode (a.k.a. nokx) and application keypad mode (a.k.a. kx). The latter will be skipped if there is no smkx terminfo entry (can be verified by running infocmp).
Some key combinations don't produce any result, which can be signalled to t3learnkeys by pressing the spacebar instead. If a wrong key is pressed by mistake, press control-R to redo the input from the last modifier change. To quit before the learning process is done, press control-C.
WARNING: the program will also ask for combinations like control-alt-delete, which may cause your machine to reboot. If you are unsure about the results the key combination may have, simply press spacebar to skip the entry.
For terminal emulators running in the X11 environment, there is an auto-learn mode activated by --auto-learn, which will emulate pressing the keys. You may have to configure the terminal emulator to accept "SendKey" events for this to work.