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