head 1.1; branch 1.1.1; access; symbols netbsd-11-0-RC4:1.1.1.2 netbsd-11-0-RC3:1.1.1.2 netbsd-11-0-RC2:1.1.1.2 netbsd-11-0-RC1:1.1.1.2 netbsd-11:1.1.1.2.0.4 netbsd-11-base:1.1.1.2 netbsd-10-1-RELEASE:1.1.1.2 netbsd-8-3-RELEASE:1.1.1.1 netbsd-9-4-RELEASE:1.1.1.1 netbsd-10-0-RELEASE:1.1.1.2 netbsd-10-0-RC6:1.1.1.2 netbsd-10-0-RC5:1.1.1.2 netbsd-10-0-RC4:1.1.1.2 netbsd-10-0-RC3:1.1.1.2 netbsd-10-0-RC2:1.1.1.2 netbsd-10-0-RC1:1.1.1.2 xkeyboard-config-2-38:1.1.1.2 netbsd-10:1.1.1.2.0.2 netbsd-10-base:1.1.1.2 xkeyboard-config-2-37:1.1.1.2 netbsd-9-3-RELEASE:1.1.1.1 xkeyboard-config-2-34:1.1.1.1 xkeyboard-config-2-33:1.1.1.1 netbsd-9-2-RELEASE:1.1.1.1 xkeyboard-config-2-32:1.1.1.1 xkeyboard-config-2-31:1.1.1.1 netbsd-9-1-RELEASE:1.1.1.1 netbsd-8-2-RELEASE:1.1.1.1 xkeyboard-config-2-29:1.1.1.1 netbsd-9-0-RELEASE:1.1.1.1 netbsd-9-0-RC2:1.1.1.1 netbsd-9-0-RC1:1.1.1.1 netbsd-9:1.1.1.1.0.26 netbsd-9-base:1.1.1.1 xkeyboard-config-2-27:1.1.1.1 netbsd-8-1-RELEASE:1.1.1.1 netbsd-8-1-RC1:1.1.1.1 xkeyboard-config-2-26:1.1.1.1 xkeyboard-config-2-25:1.1.1.1 netbsd-7-2-RELEASE:1.1.1.1 netbsd-8-0-RELEASE:1.1.1.1 netbsd-8-0-RC2:1.1.1.1 netbsd-8-0-RC1:1.1.1.1 netbsd-7-1-2-RELEASE:1.1.1.1 xkeyboard-config-2-23-1:1.1.1.1 netbsd-7-1-1-RELEASE:1.1.1.1 xkeyboard-config-2-21:1.1.1.1 netbsd-8:1.1.1.1.0.24 netbsd-8-base:1.1.1.1 netbsd-7-1:1.1.1.1.0.22 netbsd-7-1-RELEASE:1.1.1.1 netbsd-7-1-RC2:1.1.1.1 xkeyboard-config-2-20:1.1.1.1 netbsd-7-1-RC1:1.1.1.1 xkeyboard-config-2-19:1.1.1.1 netbsd-7-0-2-RELEASE:1.1.1.1 netbsd-7-0-1-RELEASE:1.1.1.1 netbsd-7-0:1.1.1.1.0.20 netbsd-7-0-RELEASE:1.1.1.1 netbsd-7-0-RC3:1.1.1.1 netbsd-7-0-RC2:1.1.1.1 xkeyboard-config-2-15:1.1.1.1 netbsd-7-0-RC1:1.1.1.1 netbsd-5-2-3-RELEASE:1.1.1.1 netbsd-5-1-5-RELEASE:1.1.1.1 netbsd-6-0-6-RELEASE:1.1.1.1 netbsd-6-1-5-RELEASE:1.1.1.1 netbsd-7:1.1.1.1.0.18 netbsd-7-base:1.1.1.1 xkeyboard-config-2-12:1.1.1.1 netbsd-6-1-4-RELEASE:1.1.1.1 netbsd-6-0-5-RELEASE:1.1.1.1 riastradh-xf86-video-intel-2-7-1-pre-2-21-15:1.1.1.1 xkeyboard-config-2-11:1.1.1.1 riastradh-drm2:1.1.1.1.0.16 riastradh-drm2-base:1.1.1.1 netbsd-6-1-3-RELEASE:1.1.1.1 netbsd-6-0-4-RELEASE:1.1.1.1 netbsd-5-2-2-RELEASE:1.1.1.1 netbsd-5-1-4-RELEASE:1.1.1.1 netbsd-6-1-2-RELEASE:1.1.1.1 netbsd-6-0-3-RELEASE:1.1.1.1 netbsd-5-2-1-RELEASE:1.1.1.1 netbsd-5-1-3-RELEASE:1.1.1.1 netbsd-6-1-1-RELEASE:1.1.1.1 xkeyboard-config-2-9:1.1.1.1 netbsd-6-1:1.1.1.1.0.14 netbsd-6-0-2-RELEASE:1.1.1.1 netbsd-6-1-RELEASE:1.1.1.1 netbsd-6-1-RC4:1.1.1.1 netbsd-6-1-RC3:1.1.1.1 netbsd-6-1-RC2:1.1.1.1 netbsd-6-1-RC1:1.1.1.1 netbsd-5-2:1.1.1.1.0.12 netbsd-6-0-1-RELEASE:1.1.1.1 netbsd-5-2-RELEASE:1.1.1.1 netbsd-5-2-RC1:1.1.1.1 netbsd-6-0:1.1.1.1.0.10 netbsd-6-0-RELEASE:1.1.1.1 netbsd-6-0-RC2:1.1.1.1 netbsd-6-0-RC1:1.1.1.1 netbsd-6:1.1.1.1.0.8 netbsd-6-base:1.1.1.1 netbsd-5-1-2-RELEASE:1.1.1.1 netbsd-5-1-1-RELEASE:1.1.1.1 xkeyboard-config-2-3:1.1.1.1 xkeyboard-config-2-1:1.1.1.1 xkeyboard-config-2-0:1.1.1.1 netbsd-5-1:1.1.1.1.0.6 netbsd-5-1-RELEASE:1.1.1.1 netbsd-5-1-RC4:1.1.1.1 netbsd-5-1-RC3:1.1.1.1 xkeyboard-config-1-9:1.1.1.1 netbsd-5-1-RC2:1.1.1.1 netbsd-5-1-RC1:1.1.1.1 netbsd-5-0-2-RELEASE:1.1.1.1 netbsd-5-0-1-RELEASE:1.1.1.1 xkeyboard-config-1-4:1.1.1.1 netbsd-5-0:1.1.1.1.0.4 netbsd-5-0-RELEASE:1.1.1.1 netbsd-5-0-RC4:1.1.1.1 netbsd-5-0-RC3:1.1.1.1 netbsd-5-0-RC2:1.1.1.1 netbsd-5-0-RC1:1.1.1.1 netbsd-5:1.1.1.1.0.2 netbsd-5-base:1.1.1.1 xkeyboard-config-1-3:1.1.1.1 xorg:1.1.1; locks; strict; comment @# @; 1.1 date 2008.08.30.09.12.23; author mrg; state Exp; branches 1.1.1.1; next ; 1.1.1.1 date 2008.08.30.09.12.23; author mrg; state Exp; branches; next 1.1.1.2; 1.1.1.2 date 2022.10.17.07.37.06; author mrg; state Exp; branches; next ; commitid WK5G7TzJGmFIJ2YD; desc @@ 1.1 log @Initial revision @ text @ The XKB Configuration Guide Kamil Toman, Ivan U. Pascal 25 November 2002 Abstract This document describes how to configure XFree86 XKB from a user's point a few. It converts basic configuration syntax and gives also a few examples. 1. Overview The XKB configuration is decomposed into a number of components. Selecting proper parts and combining them back you can achieve most of configurations you might need. Unless you have a completely atypical keyboard you really don't need to touch any of xkb configuration files. 2. Selecting XKB Configuration The easiest and the most natural way how to specify a keyboard mapping is to use rules component. As its name suggests it describes a number of general rules how to combine all bits and pieces into a valid and useful keyboard mapping. All you need to do is to select a suitable rules file and then to feed it with a few parameters that will adjust the keyboard behaviour to ful- fill your needs. The parameters are: o XkbRules - files of rules to be used for keyboard mapping composition o XkbModel - name of model of your keyboard type o XkbLayout - layout(s) you intend to use o XkbVariant - variant(s) of layout you intend to use o XkbOptions - extra xkb configuration options The proper rules file depends on your vendor. In reality, the commonest file of rules is xfree86. For each rules file there is a description file named .lst, for instance xfree86.lst which is located in xkb configu- ration subdirectory rules (for example /etc/X11/xkb/rules). 2.1 Basic Configuration Let's say you want to configure a PC style America keyboard with 104 keys as described in xfree86.lst. It can be done by simply writing several lines from below to you XFree86 configuration file (often found as /etc/X11/XF86Config-4 or /etc/X11/XF86Config): Section "InputDevice" Identifier "Keyboard1" Driver "Keyboard" Option "XkbModel" "pc104" Option "XkbLayout" "us" Option "XKbOptions" "" EndSection The values of parameters XkbModel and XkbLayout are really not surprising. The parameters XkbOptions has been explicitly set to empty set of parameters. The parameter XkbVariant has been left out. That means the default variant named basic is loaded. Of course, this can be also done at runtime using utility setxkbmap. Shell command loading the same keyboard mapping would look like: setxkbmap -rules xfree86 -model pc104 -layout us -option "" The configuration and the shell command would be very analogical for most other layouts (internationalized mappings). 2.2 Advanced Configuration Since XFree86 4.3.x you can use multi-layouts xkb configuration. What does it mean? Basically it allows to load up to four different keyboard layouts at a time. Each such layout would reside in its own group. The groups (unlike complete keyboard remapping) can be switched very fast from one to another by a combination of keys. Let's say you want to configure your new Logitech cordless desktop keyboard, you intend to use three different layouts at the same time - us, czech and german (in this order), and that you are used to Alt-Shift combination for switching among them. Then the configuration snippet could look like this: Section "InputDevice" Identifier "Keyboard1" Driver "Keyboard" Option "XkbModel" "logicordless" Option "XkbLayout" "us,cz,de" Option "XKbOptions" "grp:alt_shift_toggle" EndSection Of course, this can be also done at runtime using utility setxkbmap. Shell command loading the same keyboard mapping would look like: setxkbmap -rules xfree86 -model logicordless -layout "us,cz,de" \ -option "grp:alt_shift_toggle" 2.3 Even More Advanced Configuration Okay, let's say you are more demanding. You do like the example above but you want it to change a bit. Let's imagine you want the czech keyboard mapping to use another variant but basic. The configuration snippet then changes into: Section "InputDevice" Identifier "Keyboard1" Driver "Keyboard" Option "XkbModel" "logicordless" Option "XkbLayout" "us,cz,de" Option "XkbVariant" ",bksl," Option "XKbOptions" "grp:alt_shift_toggle" EndSection That's seems tricky but it is not. The logic for settings of variants is the same as for layouts, that means the first and the third variant settings are left out (set to basic), the second is set to bksl (a special variant with an enhanced definition of the backslash key). Analogically, the loading runtime will change to: setxkmap -rules xfree86 -model logicordless -layout "us,cz,de" \ -variant ",bksl," -option "grp:alt_shift_toggle" 2.4 Basic Global Options See rules/*.lst files. 3. Direct XKB Configuration Generally, you can directly prescribe what configuration of each of basic xkb components should be used to form the resulting keyboard mapping. This method is rather "brute force". You precisely need to know the structure and the meaning of all of used configuration components. This method also exposes all xkb configuration details directly into XFree86 configuration file which is a not very fortunate fact. In rare occasions it may be needed, though. So how does it work? 3.1 Basic Components There are five basic components used to form a keyboard mapping: o key codes - a translation of the scan codes produced by the keyboard into a suitable symbolic form o types - a specification of what various combinations of modifiers pro- duce o key symbols - a translation of symbolic key codes into actual symbols o geometry - a description of physical keyboard geometry o compatibility maps - a specification of what action should each key pro- duce in order to preserve compatibility with XKB-unware clients 3.2 Example Configuration Look at the following example: Section "InputDevice" Identifier "Keyboard0" Driver "Keyboard" Option "XkbKeycodes" "xfree86" Option "XkbTypes" "default" Option "XkbSymbols" "en_US(pc104)+de+swapcaps" Option "XkbGeometry" "pc(pc104)" Option "XkbCompat" "basic+pc+iso9995" EndSection This configuration sets the standard XFree86 default interpretation of key- board keycodes, sets the default modificator types. The symbol table is com- posed of extended US keyboard layout in its variant for pc keyboards with 104 keys plus all keys for german layout are redefined respectively. Also the logical meaning of Caps-lock and Control keys is swapped. The standard key- board geometry (physical look) is set to pc style keyboard with 104 keys. The compatibility map is set to allow basic shifting, to allow Alt keys to be interpreted and also to allow iso9995 group shifting. 4. Keymap XKB Configuration It is the formerly used way to configure xkb. The user included a special keymap file which specified the direct xkb configuration. This method has been obsoleted by previously described rules files which are far more flexi- ble and allow simpler and more intuitive syntax. It is preserved merely for compatibility reasons. Avoid using it if it is possible. Generated from XFree86: xc/programs/Xserver/hw/xfree86/doc/sgml/XKB-Config.sgml,v 1.4 dawes Exp $ @ 1.1.1.1 log @initial import of xkeyboard-config-1.3 @ text @@ 1.1.1.2 log @initial import of xkeyboard-config-2.37 @ text @a0 1 d10 1 a10 1 point of view. It covers the basic configuration syntax and gives a12 1 d15 10 a24 11 The XKB configuration system consists of a number of components. Selecting and combining the proper parts, you can achieve most of the configurations you might need. Unless you have a completely atypical keyboard, you really don't need to touch any of the xkb component files themselves. 2. Selecting an XKB configuration The easiest and most natural way to specify a keyboard mapping is to use the rules component. As its name suggests, it describes a number of general rules on how to combine the bits and pieces into a valid and useful keyboard d26 2 a27 2 feed it with a few parameters that will adjust the keyboard behaviour to fulfill your needs. d31 1 a31 1 o XkbRules - the file of rules to be used for keyboard mapping composition d33 1 a33 1 o XkbModel - the name of the model of your keyboard d35 1 a35 1 o XkbLayout - the layout(s) you intend to use d37 1 a37 1 o XkbVariant - the variant(s) of the layout(s) you intend to use d41 4 a44 4 The proper rules file depends on your vendor. In reality, the commonest file of rules is xfree86. For each rules file there is a description file named .lst, for instance xfree86.lst, which is located in the xkb configuration subdirectory 'rules' (for example /etc/X11/xkb/rules). d48 4 a51 3 Let's say you want to configure a PC-style American keyboard with 104 keys as described in xfree86.lst. It can be done by simply writing several lines to your XFree86 configuration file (often found as /etc/X11/XF86Config): d62 4 a65 4 The values of the parameters XkbModel and XkbLayout are really not surprising. The parameter XkbOptions has been explicitly set to empty, meaning no options. The parameter XkbVariant has been left out, meaning that the default variant (the first variant in the file, often named 'basic') will be loaded. d67 2 a68 2 Of course, this can also be done at runtime using the utility setxkbmap. The shell command loading the same keyboard mapping would look like: d72 1 a72 1 The configuration snippet and the shell command will be very similar for most d77 5 a81 5 Since XFree86 4.3.x, you can use multi-layouts xkb configuration. What does it mean? Basically it allows you to load up to four different keyboard layouts at a time. Each such layout will reside in its own group. The groups (unlike a complete keyboard remapping) can be switched very fast from one to another with some key combination. d84 3 a86 3 you intend to use three different layouts at the same time - US, Czech and German (in this order), and that you are used to the Alt+Shift combination for switching among them. d91 1 a91 1 Identifier "Keyboard2" d99 2 a100 2 Of course, this can also be done at runtime using the utility setxkbmap. The shell command loading the same keyboard mapping would look like: d103 1 a103 1 -option "grp:alt_shift_toggle" d108 2 a109 2 want to change it a bit. Let's imagine you want the Czech keyboard mapping to use another variant than basic. The configuration snippet then changes into: d112 1 a112 1 Identifier "Keyboard2" d121 4 a124 4 That seems tricky but it is not. The logic for setting variants is the same as for layouts, which means that the first and the third variant settings are left out (set to basic), and the second is set to bksl (a special variant with an enhanced definition of the backslash key). d126 1 a126 1 Analogically, the loading at runtime will change to: d133 1 a133 2 See the rules/*.lst files. d137 2 a138 2 Generally, you can directly prescribe what configuration for each of the basic xkb components should be used to form the resulting keyboard mapping. This d140 1 a140 1 the meaning of all of the used configuration components. d142 3 a144 3 This method also exposes all xkb configuration details directly into the XFree86 configuration file, which is a not very fortunate fact. In rare occasions it may be needed, though. So how does it work? d153 2 a154 1 o types - a specification of what various combinations of modifiers produce d158 1 a158 1 o geometry - a description of all physical keyboard dimensions d160 2 a161 2 o compatibility maps - a specification of what action each key should produce in order to preserve compatibility with XKB-unware clients d178 7 a184 7 This configuration sets the standard XFree86 interpretation of keyboard keycodes, and sets the default modificator types. The symbol table is composed of an extended US keyboard layout in its variant for PC keyboards with 104 keys, and all keys for a German layout are redefined. Also the logical meanings of the Caps-lock and Control keys are swapped. The standard keyboard geometry (physical look) is set to a PC-style keyboard with 104 keys. The compatibility map is set to allow basic shifting, to allow Alt keys to be a186 1 d189 1 a189 1 This is the formerly used way to configure xkb. The user included a special d191 5 a195 3 been obsoleted by the previously described rules files which are far more flexible and allow a simpler and more intuitive syntax. The obsolete method is preserved merely for compatibility reasons. Avoid using it if possible. @