In the Bad Old Days, the X Window System did everything differently from any other program; it was basically its own operating system, sitting on top of Linux (or whatever OS it ran on). As of Debian 6.0 (“Squeeze”), X has become a more normal application that uses the kernel's I/O facilities, instead of talking to the hardware directly. (There's a good, readable explanation of this improved integration here).
As a result, we no longer have to deal with the keyboard layout completely separately in X and in consoles (i.e., the so-called Virtual Terminals). The layout of the keyboard is handled for both systems by the keyboard-configuration package, whose configuration file is /etc/default/keyboard . Information describing the keyboard, which used to be in the InputDevice section of /etc/X11/xorg.conf, now goes in /etc/default/keyboard, and also describes the keyboard for the consoles.
It's still possible to have completely different arrangements for the consoles and X, if you like. This means that it's still necessary to do some of the configuration for consoles separately. That part is handled by the console-setup package. (In particular, it's still necessary to define Compose sequences separately for consoles and for X.) And console-setup does things that used to be done by packages like console-tools , which is now being superseded by kbd .
Furthermore, you may need to have things properly set up for various “application” programs, particularly under X. (For example, you not only need a UTF-8-aware terminal emulator, like urxvt or uxterm ; you need to have it behave properly when sent the Print code, if you want the “Print Scrn” key to work.)
Finally, the 2002 HOWTO file /usr/share/doc/HOWTO/en-txt/Keyboard-and-Console-HOWTO.gz (available on the Web at http://tldp.org/HOWTO/Keyboard-and-Console-HOWTO.html) is by now quite obsolete, although some of its information is still useful. In particular, the ISO-8859-1 setups it described as the latest thing a decade ago are completely superseded by UTF-8. (Also, the file /usr/share/doc/doc-linux-html/HOWTO/Font-HOWTO/index.html has almost equally stale info on fonts.) So we need a new guide to setting things up.
This page is a start.
localeshould show UTF-8 in most of the lines of output, especially LANG and LC_CTYPE. If not, edit (as root) /etc/default/locale , which should contain something ending in UTF-8, such as:
dpkg-reconfigure locales (see http://wiki.debian.org/Locale for details).
dpkg-reconfigure keyboard-configurationsets up the keyboard geometry for both the consoles and X.
It's often helpful to see how the package is currently configured. The command
debconf-show keyboard-configurationwill show you the answers to all the many questions asked by the dpkg-reconfigure command, and may reveal what's wrong. Then you'll know what to change when you reconfigure the package.
Although the keyboard-geometry description in /etc/default/keyboard sets XKB variables inherited from Xorg.conf, don't be misled into thinking that these determine just the X keyboard: they also set the console keyboard geometry.
However, the documentation for these things is all under X. So, see man X , especially the KEYBOARDS section near the end, and the various XKB environment variables. The directories /usr/share/X11/xkb/* have the keyboard-layout definitions. A clear introduction to these directories is here.
Because these definitions are complex and difficult for a beginner to understand, it's probably simpler just to draw a picture of the keyboard:
There is a program called xkbprint that will produce a PostScript drawing of a keyboard. Its man page is very cryptic; it refers to a “compiled keymap (.xkm) file”; but there are no .xkm files in the filesystem. However, it mentions xkbcomp in the “SEE ALSO” items at the end.
In turn, the man page for xkbcomp says it can convert an .xkb file into an .xkm file, but without saying where you can find the .xkb description of a keyboard; again, there are no files of this kind among the distributed X files.
However, if you Google long enough for this suffix, you eventually find that the program setxkbmap can produce this format as output. And setxkbmap has all sorts of options that refer to keyboard models that actually exist — see, for example, any of the identical files:
/usr/share/X11/xkb/rules/base.lstSo the process of generating a keyboard image for the Logitech keyboard called “logiik” in these list-files goes like this:
setxkbmap -model logiik -print > logiik.map xkbcomp -xkm logiik.map xkbprint -label symbols logiik.xkm logiik.psUse gv to display the PostScript file logiik.ps ; you'll need to change the orientation from “Landscape” to “Seascape”, and increase the scale to about 4 to read all the small annotations. Notice that the keycode of each key is printed in very tiny numbers below each key; if you want to read these numbers easily, replace “symbols” with “code” in the xkbprint command line.
Unspecified values and components always default to your current configuration. So, if you want to see what X thinks your current keyboard looks like, just omit the “model” specification to setxkbmap and use
setxkbmap -print > current.mapto get your current map; then you can use current instead of logiik as the base name of the resulting files. If you want to see what a French keyboard looks like, use -layout fr instead of -model logiik in the example; that produces a picture of your keyboard with an azerty layout.
The reasons for this complexity are historical. For one thing, X has been around for a long time, during which hardware features have evolved considerably. Keyboards have become more complicated, adding power-control and special internet and “media” keys. And, as keyboard styles have proliferated, configuration schemes that were adequate for a small selection of features have become unwieldy. So new configuration methods have been added, while older ones had to be kept for backward compatibility.
As a result, we now have three or four different ways to configure the X keyboard, as explained by Ivan Pascal. (Again, see here for a discussion of the two main approaches.) All of them are complicated enough that you are unlikely to get everything exactly right on the first try. On the other hand, you don't really have to: once the alphabetic keys are in the right places, so you can type commands and edit configuration files, the more obscure details — usually involving those special keys, like Print Screen and Page Up, between the alphabetic keys and the numeric keypad on “pc104” keyboards — can be handled as final adjustments (see the discussion of xmodmap, below.)
So you can regard keyboard configuration as a matter of successive approximations, and tweak the fine details until you're happy with the result.
See http://madduck.net/docs/extending-xkb/ for more information on selecting the keyboard model, as well as examples of how to make XKB work. All the gory details are given at the X.Org website, which also has the XKB Configuration Guide, (which you should already have in several formats in the /usr/share/doc/xorg-docs/input directory, if you have installed the xorg-docs package).
dpkg-reconfigure keyboard-configurationto set the keyboard geometry, most of what needs to be done is accomplished by running:
setupcon -vas ROOT from a CONSOLE — NOT over the wire, or in an X terminal session !!
The setupcon script reads configuration data from /etc/default/keyboard , converts the keyboard configuration specified by the XKB parameters in that file to console-type data with ckbcomp , saves the result in the compressed keymap file /etc/console-setup/cached.kmap.gz , and loads the console from /etc/console-setup/cached.kmap.gz by invoking loadkeys .
If you need (or want) special features, such as unusual key translations
not included in the standard alternatives, minor changes to the console
keymap can be put in /etc/console-setup/remap.inc ,
which will be appended to the cached.kmap file.
4. See man install-keymap for final steps. This installs the console keymap used at boot-time,
/etc/console/boottime.kmap.gz .This boot-time keymap is used only during the early stages of the boot process. Normally, you'll never deal with it; so it doesn't need a lot of compose sequences, or other fancy stuff. However, it's essential that it be reliable, as it's all you have if booting fails in early stages. Therefore, a backup version of this is kept in the “default” keymap (either /etc/console-tools/default.kmap.gz or /etc/kbd/default.kmap.gz — depending on which of these two conflicting packages you have installed.)
Notice that all console keymap files have the .kmap extension, and are all normally used in gzipped format (*.gz). For the format of these files, see:
Terminology: "keynumber" means the key's I.D. number; use showkey in a console to find it.
"keysym" is the symbolic name of the associated action; "dumpkeys -l" shows the full list.
A large library of *.kmap.gz files for most standard keyboards is in
5. Note that the format of the console is set during the boot sequence.
In particular, if the framebuffer takes over, you may need to add a parameter like "video=640x480" to the kernel command line, in the configuration file(s) for your bootloader (e.g., lilo or grub).
Furthermore, there is a sed script called "remap" that lives in either /etc/console-setup or /etc/kbd (depending on which package you use), and is called during the init sequence, when it modifies the output of dumpkeys to the form actually in use once the system is up. This is typically used to swap pairs of keys like <Ctrl>/<Shift>, or <BS>/<DEL>.
(see man xev ).
To see the current X keyboard mapping, use
So, to see what lines to put in your .Xmodmap file, you get the keycodes from xev, and the desired character or action from
which lists all the regular keysyms, prefixed by XK_ . This file is in package x11proto-core-dev, which is still in "jessie" (Debian 8).
Console files: -------------- /etc/default/keyboard refers to the default keyboard *layout*, not the full key-mapping. See: /usr/share/doc/console-setup/README.gz /usr/share/doc/keyboard-configuration/README.Debian tells more about this. (See man setupcon ) (These both come from the keyboard-configuration package.) X-Window files: --------------- /usr/include/X11/keysymdef.h All regular keysyms, prefixed by XK_ /usr/include/X11/XF86keysym.h All vendor-specific keysyms, prefixed by XF86K_ /usr/share/X11/XKeysymDB All special X functions, mapped or not /usr/share/X11/locale/en_US.UTF-8/Compose Compose-key database LOCAL FILES: ============ default.kmap gunzipped from /etc/console-tools/default.kmap.gz defkeymap.kmap gunzipped from /usr/share/keymaps/i386/qwerty/defkeymap.kmap.gz
in a console; it's in the console-tools package. [It's missing from that package's modern replacement, kbd.]
keycode 107 = BackSpace Print Print Print
in your .Xmodmap file.
This makes the key print what's on the screen if
Note that these key-presses generate the “Print” keysym, which is sent to
the terminal emulator (urxvt) in X. However, there's still a problem if
there are Unicode characters that need to be mapped before being sent to
Copyright © 2011 – 2012, 2015 Andrew T. Young
alphabetic index page
GF home page
website overview page
Back to the . . .
main LaTeX page
Note that these key-presses generate the “Print” keysym, which is sent to the terminal emulator (urxvt) in X. However, there's still a problem if there are Unicode characters that need to be mapped before being sent to the printer.
Copyright © 2011 – 2012, 2015 Andrew T. Young
alphabetic index page
GF home page
or the website overview page