--- /dev/null
+ This directory contains files of elisp that customize Emacs for certain
+terminal types. When Emacs starts, it checks the TERM environment variable to
+see what type of terminal the user is running on, checks for an elisp file
+named "term/${TERM}.el", and if one exists, loads it.
+
+ When writing terminal packages, there are some things it is good to keep in
+mind.
+
+ First, about keycap names. Your terminal package can create any keycap
+cookies it likes, but there are good reasons to stick to the set recognized by
+the X-windows code whenever possible. The X key symbols recognized by Emacs
+are listed in src/term.c; look for the string `keys' in that file.
+
+ For one thing, it means that you'll have the same Emacs key bindings on in
+terminal mode as on an X console. If there are differences, you can bet
+they'll frustrate you after you've forgotten about them.
+
+ For another, the X keysms provide a standard set of names that Emacs knows
+about. It tries to bind many of them to useful things at startup, before your
+.emacs is read (so you can override them). In some ways, the X keysym standard
+is a admittedly poor one; it's incomplete, and not well matched to the set of
+`virtual keys' that UNIX terminfo(3) provides. But, trust us, the alternatives
+were worse.
+
+ This doesn't mean that if your terminal has a "Cokebottle" key you shouldn't
+define a [cokebottle] keycap. But if you must define cookies that aren't in
+that set, try to pattern them on the standard terminfo variable names for
+clarity; also, for a fighting chance that your binding may be useful to someone
+else someday.
+
+ For example, if your terminal has a `find' key, observe that terminfo
+supports a key_find capability and call your cookie [key-find].
+
+Here is a complete list, with corresponding X keysyms.
+
+-----------------------------------------------------------------------------
+Variable name cap X Keysym Description
+-------------- --- ------------ -------------------------------------
+key_down kd down Sent by terminal down arrow key
+key_up ku up Sent by terminal up arrow key
+key_left kl left Sent by terminal left arrow key
+key_right kr right Sent by terminal right arrow key
+key_home kh home Sent by home key.
+key_backspace kb Sent by backspace key
+key_dl kd deleteline Sent by delete line key.
+key_il kA insertline Sent by insert line.
+key_dc kD Sent by delete character key.
+key_ic kI insertchar (1) Sent by ins char/enter ins mode key.
+key_eic KM Sent by rmir or smir in insert mode.
+key_clear kC Sent by clear screen or erase key.
+key_eos kS Sent by clear-to-end-of-screen key.
+key_eol kE Sent by clear-to-end-of-line key.
+key_sf kF Sent by scroll-forward/down key
+key_sr kR Sent by scroll-backward/up key
+key_npage kN next (2) Sent by next-page key
+key_ppage kP prior (2) Sent by previous-page key
+key_stab kT Sent by set-tab key
+key_ctab kt Sent by clear-tab key
+key_catab ka Sent by clear-all-tabs key.
+key_enter @8 kp-enter Enter/send (unreliable)
+key_print %9 print print or copy
+key_ll kH Sent by home-down key
+key_a1 K1 kp-1 Upper left of keypad
+key_a3 K3 kp-3 Upper right of keypad
+key_b2 K2 kp-5 Center of keypad
+key_c1 K4 kp-7 Lower left of keypad
+key_c3 K5 kp-9 Lower right of keypad
+key_btab kB backtab Back tab key
+key_beg @1 begin beg(inning) key
+key_cancel @2 cancel cancel key
+key_close @3 close key
+key_command @4 execute (3) cmd (command) key
+key_copy @5 copy key
+key_create @6 create key
+key_end @7 end end key
+key_exit @9 exit key
+key_find @0 find key
+key_help %1 help key
+key_mark %2 mark key
+key_message %3 message key
+key_move %4 move key
+key_next %5 next (2) next object key
+key_open %6 open key
+key_options %7 menu (3) options key
+key_previous %8 previous (2) previous object key
+key_redo %0 redo redo key
+key_reference &1 ref(erence) key
+key_refresh &2 refresh key
+key_replace &3 replace key
+key_restart &4 reset (3) restart key
+key_resume &5 resume key
+key_save &6 save key
+key_sbeg &9 shifted beginning key
+key_select *6 select select key
+key_suspend &7 suspend key
+key_undo &8 undo undo key
+
+key_scancel &0 shifted cancel key
+key_scommand *1 shifted command key
+key_scopy *2 shifted copy key
+key_screate *3 shifted create key
+key_sdc *4 shifted delete char key
+key_sdl *5 shifted delete line key
+key_send *7 shifted end key
+key_seol *8 shifted clear line key
+key_sexit *9 shifted exit key
+key_sf kF shifted find key
+key_shelp #1 shifted help key
+key_shome #2 shifted home key
+key_sic #3 shifted input key
+key_sleft #4 shifted left arrow key
+key_smessage %a shifted message key
+key_smove %b shifted move key
+key_snext %c shifted next key
+key_soptions %d shifted options key
+key_sprevious %e shifted prev key
+key_sprint %f shifted print key
+key_sredo %g shifted redo key
+key_sreplace %h shifted replace key
+key_sright %i shifted right arrow
+key_sresume %j shifted resume key
+key_ssave !1 shifted save key
+key_suspend !2 shifted suspend key
+key_sundo !3 shifted undo key
+
+key_f0 k0 f0 (4) function key 0
+key_f1 k1 f1 function key 1
+key_f2 k2 f2 function key 2
+key_f3 k3 f3 function key 3
+key_f4 k4 f4 function key 4
+key_f5 k5 f5 function key 5
+key_f6 k6 f6 function key 6
+key_f7 k7 f7 function key 7
+key_f8 k8 f8 function key 8
+key_f9 k9 f9 function key 9
+key_f10 k; f10 (4) function key 10
+key_f11 F1 f11 function key 11
+ : : : :
+key_f35 FP f35 function key 35
+key_f36 FQ function key 36
+ : : : :
+key_f64 k1 function key 64
+
+(1) The terminfo documentation says this may be the 'insert character' or
+ `enter insert mode' key. Accordingly, key_ic is mapped to the `insertchar'
+ keysym if there is also a key_dc key; otherwise it's mapped to `insert'.
+ The presumption is that keyboards with `insert character' keys usually
+ have `delete character' keys paired with them.
+
+(2) If there is no key_next key but there is a key_npage key, key_npage
+ will be bound to the `next' keysym. If there is no key_previous key but
+ there is a key_ppage key, key_ppage will be bound to the `previous' keysym.
+
+(3) Sorry, these are not exact but they're the best we can do.
+
+(4) The uses of the "k0" capability are inconsistent; sometimes it
+ describes F10, whereas othertimes it describes F0 and "k;" describes F10.
+ Emacs attempts to politely accomodate both systems by testing for
+ "k;", and if it is present, assuming that "k0" denotes F0, otherwise F10.
+-----------------------------------------------------------------------------
+
+ The following X keysyms do *not* have terminfo equivalents. These are
+the cookies your terminal package will have to set up itself, if you want them:
+
+ break
+ system
+ user
+ kp-backtab
+ kp-space
+ kp-tab
+ kp-f1
+ kp-f2
+ kp-f3
+ kp-f4
+ kp-multiply
+ kp-add
+ kp-separator
+ kp-subtract
+ kp-decimal
+ kp-divide
+ kp-0
+ kp-2
+ kp-4
+ kp-6
+ kp-8
+ kp-equal
+
+ In general, you should not bind any of the standard keysym names to
+functions in a terminal package. There's code in loaddefs.el that does that;
+the less people make exceptions to that, the more consistent an interface Emacs
+will have across different keyboards. Those exceptions should go in your
+.emacs file.
+
+ Finally, if you're using a USL UNIX or a Sun box or anything else with the
+USL version of curses(3) on it, bear in mind that the original curses(3) had
+(and still has) a very much smaller set of keycaps. In fact, the reliable
+ones were just the arrow keys and the first ten function keys. If you care
+about making your package portable to older Berkeley machines, don't count on
+the setup code to bind anything else.
+
+ If your terminal's arrow key sequences are so funky that they conflict with
+normal Emacs key bindings, the package should set up a function called
+(enable-foo-arrow-keys), where `foo' becomes the terminal name, and leave
+it up to the user's .emacs file whether to call it.
+
+ Before writing a terminal-support package, it's a good idea to read the
+existing ones and learn the common conventions.
HCoop / bpt / emacs.git / commitdiff