| .\" keymaps.5 - Copyright (C) Andries Brouwer 1998 |
| .\" May be freely distributed. |
| .\" @(#)keymaps.5 1.10 940130 aeb |
| .TH KEYMAPS 5 "24 April 1998" |
| .SH NAME |
| keymaps \- keyboard table descriptions for loadkeys and dumpkeys |
| .SH DESCRIPTION |
| .IX "keymaps" "" "\fLkeymaps\fR \(em keyboard table descriptions for loadkeys and dumpkeys" "" |
| .IX "loadkeys" "keyboard table descriptions" "\fLloadkeys\fR" "keyboard table descriptions" |
| .IX "dumpkeys" "keyboard table descriptions" "\fLdumpkeys\fR" "keyboard table descriptions" |
| .IX keyboard "table descriptions for loadkeys and dumpkeys" keyboard "table descriptions for \fLloadkeys\fR and \fLdumpkeys\fR" |
| .IX "translation tables" |
| .LP |
| These files are used by |
| .BR loadkeys (1) |
| to modify the translation tables used by the kernel keyboard driver |
| and generated by |
| .BR dumpkeys (1) |
| from those translation tables. |
| .LP |
| The format of these files is vaguely similar to the one accepted by |
| .BR xmodmap (1). |
| The file consists of charset or key or string definition lines |
| interspersed with comments. |
| .LP |
| Comments are introduced with |
| .B ! |
| or |
| .B # |
| characters and continue to the end of the line. Anything following one |
| of these characters on that line is ignored. Note that comments need |
| not begin from column one as with |
| .BR xmodmap (1). |
| .LP |
| The syntax of keymap files is line oriented; a complete definition |
| must fit on a single logical line. Logical lines can, however, be split |
| into multiple physical lines by ending each subline with the backslash |
| character (\\). |
| .SH "INCLUDE FILES" |
| A keymap can include other keymaps using the syntax |
| .LP |
| .RS |
| include "pathname" |
| .RE |
| .LP |
| .SH "CHARSET DEFINITIONS" |
| A character set definition line is of the form: |
| .LP |
| .RS |
| .EX |
| charset "iso-8859-x" |
| .EE |
| .RE |
| .LP |
| It defines how following keysyms are to be interpreted. |
| For example, in iso-8859-1 the symbol mu (or micro) has code 0265, |
| while in iso-8859-7 the letter mu has code 0354. |
| .SH "COMPLETE KEYCODE DEFINITIONS" |
| Each complete key definition line is of the form: |
| .LP |
| .RS |
| .nf |
| .BI keycode " keynumber " = " keysym keysym keysym" \fR... |
| .fi |
| .RE |
| .LP |
| .I keynumber |
| is the internal identification number of the key, roughly equivalent to |
| the scan code of it. |
| .I keynumber |
| can be given in decimal, octal or hexadecimal notation. |
| Octal is denoted by a leading zero and hexadecimal by the prefix |
| .B 0x. |
| .LP |
| Each of the |
| .I keysyms |
| represent keyboard actions, of which up to 256 can be bound to a single |
| key. The actions available include outputting character codes or |
| character sequences, switching consoles or keymaps, booting the machine |
| etc. (The complete list can be obtained from dumpkeys(1) by saying |
| .BI " dumpkeys -l" |
| \&.) |
| .LP |
| Each |
| .I keysym |
| may be prefixed by a '+' (plus sign), in wich case this keysym is treated |
| as a "letter" and therefore affected by the "CapsLock" the same way as by |
| "Shift" (to be correct, the CapsLock inverts the Shift state). |
| The ASCII letters ('a'-'z' and 'A'-'Z') are made CapsLock'able by default. |
| If Shift+CapsLock should not produce a lower case symbol, put lines like |
| .LP |
| .RS |
| .nf |
| .BI "keycode 30 = +a A" |
| .fi |
| .RE |
| .LP |
| in the map file. |
| .LP |
| Which of the actions bound to a given key is taken when it is pressed |
| depends on what modifiers are in effect at that moment. |
| The keyboard driver supports 9 modifiers. These modifiers are labeled |
| (completely arbitrarily) Shift, AltGr, Control, Alt, ShiftL, ShiftR, |
| CtrlL, CtrlR and CapsShift. |
| Each of these modifiers has an associated weight of power of two |
| according to the following table: |
| .LP |
| .RS |
| .TP 24 |
| .I modifier |
| .I weight |
| .TP 24 |
| Shift |
| 1 |
| .PD 0 |
| .TP 24 |
| AltGr |
| 2 |
| .TP 24 |
| Control |
| 4 |
| .TP 24 |
| Alt |
| 8 |
| .TP 24 |
| ShiftL |
| 16 |
| .TP 24 |
| ShiftR |
| 32 |
| .TP 24 |
| CtrlL |
| 64 |
| .TP 24 |
| CtrlR |
| 128 |
| .TP 24 |
| CapsShift |
| 256 |
| .PD |
| .RE |
| .LP |
| The effective action of a key is found out by adding up the weights of |
| all the modifiers in effect. By default, no modifiers are in effect, so |
| action number zero, i.e. the one in the first column in a key definition |
| line, is taken when the key is pressed or released. When e.g. Shift and |
| Alt modifiers are in effect, action number nine (from the 10th column) |
| is the effective one. |
| .LP |
| Changing the state of what modifiers are in effect can be achieved by |
| binding appropriate key actions to desired keys. For example, binding |
| the symbol Shift to a key sets the Shift modifier in effect when that |
| key is pressed and cancels the effect of that modifier when the key is |
| released. Binding AltGr_Lock to a key sets AltGr in effect when the key |
| is pressed and cancels the effect when the key is pressed again. |
| (By default Shift, AltGr, Control and Alt are bound to the keys that bear |
| a similar label; AltGr may denote the right Alt key.) |
| .LP |
| Note that you should be very careful when binding the modifier keys, |
| otherwise you can end up with an unusable keyboard mapping. If you for |
| example define a key to have Control in its first column and leave the |
| rest of the columns to be VoidSymbols, you're in trouble. This is |
| because pressing the key puts Control modifier in effect and the |
| following actions are looked up from the fifth column (see the table |
| above). So, when you release the key, the action from the fifth column |
| is taken. It has VoidSymbol in it, so nothing happens. This means that |
| the Control modifier is still in effect, although you have released the key. |
| Re-pressing and releasing the key has no effect. To avoid this, |
| you should always define all the columns to have the same modifier |
| symbol. There is a handy short-hand notation for this, see below. |
| .LP |
| .I keysyms |
| can be given in decimal, octal, hexadecimal, unicode or symbolic notation. |
| The numeric notations use the same format as with |
| .IR keynumber . |
| Unicode notation is "U+" followed by four hexadecimal digits. |
| The symbolic notation resembles that used by |
| .BR xmodmap (1). |
| Notable differences are the number symbols. The numeric |
| symbols '0', ..., '9' of |
| .BR xmodmap (1) |
| are replaced with the corresponding words 'zero', 'one', ... 'nine' to |
| avoid confusion with the numeric notation. |
| .LP |
| It should be noted that using numeric notation for the |
| .I keysyms |
| is highly unportable as the key action numbers may vary from one kernel |
| version to another and the use of numeric notations is thus strongly |
| discouraged. They are intended to be used only when you know there is a |
| supported keyboard action in your kernel for which your current version |
| of |
| .BR loadkeys (1) |
| has no symbolic name. |
| .LP |
| There is a number of short-hand notations to add readability and reduce |
| typing work and the probability of typing-errors. |
| .LP |
| First of all, you can give a map specification line, of the form |
| .LP |
| .RS |
| .EX |
| keymaps 0-2,4-5,8,12 |
| .EE |
| .RE |
| .LP |
| to indicate that the lines of the keymap will not specify all 256 columns, |
| but only the indicated ones. (In the example: only the plain, Shift, |
| AltGr, Control, Control+Shift, Alt and Control+Alt maps, that is, 7 columns |
| instead of 256.) |
| When no such line is given, the keymaps 0-M will be defined, where |
| M+1 is the maximum number of entries found in any definition line. |
| .LP |
| Next, you can leave off any trailing VoidSymbol entries from a key |
| definition line. VoidSymbol denotes a keyboard action which produces no |
| output and has no other effects either. For example, to define key |
| number 30 to output 'a' unshifted, 'A' when pressed with Shift and do |
| nothing when pressed with AltGr or other modifiers, you can write |
| .LP |
| .RS |
| .nf |
| keycode 30 = a A |
| .fi |
| .RE |
| .LP |
| instead of the more verbose |
| .LP |
| .RS |
| .nf |
| keycode 30 = a A VoidSymbol VoidSymbol \\ |
| VoidSymbol VoidSymbol VoidSymbol ... |
| .fi |
| .RE |
| .LP |
| For added convenience, you can usually get off with still more terse |
| definitions. If you enter a key definition line with only and exactly |
| one action code after the equals sign, it has a special meaning. If the |
| code (numeric or symbolic) is not an ASCII letter, it means the code |
| is implicitly replicated through all columns being defined. |
| If, on the other hand, the action code is an ASCII character in the |
| range 'a', ..., 'z' or 'A', ..., 'Z' in the ASCII collating sequence, |
| the following definitions are made for the different modifier combinations, |
| provided these are actually being defined. |
| (The table lists the two possible cases: |
| either the single action code is a lower case letter, |
| denoted by 'x' or an upper case letter, denoted by 'Y'.) |
| .LP |
| .RS 4 |
| .TP 24 |
| .I modifier |
| .I symbol |
| .TP 24 |
| none |
| x Y |
| .PD 0 |
| .TP 24 |
| Shift |
| X y |
| .TP 24 |
| AltGr |
| x Y |
| .TP 24 |
| Shift+AltGr |
| X y |
| .TP 24 |
| Control |
| Control_x Control_y |
| .TP 24 |
| Shift+Control |
| Control_x Control_y |
| .TP 24 |
| AltGr+Control |
| Control_x Control_y |
| .TP 24 |
| Shift+AltGr+Control |
| Control_x Control_y |
| .TP 24 |
| Alt |
| Meta_x Meta_Y |
| .TP 24 |
| Shift+Alt |
| Meta_X Meta_y |
| .TP 24 |
| AltGr+Alt |
| Meta_x Meta_Y |
| .TP 24 |
| Shift+AltGr+Alt |
| Meta_X Meta_y |
| .TP 24 |
| Control+Alt |
| Meta_Control_x Meta_Control_y |
| .TP 24 |
| Shift+Control+Alt |
| Meta_Control_x Meta_Control_y |
| .TP 24 |
| AltGr+Control+Alt |
| Meta_Control_x Meta_Control_y |
| .TP 24 |
| Shift+AltGr+Control+Alt |
| Meta_Control_x Meta_Control_y |
| .PD |
| .RE |
| .LP |
| .SH "SINGLE MODIFIER DEFINITIONS" |
| All the previous forms of key definition lines always define all the M+1 |
| possible modifier combinations being defined, whether the line actually |
| contains that many action codes or not. |
| There is, however, a variation of the definition |
| syntax for defining only single actions to a particular modifier |
| combination of a key. This is especially useful, if you load a keymap |
| which doesn't match your needs in only some modifier combinations, like |
| AltGr+function keys. You can then make a small local file redefining |
| only those modifier combinations and loading it after the main file. |
| The syntax of this form is: |
| .LP |
| .BR "" { " plain " "| <modifier sequence> } " keycode |
| .I keynumber |
| .B = |
| .I keysym |
| .LP |
| , e.g., |
| .RS |
| .EX |
| .nf |
| plain keycode 14 = BackSpace |
| control alt keycode 83 = Boot |
| alt keycode 105 = Decr_Console |
| alt keycode 106 = Incr_Console |
| .fi |
| .EE |
| .RE |
| Using "plain" will define only the base entry of a |
| key (i.e. the one with no modifiers in effect) without affecting the |
| bindings of other modifier combinations of that key. |
| .SH "STRING DEFINITIONS" |
| In addition to comments and key definition lines, a keymap can |
| contain string definitions. These are used to define what each function |
| key action code sends. The syntax of string definitions is: |
| .LP |
| .RS |
| .B string |
| .I keysym |
| .B = |
| .BI |
| "text" |
| .RE |
| .LP |
| .I text |
| can contain literal characters, octal character codes in the format of |
| backslash followed by up to three octal digits, and the three escape |
| sequences \fB\\n\fP, \fB\\\\\fP, and \fB\\"\fP, |
| for newline, backslash and quote, respectively. |
| .SH "COMPOSE DEFINITIONS" |
| Then there may also be compose definitions. They have syntax |
| .LP |
| .RS |
| .BI "compose '" char "' '" char "' to '" char "'" |
| .RE |
| and describe how two bytes are combined to form a third one |
| (when a dead accent or compose key is used). |
| This is used to get accented letters and the like on a standard |
| keyboard. |
| .SH ABBREVIATIONS |
| Various abbreviations can be used with kbd-0.96 and later. |
| .TP |
| .B "strings as usual" |
| Defines the usual values of the strings (but not the keys |
| they are bound to). |
| .TP |
| \fBcompose as usual for "iso-8859-1"\fP |
| Defines the usual compose combinations. |
| .LP |
| To find out what |
| .I keysyms |
| there are available for use in keymaps, use the command |
| .LP |
| .RS |
| .nf |
| .B dumpkeys --long-info |
| .fi |
| .RE |
| .LP |
| Unfortunately, there is currently no description of what each symbol |
| does. It has to be guessed from the name or figured out from the kernel |
| sources. |
| .LP |
| .SH EXAMPLES |
| (Be careful to use a keymaps line, like the first line of `dumpkeys`, |
| or "keymaps 0-15" or so.) |
| .LP |
| The following entry exchanges the left Control key and the Caps Lock |
| key on the keyboard: |
| .LP |
| .RS |
| .nf |
| keycode 58 = Control |
| keycode 29 = Caps_Lock |
| .fi |
| .RE |
| .LP |
| Key number 58 is normally the Caps Lock key, and key number 29 is |
| normally the Control key. |
| .LP |
| The following entry sets the Shift and Caps Lock keys to behave more |
| nicely, like in older typewriters. That is, pressing Caps Lock key once |
| or more sets the keyboard in CapsLock state and pressing either of the |
| Shift keys releases it. |
| .LP |
| .RS |
| .nf |
| keycode 42 = Uncaps_Shift |
| keycode 54 = Uncaps_Shift |
| keycode 58 = Caps_On |
| .fi |
| .RE |
| .LP |
| The following entry sets the layout of the edit pad in the enhanced |
| keyboard to be more like that in the VT200 series terminals: |
| .LP |
| .RS |
| .nf |
| keycode 102 = Insert |
| keycode 104 = Remove |
| keycode 107 = Prior |
| shift keycode 107 = Scroll_Backward |
| keycode 110 = Find |
| keycode 111 = Select |
| control alt keycode 111 = Boot |
| control altgr keycode 111 = Boot |
| .fi |
| .RE |
| .LP |
| Here's an example to bind the string "du\\ndf\\n" to the key AltGr-D. We use |
| the "spare" action code F100 not normally bound to any key. |
| .LP |
| .RS |
| .nf |
| altgr keycode 32 = F100 |
| string F100 = "du\\ndf\\n" |
| .LP |
| .SH "SEE ALSO" |
| .BR loadkeys (1), |
| .BR dumpkeys (1), |
| .BR showkey (1), |
| .BR xmodmap (1) |