Bug#241923: [xmodmap] manpage sucks
The issue at the heart of this bug report is that X essentially
supports two mechanisms for dealing with modifier keys on the keyboard.
The first of these mechanisms, as handled by the xmodmap 'add',
'remove', and 'clear' commands is that KeyPress and KeyRelease events
include a 'state' parameter which indicates which modifier keys are
currently active on the keyboard. In a standard configuration the
shift, lock, control, and mod1 states will be linked to Shift, Caps
Lock, Ctrl, and Alt/Meta respectively, and the other modX will be used
for other shift states. 'xmodmap -pm' shows this quite clearly.
The second mechanism, the one described in the paragraph documenting
'keycode NUMBER', relates to which keysym is given to the KeyPress
event, which is the thing xmodmap is usually used to configure. Which
keysym is given is only changed by the Shift, Mode_switch, and
So, supposed I press the 'a' key with or without the Shift and Meta
modifier keys, the processor of the KeyPress event sees the following:
None: 'a', state=0x0
Shift: 'A', state=0x1
Meta: 'a', state=0x8
Shift+Meta: 'A', state=0x9
In general, unless you actually care about whether a particular
keypress had the shift key down or not you can treat this as two
entirely independant mechanisms -- one of which (Shift, Mode_switch,
ISO_Level3_Shift) changes the keysym, the other of which (Meta, Super,
Hyper etc) changes the modifiers.
Thus the second section you quoted about having a combined
Meta/Multi_key is exploiting the difference between these two
mechanisms. It is also probably a bad idea to do this nowadays, since a
lot more things handle Multi_key than used to!
I'm not sure the xmodmap manpage is the right place to put this
discussion, but at the moment it is likely to be confusing to anyone who
doesn't understand the underlying model of how keyboard input works.