>> so, what is the XKeysymToKeycode stuff[?]
> Probably - I'll check what it does here.  Unfortunately my knowedge
> of lowlevel X11 stuff is rather limited so someone else should
> comment this :/

Keyboard handling is one of the funkiest parts of X.

X assumes that, at some point, the X server gets key-up and key-down
events for the keys on the keyboard.  (If this isn't so, some module
somewhere is required to do whatever is necessary to fake it.)  At this
level, keys are identified with small integers.

These get mapped to abstract symbols, which in theory - and usually in
practice as well - match what's marked on the physical keys.  These
abstract symbols have been given symbolic names for API use, and in
theory there is supposed to be an appropriate name for every keyboard
key label in existence - and they actually did a not-too-bad job of
approximating that, given the magnitude of the task.

Now, the thing is, this mapping is carried out by the *client*.  Even
though the mapping table is maintained by the server, the server does
not actually use it for anything; it's just a central place to store it
where all clients can get at it.  Clients can tell the server to change
it, and when this happens, _all_ clients are told about the change, so
they can update their own copies.  Why this design was chosen I do not
know, though I have some plausible speculations.

This means that the small-integer names are exposed to the clients.
(Some kind of names for keys have to be exposed to the clients for them
to be able to change the keybaord mapping.  The funky part is that
these names are also used for routine keystrokes, not just mapping
changes.)

A keycode is one of the small integers, and is always in the range 8
through 255 (if the keyboard generates codes outside this range, some
code somewhere on the server side must map as necessary to compensate);
X cannot handle a keyboard with more than 248 keys, except by
conflating some of them.  A keysym is one of the symbolic names,
represented as a 32-bit integer.  The correspondence between names and
values is part of the protocol definition - eg, the Cyrillic letter zhe
has the C API name XK_Cyrillic_zhe and value 0x6d6.

Keyboard events (eg KeyPress) carry the keycode of the relevant key but
no keysyms.  Mapping the keycode and modifier bits to a keysym, when
it's done at all (which it usually is), is done by the client.  Mapping
the keysym to an input string (usually of length 1) is also up to the
client - and that mapping, while it is probably done for the majority
of keystrokes, is left undone far more commonly than the
keycode->keysym mapping.  (When might it not be done?  For example, if
you use a virtual-root window manager that takes, say,
control-alt-leftarrow as a command to switch roots, it probably will
not map that keystroke to a string at all, since it does not represent
input characters in any sense.)

Now, I can explain what XKeysymToKeycode does: it searches the
keycode-to-keysym mapping table looking for a keycode that maps to the
keysym you pass in.  (The doc I have for it does not specify what
happens if multiple keycodes map to that keysym; I suspect it just
picks one - probably the highest or lowest or some such, though since
it's not specified depending on it is a Bad Thing.)

Whether this actually helps you, of course, is a completely separate
question.  I hope it helps at least to the extent of alleviating some
confusion and/or incomprehension.  I'll be happy to go into more detail
if desired.

/~\ The ASCII				der Mouse
\ / Ribbon Campaign
 X  Against HTML	       mouse@rodents.montreal.qc.ca
/ \ Email!	     7D C8 61 52 5D E7 2D 39  4E F1 31 3E E8 B3 27 4B