home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / gnu / emacs-19.16 / lisp / term / README < prev    next >
Encoding:
Text File  |  1993-06-08  |  8.2 KB  |  215 lines
  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.
  215.