Keystroke flow in X.org

Now that I've been finding my way around XKB for a while, I thought I'd draw up a diagram of how keystrokes flow through X.org.

In the initial setup, before we get to the diagram below, the X server compiles the appropriate files into an XKB map, and provides this to the client (application) on request.

What I discuss below isn't so much the real keystroke flow, as which files need to be edited if you want to affect what character is produced by the client. Of course, the client can completely ignore the characters recommended by the server.

The keystrokes are received from the X.org server by the client (ie. application) program as as numeric key codes.

The key codes are next passed through the XKB translation table, which is generated by xkbcomp. I'll take a little time to talk about the relevant xkb files. Please understand though, that changes to these files do not take effect until xkbcomp has been run (this can be done with setxkbmap too).

The files in xkb/keycodes contain a mapping between the numeric key codes received from the driver, and named key codes.

The files in xkb/symbols contain a mapping from named key codes to named key symbols. The mapping used here depends on what keyboard layout has been set (ie. US or Russian or Greek...); the files in the xkb/rules directory also has an effect on which files are selected here. But once the appropriate files from the symbols directory have been selected, it is the contents of these files that determine the key codes -> key symbols mapping.

The keysymdef.h file has a translation table which converts the named key symbols to numeric key symbols. When everything is compiled, what XKB has in its translation table is numeric key codes and numeric key symbols; the named versions are just for human convenience.

The final step is the files in the locale/<localename> directory. These turn a group of key symbols into a single character. There must be something somewhere that also maps single key symbols to characters, but I don't know where that is.