contrib/README.xterm

   1                      Solving keyboard related problems
   2                                with XTERM
   3                         and GNU Midnight Commander
   4                        (and other programs as well).
   5
   6 Xterm brings a handful of problems with input keys and their translations.
   7 Some of these problems include xterm's failure to make a difference between
   8 shifted and not shifted function keys (many keyboards do not have more than
   9 10 or 12 function keys, so it is useful to generate higher function keys (11
  10 - 20) by pressing Shift and function key - 10 (e.g. Shift+F3 is F13). Xterm
  11 also doesn't send Alt+character and Meta+character as something other than
  12 plain character. Also, home key does not work on most systems. And keypad
  13 operator characters (+, -, /, *) send different sequences than normal +, -,
  14 /, * (or sometimes do not send anything).
  15
  16 Please note that if you want to use the Alt key on an XTerm, you have to
  17 make sure you use:
  18
  19 XTerm*eightBitInput: false
  20
  21 Otherwise, you will just get accented keys.
  22
  23 Fortunately this can be solved, since xterm is written on top of the
  24 X Toolkit Intrinsics, which has a built-in feature of event translation
  25 tables that can be specified using X resources. This doesn't apply to rxvt,
  26 where the only solution to this problem would be patching rxvt's sources and
  27 recompiling. So from now on, we are speaking only about xterm (and its
  28 modifications, like color_xterm and ansi_xterm).
  29
  30 Xterm brings two new Xt widgets (if you don't know what they are it doesn't
  31 matter), vt100 and tek4014 (these are used for the terminal display in vt100
  32 and tektronics mode). The translation table is specified in
  33 *vt100.translations and *tek4014.translations resources.
  34 You can see a sample in xterm.ad file in this directory.
  35
  36 If you want to install these translations, bear in mind that you have to
  37 keep your terminfo and termcap in sync with these. So if you install
  38 xterm.ad, you have to install xterm.ti and xterm.tcap (or do necessary
  39 changes yourself).
  40
  41 xterm.ad has to be loaded into the Xrm (X resource manager), either by xterm
  42 itself or by xrdb utility. There are many places you may want to install it
  43 to; the decision is yours. Preferably it should go to your personal
  44 $HOME/.Xdefaults file (if you have any). This file is automatically loaded
  45 using xrdb whenever you start the X server (it is done by startx and openwin
  46 scripts). Another possibility is to put this into
  47 $X11ROOT/lib/X11/app-defaults/XTerm or wherever your app-defaults file of
  48 xterm is and whatever is its name (sometimes it will have to be XTerm-ansi,
  49 XTerm-color etc.) Or you can put this anywhere and call
  50           xrdb xterm.ad
  51 from any script you run on X11 startup.
  52
  53 xterm.ti (terminfo database source) is installed by running `tic xterm.ti'.
  54 tic will compile it and place it into your TERMINFO directory.
  55
  56 xterm.tcap is the xterm (and xterm-color) termcap entry. It is based on the
  57 newest termcap database from http://www.ccil.org/~esr/ncurses.html, but
  58 contains a bunch of changes to make all the above mentioned keys work. Even
  59 if mc is compiled so that it uses terminfo, you need to install the termcap
  60 entry so that other programs which use termcap will behave correctly. You
  61 have to edit your /etc/termcap and replace xterm and xterm-color entries
  62 with those from xterm.tcap.
  63
  64 The xterm.ad translation table contains many items (some of them may be
  65 unnecessary) but are included only to make it work on all different xterms
  66 (xterm terminfo and termcap databases have different sequences for the same
  67 keys in every different database, so xterm.ad works as a standard to make
  68 xterm.ti and termcap happy). If you find that xterm works well even if you
  69 delete some lines from the translations, feel free to do it.
  70
  71 By default,  Alt+character keys received by mc are generated in xterm.ad by
  72 Alt modifier plus the key. On some systems, you may want to change this to
  73 the Meta modifier (e.g. if the Alt modifier is missing). You do it by
  74 replacing a letter s at the beginning of table lines with letter m.
  75
  76 And what you might want to know, if you are going to change anything, is:
  77 Each line looks like
  78         modifiers<Key>keyname: string("something") \n\
  79 where modifiers can be:
  80 a for alt
  81 m for meta
  82 c for control
  83 button1 (2, 3) for mouse buttons.
  84
  85   The string is generated whenever the named key is pressed while the
  86 modifiers are in a state matching the specification.  Naming a modifier
  87 specifies that the modifier must be pressed.  A ~ in front of a modifier
  88 name specifies that the modifier must NOT be pressed.  If the set of
  89 modifiers is preceded by !, unmentioned modifiers must not be
  90 pressed; otherwise their state is ignored.
  91
  92 After <Key> you specify a name of the key (if you don't know a canonical
  93 name of any key, see $X11ROOT/include/X11/keysymdef.h (keynames are the
  94 names there without leading XK_). Then there can be any sequence of string
  95 statements which send the string to the tty line, as if the user typed that
  96 sequence of characters. If it has the form string(0xXX), where X's are
  97 hexadecimal digits, then the ascii character of that value is sent rather
  98 than 0xXX.
  99
 100 This is a subset of all the translation table features. If you want a
 101 complete reference, see xterm(1) and X Toolkit Intrinsics manual Appendix B.
 102
 103 Please, if you find any problems or errors in this stuff, let me know by
 104 e-mail to
 105 mc-devel@lists.midnight-commander.org.
 106
 107
 108
 109