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