So, with everyone just pulling in the xkbcommon library, is there any chance that we get a decent documentation for it? I have spent considarable time trying to figure out how it works in the last few weeks creating a customized Dvorak layout with emphasis on programming (yea, I know there is stock one, I don't like it). Anyway, the XKB configuration - while being very powerfull - is also one with the worst documentation.. ever. Try to create a keyboard configuration with multiple levels and map shift level switches to normal alphanumerical keys and let them behave differently (be different shift/control keys) on various shift levels? You are in for a good ride there. Not to mention all the legacy convention in there. My head hurts.
the library itself has pretty good documentation, but the format is definitely very much lacking. we've been looking to create a new, less confusing, format, which was blocked on a sensible library interface - the old interface looked exactly like the format!
unfortunately time is very much lacking, but patches definitely welcome.