| blob | 29aadfe0919db4ec59be8ebd527e2d474462846e |
1 .\" keymaps.5 - Copyright (C) Andries Brouwer 1998
2 .\" May be freely distributed.
3 .\" @(#)keymaps.5 1.10 940130 aeb
4 .TH KEYMAPS 5 "24 April 1998"
5 .SH NAME
6 keymaps \- keyboard table descriptions for loadkeys and dumpkeys
7 .SH DESCRIPTION
8 .IX "keymaps" "" "\fLkeymaps\fR \(em keyboard table descriptions for loadkeys and dumpkeys" ""
9 .IX "loadkeys" "keyboard table descriptions" "\fLloadkeys\fR" "keyboard table descriptions"
10 .IX "dumpkeys" "keyboard table descriptions" "\fLdumpkeys\fR" "keyboard table descriptions"
11 .IX keyboard "table descriptions for loadkeys and dumpkeys" keyboard "table descriptions for \fLloadkeys\fR and \fLdumpkeys\fR"
12 .IX "translation tables"
13 .LP
14 These files are used by
15 .BR loadkeys (1)
16 to modify the translation tables used by the kernel keyboard driver
17 and generated by
18 .BR dumpkeys (1)
19 from those translation tables.
20 .LP
21 The format of these files is vaguely similar to the one accepted by
22 .BR xmodmap (1).
23 The file consists of charset or key or string definition lines
24 interspersed with comments.
25 .LP
26 Comments are introduced with
27 .B !
28 or
29 .B #
30 characters and continue to the end of the line. Anything following one
31 of these characters on that line is ignored. Note that comments need
32 not begin from column one as with
33 .BR xmodmap (1).
34 .LP
35 The syntax of keymap files is line oriented; a complete definition
36 must fit on a single logical line. Logical lines can, however, be split
37 into multiple physical lines by ending each subline with the backslash
38 character (\\).
39 .SH "INCLUDE FILES"
40 A keymap can include other keymaps using the syntax
41 .LP
42 .RS
43 include "pathname"
44 .RE
45 .LP
46 .SH "CHARSET DEFINITIONS"
47 A character set definition line is of the form:
48 .LP
49 .RS
50 .EX
51 charset "iso-8859-x"
52 .EE
53 .RE
54 .LP
55 It defines how following keysyms are to be interpreted.
56 For example, in iso-8859-1 the symbol mu (or micro) has code 0265,
57 while in iso-8859-7 the letter mu has code 0354.
58 .SH "COMPLETE KEYCODE DEFINITIONS"
59 Each complete key definition line is of the form:
60 .LP
61 .RS
62 .nf
63 .BI keycode " keynumber " = " keysym keysym keysym" \fR...
64 .fi
65 .RE
66 .LP
67 .I keynumber
68 is the internal identification number of the key, roughly equivalent to
69 the scan code of it.
70 .I keynumber
71 can be given in decimal, octal or hexadecimal notation.
72 Octal is denoted by a leading zero and hexadecimal by the prefix
73 .B 0x.
74 .LP
75 Each of the
76 .I keysyms
77 represent keyboard actions, of which up to 256 can be bound to a single
78 key. The actions available include outputting character codes or
79 character sequences, switching consoles or keymaps, booting the machine
80 etc. (The complete list can be obtained from dumpkeys(1) by saying
81 .BI " dumpkeys -l"
82 \&.)
83 .LP
84 Each
85 .I keysym
86 may be prefixed by a '+' (plus sign), in wich case this keysym is treated
87 as a "letter" and therefore affected by the "CapsLock" the same way as by
88 "Shift" (to be correct, the CapsLock inverts the Shift state).
89 The ASCII letters ('a'-'z' and 'A'-'Z') are made CapsLock'able by default.
90 If Shift+CapsLock should not produce a lower case symbol, put lines like
91 .LP
92 .RS
93 .nf
94 .BI "keycode 30 = +a A"
95 .fi
96 .RE
97 .LP
98 in the map file.
99 .LP
100 Which of the actions bound to a given key is taken when it is pressed
101 depends on what modifiers are in effect at that moment.
102 The keyboard driver supports 8 modifiers. These modifiers are labeled
103 (completely arbitrarily) Shift, AltGr, Control, Alt, ShiftL, ShiftR,
104 CtrlL and CtrlR.
105 Each of these modifiers has an associated weight of power of two
106 according to the following table:
107 .LP
108 .RS
109 .TP 24
110 .I modifier
111 .I weight
112 .TP 24
113 Shift
114 1
115 .PD 0
116 .TP 24
117 AltGr
118 2
119 .TP 24
120 Control
121 4
122 .TP 24
123 Alt
124 8
125 .TP 24
126 ShiftL
127 16
128 .TP 24
129 ShiftR
130 32
131 .TP 24
132 CtrlL
133 64
134 .TP 24
135 CtrlR
136 128
137 .PD
138 .RE
139 .LP
140 The effective action of a key is found out by adding up the weights of
141 all the modifiers in effect. By default, no modifiers are in effect, so
142 action number zero, i.e. the one in the first column in a key definition
143 line, is taken when the key is pressed or released. When e.g. Shift and
144 Alt modifiers are in effect, action number nine (from the 10th column)
145 is the effective one.
146 .LP
147 Changing the state of what modifiers are in effect can be achieved by
148 binding appropriate key actions to desired keys. For example, binding
149 the symbol Shift to a key sets the Shift modifier in effect when that
150 key is pressed and cancels the effect of that modifier when the key is
151 released. Binding AltGr_Lock to a key sets AltGr in effect when the key
152 is pressed and cancels the effect when the key is pressed again.
153 (By default Shift, AltGr, Control and Alt are bound to the keys that bear
154 a similar label; AltGr may denote the right Alt key.)
155 .LP
156 Note that you should be very careful when binding the modifier keys,
157 otherwise you can end up with an unusable keyboard mapping. If you for
158 example define a key to have Control in its first column and leave the
159 rest of the columns to be VoidSymbols, you're in trouble. This is
160 because pressing the key puts Control modifier in effect and the
161 following actions are looked up from the fifth column (see the table
162 above). So, when you release the key, the action from the fifth column
163 is taken. It has VoidSymbol in it, so nothing happens. This means that
164 the Control modifier is still in effect, although you have released the key.
165 Re-pressing and releasing the key has no effect. To avoid this,
166 you should always define all the columns to have the same modifier
167 symbol. There is a handy short-hand notation for this, see below.
168 .LP
169 .I keysyms
170 can be given in decimal, octal, hexadecimal, unicode or symbolic notation.
171 The numeric notations use the same format as with
172 .IR keynumber .
173 Unicode notation is "U+" followed by four hexadecimal digits.
174 The symbolic notation resembles that used by
175 .BR xmodmap (1).
176 Notable differences are the number symbols. The numeric
177 symbols '0', ..., '9' of
178 .BR xmodmap (1)
179 are replaced with the corresponding words 'zero', 'one', ... 'nine' to
180 avoid confusion with the numeric notation.
181 .LP
182 It should be noted that using numeric notation for the
183 .I keysyms
184 is highly unportable as the key action numbers may vary from one kernel
185 version to another and the use of numeric notations is thus strongly
186 discouraged. They are intended to be used only when you know there is a
187 supported keyboard action in your kernel for which your current version
188 of
189 .BR loadkeys (1)
190 has no symbolic name.
191 .LP
192 There is a number of short-hand notations to add readability and reduce
193 typing work and the probability of typing-errors.
194 .LP
195 First of all, you can give a map specification line, of the form
196 .LP
197 .RS
198 .EX
199 keymaps 0-2,4-5,8,12
200 .EE
201 .RE
202 .LP
203 to indicate that the lines of the keymap will not specify all 256 columns,
204 but only the indicated ones. (In the example: only the plain, Shift,
205 AltGr, Control, Control+Shift, Alt and Control+Alt maps, that is, 7 columns
206 instead of 256.)
207 When no such line is given, the keymaps 0-M will be defined, where
208 M+1 is the maximum number of entries found in any definition line.
209 .LP
210 Next, you can leave off any trailing VoidSymbol entries from a key
211 definition line. VoidSymbol denotes a keyboard action which produces no
212 output and has no other effects either. For example, to define key
213 number 30 to output 'a' unshifted, 'A' when pressed with Shift and do
214 nothing when pressed with AltGr or other modifiers, you can write
215 .LP
216 .RS
217 .nf
218 keycode 30 = a A
219 .fi
220 .RE
221 .LP
222 instead of the more verbose
223 .LP
224 .RS
225 .nf
226 keycode 30 = a A VoidSymbol VoidSymbol \\
227 VoidSymbol VoidSymbol VoidSymbol ...
228 .fi
229 .RE
230 .LP
231 For added convenience, you can usually get off with still more terse
232 definitions. If you enter a key definition line with only and exactly
233 one action code after the equals sign, it has a special meaning. If the
234 code (numeric or symbolic) is not an ASCII letter, it means the code
235 is implicitly replicated through all columns being defined.
236 If, on the other hand, the action code is an ASCII character in the
237 range 'a', ..., 'z' or 'A', ..., 'Z' in the ASCII collating sequence,
238 the following definitions are made for the different modifier combinations,
239 provided these are actually being defined.
240 (The table lists the two possible cases:
241 either the single action code is a lower case letter,
242 denoted by 'x' or an upper case letter, denoted by 'Y'.)
243 .LP
244 .RS 4
245 .TP 24
246 .I modifier
247 .I symbol
248 .TP 24
249 none
250 x Y
251 .PD 0
252 .TP 24
253 Shift
254 X y
255 .TP 24
256 AltGr
257 x Y
258 .TP 24
259 Shift+AltGr
260 X y
261 .TP 24
262 Control
263 Control_x Control_y
264 .TP 24
265 Shift+Control
266 Control_x Control_y
267 .TP 24
268 AltGr+Control
269 Control_x Control_y
270 .TP 24
271 Shift+AltGr+Control
272 Control_x Control_y
273 .TP 24
274 Alt
275 Meta_x Meta_Y
276 .TP 24
277 Shift+Alt
278 Meta_X Meta_y
279 .TP 24
280 AltGr+Alt
281 Meta_x Meta_Y
282 .TP 24
283 Shift+AltGr+Alt
284 Meta_X Meta_y
285 .TP 24
286 Control+Alt
287 Meta_Control_x Meta_Control_y
288 .TP 24
289 Shift+Control+Alt
290 Meta_Control_x Meta_Control_y
291 .TP 24
292 AltGr+Control+Alt
293 Meta_Control_x Meta_Control_y
294 .TP 24
295 Shift+AltGr+Control+Alt
296 Meta_Control_x Meta_Control_y
297 .PD
298 .RE
299 .LP
300 .SH "SINGLE MODIFIER DEFINITIONS"
301 All the previous forms of key definition lines always define all the M+1
302 possible modifier combinations being defined, whether the line actually
303 contains that many action codes or not.
304 There is, however, a variation of the definition
305 syntax for defining only single actions to a particular modifier
306 combination of a key. This is especially useful, if you load a keymap
307 which doesn't match your needs in only some modifier combinations, like
308 AltGr+function keys. You can then make a small local file redefining
309 only those modifier combinations and loading it after the main file.
310 The syntax of this form is:
311 .LP
312 .BR "" { " plain " "| <modifier sequence> } " keycode
313 .I keynumber
314 .B =
315 .I keysym
316 .LP
317 , e.g.,
318 .RS
319 .EX
320 .nf
321 plain keycode 14 = BackSpace
322 control alt keycode 83 = Boot
323 alt keycode 105 = Decr_Console
324 alt keycode 106 = Incr_Console
325 .fi
326 .EE
327 .RE
328 Using "plain" will define only the base entry of a
329 key (i.e. the one with no modifiers in effect) without affecting the
330 bindings of other modifier combinations of that key.
331 .SH "STRING DEFINITIONS"
332 In addition to comments and key definition lines, a keymap can
333 contain string definitions. These are used to define what each function
334 key action code sends. The syntax of string definitions is:
335 .LP
336 .RS
337 .B string
338 .I keysym
339 .B =
340 .BI
341 "text"
342 .RE
343 .LP
344 .I text
345 can contain literal characters, octal character codes in the format of
346 backslash followed by up to three octal digits, and the three escape
347 sequences \fB\\n\fP, \fB\\\\\fP, and \fB\\"\fP,
348 for newline, backslash and quote, respectively.
349 .SH "COMPOSE DEFINITIONS"
350 Then there may also be compose definitions. They have syntax
351 .LP
352 .RS
353 .BI "compose '" char "' '" char "' to '" char "'"
354 .RE
355 and describe how two bytes are combined to form a third one
356 (when a dead accent or compose key is used).
357 This is used to get accented letters and the like on a standard
358 keyboard.
359 .SH ABBREVIATIONS
360 Various abbreviations can be used with kbd-0.96 and later.
361 .TP
362 .B "strings as usual"
363 Defines the usual values of the strings (but not the keys
364 they are bound to).
365 .TP
366 \fBcompose as usual for "iso-8859-1"\fP
367 Defines the usual compose combinations.
368 .LP
369 To find out what
370 .I keysyms
371 there are available for use in keymaps, use the command
372 .LP
373 .RS
374 .nf
375 .B dumpkeys --long-info
376 .fi
377 .RE
378 .LP
379 Unfortunately, there is currently no description of what each symbol
380 does. It has to be guessed from the name or figured out from the kernel
381 sources.
382 .LP
383 .SH EXAMPLES
384 (Be careful to use a keymaps line, like the first line of `dumpkeys`,
385 or "keymaps 0-15" or so.)
386 .LP
387 The following entry exchanges the left Control key and the Caps Lock
388 key on the keyboard:
389 .LP
390 .RS
391 .nf
392 keycode 58 = Control
393 keycode 29 = Caps_Lock
394 .fi
395 .RE
396 .LP
397 Key number 58 is normally the Caps Lock key, and key number 29 is
398 normally the Control key.
399 .LP
400 The following entry sets the Shift and Caps Lock keys to behave more
401 nicely, like in older typewriters. That is, pressing Caps Lock key once
402 or more sets the keyboard in CapsLock state and pressing either of the
403 Shift keys releases it.
404 .LP
405 .RS
406 .nf
407 keycode 42 = Uncaps_Shift
408 keycode 54 = Uncaps_Shift
409 keycode 58 = Caps_On
410 .fi
411 .RE
412 .LP
413 The following entry sets the layout of the edit pad in the enhanced
414 keyboard to be more like that in the VT200 series terminals:
415 .LP
416 .RS
417 .nf
418 keycode 102 = Insert
419 keycode 104 = Remove
420 keycode 107 = Prior
421 shift keycode 107 = Scroll_Backward
422 keycode 110 = Find
423 keycode 111 = Select
424 control alt keycode 111 = Boot
425 control altgr keycode 111 = Boot
426 .fi
427 .RE
428 .LP
429 Here's an example to bind the string "du\\ndf\\n" to the key AltGr-D. We use
430 the "spare" action code F100 not normally bound to any key.
431 .LP
432 .RS
433 .nf
434 altgr keycode 32 = F100
435 string F100 = "du\\ndf\\n"
436 .LP
437 .SH "SEE ALSO"
438 .BR loadkeys (1),
439 .BR dumpkeys (1),
440 .BR showkey (1),
441 .BR xmodmap (1)