diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 114 |
1 files changed, 102 insertions, 12 deletions
@@ -1,23 +1,113 @@ -All questions regarding this software should be directed at the -Xorg mailing list: +xkbcommon +========= - http://lists.freedesktop.org/mailman/listinfo/xorg +libxkbcommon is a keymap compiler and support library which processes a +reduced subset of keymaps as defined by the XKB specification. Primarily, +a keymap is created from a set of Rules/Model/Layout/Variant/Options names, +processed through an XKB ruleset, and compiled into a struct xkb_desc, which +is the base type for all xkbcommon operations. -Please submit bug reports to the Xorg bugzilla: +From an xkb_desc, an xkb_state object is created which holds the current +state of all modifiers, groups, LEDs, etc, relating to that keymap. All +key events must be fed into the xkb_state object using xkb_state_update_key. +Once this is done, the xkb_state object will be properly updated, and the +keysyms to use can be obtained with xkb_key_get_syms. - https://bugs.freedesktop.org/enter_bug.cgi?product=xorg +libxkbcommon does not distribute a dataset itself, other than for testing +purposes. The most common dataset is xkeyboard-config, as used by all +current distributions for their X11 XKB data. More information on +xkeyboard-config is available here: + http://www.freedesktop.org/wiki/Software/XKeyboardConfig -The master development code repository can be found at: - git://anongit.freedesktop.org/git/xorg/lib/libxkbcommon +API +=== - http://cgit.freedesktop.org/xorg/lib/libxkbcommon +While xkbcommon's API is somewhat derived from the classic XKB API as found +in <X11/extensions/XKB.h> and friends, it has been substantially reworked to +expose fewer internal details to clients. The only supported API is available +in <xkbcommon/xkbcommon.h>. Any definition not in this header (including +accessing internal structures through the old macros previously available) +should be regarded as an implementation detail and is liable to change at any +time. -For patch submission instructions, see: +During its early development, xkbcommon does not promise API or ABI stability. +Regardless, we will attempt to not break ABI during a minor release series, +so applications written against 0.1.0 should be completely compatible with +0.1.3, but not necessarily with 0.2.0. However, new symbols may be introduced +in any release. Thus, anyone packaging xkbcommon should make sure any package +depending on it depends on a release greater than or equal to the version it +was built against (or earlier, if it doesn't use any newly-introduced +symbols), but less than the next major release. - http://www.x.org/wiki/Development/Documentation/SubmittingPatches +xkbcommon 1.x will offer full API and ABI stability for its lifetime, with a +soname of libxkbcommon.so.1. Any ABI breaks will wait until xkbcommon 2.0, +which will be libxkbcommon.so.2. -For more information on the git code manager, see: +The xkbcomp command-line tool has also been removed, although this will +likely reappear in a later release. - http://wiki.x.org/wiki/GitPage +Relation to X11 +=============== + +Relative to the XKB 1.1 specification implemented in current X servers, +xkbcommon has removed support for some parts of the specification which +introduced unnecessary complications. Many of these removals were in fact +not implemented, or half-implemented at best, as well as being totally +unused in the standard dataset. + +Notable removals: + - geometry support + + there were very few geometry definitions available, and while + xkbcommon was responsible for parsing this insanely complex format, + it never actually did anything with it + + hopefully someone will develop a companion library which supports + keyboard geometries in a more useful format + - KcCGST (keycodes/compat/geometry/symbols/types) API + + use RMLVO instead; KcCGST is now an implementation detail + + including pre-defined keymap files + - XKM support + + may come in an optional X11 support/compatibility library + - around half of the interpret actions + + pointer device, message and redirect actions in particular + - non-virtual modifiers + + core and virtual modifiers have been collapsed into the same + namespace, with a 'significant' flag that largely parallels the + core/virtual split + - radio groups + + completely unused in current keymaps, never fully implemented + - overlays + + almost completely unused in current keymaps + - indicator behaviours such as LED-controls-key + + the only supported LED behaviour is key-controls-LED; again this + was never really used in current keymaps + +Notable additions: + - 32-bit keycodes + - extended number of modifiers + - extended number of groups + - multiple keysyms per level + + this requires incompatible dataset changes, such that X11 would + not be able to parse these + + +Development +=========== + +xkbcommon is maintained in git at freedesktop.org: + git://anongit.freedesktop.org/git/xorg/lib/libxkbcommon + +Patches are always welcome, and may be sent to either xorg-devel@lists.x.org, +or wayland-devel@lists.freedesktop.org. Bugs are tracked in Bugzilla at: + http://bugs.freedesktop.org + +The primary author and maintainer is Daniel Stone, who can be reached at: + <daniel@fooishbar.org> + + +Credits +======= + +Many thanks are due to Dan Nicholson for his heroic work in getting xkbcommon +off the ground initially, as well as to Ran Benita for subsequent development. |