lisp/term/README

   1    This directory contains files of elisp that customize Emacs for certain
   2 terminal types.
   3
   4    When Emacs starts, it checks the TERM environment variable to see what type
   5 of terminal the user is running on, checks for an elisp file named
   6 "term/${TERM}.el", and if one exists, loads it.  If that doesn't yield a file
   7 that exists, the last hyphen and what follows it is stripped.  If that doesn't
   8 yield a file that exists, the previous hyphen is stripped, and so on until all
   9 hyphens are gone.  For example, if the terminal type is `aaa-48-foo', Emacs
  10 will try first `term/aaa-48-foo.el', then `term/aaa-48.el' and finally
  11 `term/aaa.el'.
  12
  13    When writing terminal packages, there are some things it is good to keep in
  14 mind.
  15
  16    First, about keycap names.  Your terminal package can create any keycap
  17 cookies it likes, but there are good reasons to stick to the set recognized by
  18 the X-windows code whenever possible.  The key symbols recognized by Emacs
  19 are listed in src/term.c; look for the string `keys' in that file.
  20
  21    For one thing, it means that you'll have the same Emacs key bindings on in
  22 terminal mode as on an X console.  If there are differences, you can bet
  23 they'll frustrate you after you've forgotten about them.
  24
  25    For another, the X keysms provide a standard set of names that Emacs knows
  26 about.  It tries to bind many of them to useful things at startup, before your
  27 .emacs is read (so you can override them).  In some ways, the X keysym standard
  28 is a admittedly poor one; it's incomplete, and not well matched to the set of
  29 `virtual keys' that UNIX terminfo(3) provides.  But, trust us, the alternatives
  30 were worse.
  31
  32    This doesn't mean that if your terminal has a "Cokebottle" key you shouldn't
  33 define a [cokebottle] keycap.  But if you must define cookies that aren't in
  34 that set, try to pattern them on the standard terminfo variable names for
  35 clarity; also, for a fighting chance that your binding may be useful to someone
  36 else someday.
  37
  38    For example, if your terminal has a `find' key, observe that terminfo
  39 supports a key_find capability and call your cookie [key-find].
  40
  41 Here is a complete list, with corresponding X keysyms.
  42
  43 -----------------------------------------------------------------------------
  44 Variable name   cap     X Keysym        Description
  45 --------------  ---     ------------    -------------------------------------
  46 key_down        kd      down            Sent by terminal down arrow key
  47 key_up          ku      up              Sent by terminal up arrow key
  48 key_left        kl      left            Sent by terminal left arrow key
  49 key_right       kr      right           Sent by terminal right arrow key
  50 key_home        kh      home            Sent by home key.
  51 key_backspace   kb                      Sent by backspace key
  52 key_dl          kd      deleteline      Sent by delete line key.
  53 key_il          kA      insertline      Sent by insert line.
  54 key_dc          kD                      Sent by delete character key.
  55 key_ic          kI      insertchar (1)  Sent by ins char/enter ins mode key.
  56 key_eic         KM                      Sent by rmir or smir in insert mode.
  57 key_clear       kC                      Sent by clear screen or erase key.
  58 key_eos         kS                      Sent by clear-to-end-of-screen key.
  59 key_eol         kE                      Sent by clear-to-end-of-line key.
  60 key_sf          kF                      Sent by scroll-forward/down key
  61 key_sr          kR                      Sent by scroll-backward/up key
  62 key_npage       kN      next (2)        Sent by next-page key
  63 key_ppage       kP      prior (2)       Sent by previous-page key
  64 key_stab        kT                      Sent by set-tab key
  65 key_ctab        kt                      Sent by clear-tab key
  66 key_catab       ka                      Sent by clear-all-tabs key.
  67 key_enter       @8      kp-enter        Enter/send (unreliable)
  68 key_print       %9      print           print or copy
  69 key_ll          kH                      Sent by home-down key
  70 key_a1          K1      kp-1            Upper left of keypad
  71 key_a3          K3      kp-3            Upper right of keypad
  72 key_b2          K2      kp-5            Center of keypad
  73 key_c1          K4      kp-7            Lower left of keypad
  74 key_c3          K5      kp-9            Lower right of keypad
  75 key_btab        kB      backtab         Back tab key
  76 key_beg         @1      begin           beg(inning) key
  77 key_cancel      @2      cancel          cancel key
  78 key_close       @3                      close key
  79 key_command     @4      execute (3)     cmd (command) key
  80 key_copy        @5                      copy key
  81 key_create      @6                      create key
  82 key_end         @7      end             end key
  83 key_exit        @9                      exit key
  84 key_find        @0                      find key
  85 key_help        %1                      help key
  86 key_mark        %2                      mark key
  87 key_message     %3                      message key
  88 key_move        %4                      move key
  89 key_next        %5      next (2)        next object key
  90 key_open        %6                      open key
  91 key_options     %7      menu (3)        options key
  92 key_previous    %8      previous (2)    previous object key
  93 key_redo        %0      redo            redo key
  94 key_reference   &1                      ref(erence) key
  95 key_refresh     &2                      refresh key
  96 key_replace     &3                      replace key
  97 key_restart     &4      reset (3)       restart key
  98 key_resume      &5                      resume key
  99 key_save        &6                      save key
 100 key_sbeg        &9                      shifted beginning key
 101 key_select      *6      select          select key
 102 key_suspend     &7                      suspend key
 103 key_undo        &8      undo            undo key
 104
 105 key_scancel     &0                      shifted cancel key
 106 key_scommand    *1                      shifted command key
 107 key_scopy       *2                      shifted copy key
 108 key_screate     *3                      shifted create key
 109 key_sdc         *4                      shifted delete char key
 110 key_sdl         *5                      shifted delete line key
 111 key_send        *7                      shifted end key
 112 key_seol        *8                      shifted clear line key
 113 key_sexit       *9                      shifted exit key
 114 key_sf          kF                      shifted find key
 115 key_shelp       #1                      shifted help key
 116 key_shome       #2                      shifted home key
 117 key_sic         #3                      shifted input key
 118 key_sleft       #4                      shifted left arrow key
 119 key_smessage    %a                      shifted message key
 120 key_smove       %b                      shifted move key
 121 key_snext       %c                      shifted next key
 122 key_soptions    %d                      shifted options key
 123 key_sprevious   %e                      shifted prev key
 124 key_sprint      %f                      shifted print key
 125 key_sredo       %g                      shifted redo key
 126 key_sreplace    %h                      shifted replace key
 127 key_sright      %i                      shifted right arrow
 128 key_sresume     %j                      shifted resume key
 129 key_ssave       !1                      shifted save key
 130 key_suspend     !2                      shifted suspend key
 131 key_sundo       !3                      shifted undo key
 132
 133 key_f0          k0      f0 (4)          function key 0
 134 key_f1          k1      f1              function key 1
 135 key_f2          k2      f2              function key 2
 136 key_f3          k3      f3              function key 3
 137 key_f4          k4      f4              function key 4
 138 key_f5          k5      f5              function key 5
 139 key_f6          k6      f6              function key 6
 140 key_f7          k7      f7              function key 7
 141 key_f8          k8      f8              function key 8
 142 key_f9          k9      f9              function key 9
 143 key_f10         k;      f10 (4)         function key 10
 144 key_f11         F1      f11             function key 11
 145   :             :          :                    :
 146 key_f35         FP      f35             function key 35
 147 key_f36         FQ                      function key 36
 148   :             :          :                    :
 149 key_f64         k1                      function key 64
 150
 151 (1) The terminfo documentation says this may be the 'insert character' or
 152     `enter insert mode' key.  Accordingly, key_ic is mapped to the `insertchar'
 153     keysym if there is also a key_dc key; otherwise it's mapped to `insert'.
 154     The presumption is that keyboards with `insert character' keys usually
 155     have `delete character' keys paired with them.
 156
 157 (2) If there is no key_next key but there is a key_npage key, key_npage
 158     will be bound to the `next' keysym.  If there is no key_previous key but
 159     there is a key_ppage key, key_ppage will be bound to the `previous' keysym.
 160
 161 (3) Sorry, these are not exact but they're the best we can do.
 162
 163 (4) The uses of the "k0" capability are inconsistent; sometimes it
 164     describes F10, whereas othertimes it describes F0 and "k;" describes F10.
 165     Emacs attempts to politely accommodate both systems by testing for
 166     "k;", and if it is present, assuming that "k0" denotes F0, otherwise F10.
 167 -----------------------------------------------------------------------------
 168
 169    The following X keysyms do *not* have terminfo equivalents.   These are
 170 the cookies your terminal package will have to set up itself, if you want them:
 171
 172         break
 173         system
 174         user
 175         kp-backtab
 176         kp-space
 177         kp-tab
 178         kp-f1
 179         kp-f2
 180         kp-f3
 181         kp-f4
 182         kp-multiply
 183         kp-add
 184         kp-separator
 185         kp-subtract
 186         kp-decimal
 187         kp-divide
 188         kp-0
 189         kp-2
 190         kp-4
 191         kp-6
 192         kp-8
 193         kp-equal
 194
 195    In general, you should not bind any of the standard keysym names to
 196 functions in a terminal package.  There's code in loaddefs.el that does that;
 197 the less people make exceptions to that, the more consistent an interface Emacs
 198 will have across different keyboards.  Those exceptions should go in your
 199 .emacs file.
 200
 201    Finally, if you're using a USL UNIX or a Sun box or anything else with the
 202 USL version of curses(3) on it, bear in mind that the original curses(3) had
 203 (and still has) a very much smaller set of keycaps.  In fact, the reliable
 204 ones were just the arrow keys and the first ten function keys.  If you care
 205 about making your package portable to older Berkeley machines, don't count on
 206 the setup code to bind anything else.
 207
 208    If your terminal's arrow key sequences are so funky that they conflict with
 209 normal Emacs key bindings, the package should set up a function called
 210 (enable-foo-arrow-keys), where `foo' becomes the terminal name, and leave
 211 it up to the user's .emacs file whether to call it.
 212
 213    Before writing a terminal-support package, it's a good idea to read the
 214 existing ones and learn the common conventions.