A keycode represents a physical (or logical) key. In CLX, keycodes are values of type (integer 8 255). A keycode value carries no intrinsic information, although server implementors may attempt to encode geometry (for example, matrix) information in some fashion so it can be interpreted in a server- dependent fashion. The mapping between keys and keycodes cannot be changed.
A keysym is an encoding of a symbol on the cap of a key. In CLX, keysyms are values of type card32. The set of defined keysyms include the ISO Latin character sets (1-4), Katakana, Arabic, Cyrillic, Greek, Technical, Special, Publishing, APL, Hebrew, and miscellaneous keys found on keyboards (RETURN, HELP, TAB, and so on). The encoding of keysyms is defined by the X Protocol.
A list of keysyms is associated with each keycode. The length of the list can vary with each keycode. The list is intended to convey the set of symbols on the corresponding key. By convention, if the list contains a single keysym and if that keysym is alphabetic and case distinction is relevant, then it should be treated as equivalent to a two-element list of the lowercase and uppercase keysyms. For example, if the list contains the single keysym for uppercase A, the client should treat it as if it were a pair with lowercase as the first keysym and uppercase A as the second keysym.
For any keycode, the first keysym in the list should be chosen as the interpretation of a key press when no modifier keys are down. The second keysym in the list normally should be chosen when the :shift modifier is on, or when the :lock modifier is on and :lock is interpreted as :shift-lock. When the :lock modifier is on and is interpreted as :caps-lock, it is suggested that the :shift modifier first be applied to choose a keysym, but if that keysym is lowercase alphabetic, the corresponding uppercase keysym should be used instead.
Other interpretations of :caps-lock are possible; for example, it may be viewed as equivalent to :shift-lock, but only applying when the first keysym is lowercase alphabetic and the second keysym is the corresponding uppercase alphabetic. No interpretation of keysyms beyond the first two in a list is suggested here. No spatial geometry of the symbols on the key is defined by their order in the keysym list, although a geometry might be defined on a vendor-specific basis. The X server does not use the mapping between keycodes and keysyms. Rather, the X server stores the mapping merely for reading and writing by clients.