README

   1 xkbcommon
   2 =========
   3
   4 libxkbcommon is a keymap compiler and support library which processes a
   5 reduced subset of keymaps as defined by the XKB specification.  Primarily,
   6 a keymap is created from a set of Rules/Model/Layout/Variant/Options names,
   7 processed through an XKB ruleset, and compiled into a struct xkb_keymap,
   8 which is the base type for all xkbcommon operations.
   9
  10 From an xkb_keymap, an xkb_state object is created which holds the current
  11 state of all modifiers, groups, LEDs, etc, relating to that keymap.  All
  12 key events must be fed into the xkb_state object using xkb_state_update_key.
  13 Once this is done, the xkb_state object will be properly updated, and the
  14 keysyms to use can be obtained with xkb_key_get_syms.
  15
  16 libxkbcommon does not distribute a dataset itself, other than for testing
  17 purposes.  The most common dataset is xkeyboard-config, as used by all
  18 current distributions for their X11 XKB data.  More information on
  19 xkeyboard-config is available here:
  20     http://www.freedesktop.org/wiki/Software/XKeyboardConfig
  21
  22
  23 API
  24 ===
  25
  26 While xkbcommon's API is somewhat derived from the classic XKB API as found
  27 in <X11/extensions/XKB.h> and friends, it has been substantially reworked to
  28 expose fewer internal details to clients.  The only supported API is available
  29 in <xkbcommon/xkbcommon.h>.  Any definition not in this header (including
  30 accessing internal structures through the old macros previously available)
  31 should be regarded as an implementation detail and is liable to change at any
  32 time.
  33
  34 During its early development, xkbcommon does not promise API or ABI stability.
  35 Regardless, we will attempt to not break ABI during a minor release series,
  36 so applications written against 0.1.0 should be completely compatible with
  37 0.1.3, but not necessarily with 0.2.0.  However, new symbols may be introduced
  38 in any release.  Thus, anyone packaging xkbcommon should make sure any package
  39 depending on it depends on a release greater than or equal to the version it
  40 was built against (or earlier, if it doesn't use any newly-introduced
  41 symbols), but less than the next major release.
  42
  43 xkbcommon 1.x will offer full API and ABI stability for its lifetime, with a
  44 soname of libxkbcommon.so.1.  Any ABI breaks will wait until xkbcommon 2.0,
  45 which will be libxkbcommon.so.2.
  46
  47 The xkbcomp command-line tool has also been removed, although this will
  48 likely reappear in a later release.
  49
  50
  51 Relation to X11
  52 ===============
  53
  54 Relative to the XKB 1.1 specification implemented in current X servers,
  55 xkbcommon has removed support for some parts of the specification which
  56 introduced unnecessary complications.  Many of these removals were in fact
  57 not implemented, or half-implemented at best, as well as being totally
  58 unused in the standard dataset.
  59
  60 Notable removals:
  61     - geometry support
  62       + there were very few geometry definitions available, and while
  63         xkbcommon was responsible for parsing this insanely complex format,
  64         it never actually did anything with it
  65       + hopefully someone will develop a companion library which supports
  66         keyboard geometries in a more useful format
  67     - KcCGST (keycodes/compat/geometry/symbols/types) API
  68       + use RMLVO instead; KcCGST is now an implementation detail
  69       + including pre-defined keymap files
  70     - XKM support
  71       + may come in an optional X11 support/compatibility library
  72     - around half of the interpret actions
  73       + pointer device, message and redirect actions in particular
  74     - non-virtual modifiers
  75       + core and virtual modifiers have been collapsed into the same
  76         namespace, with a 'significant' flag that largely parallels the
  77         core/virtual split
  78     - radio groups
  79       + completely unused in current keymaps, never fully implemented
  80     - overlays
  81       + almost completely unused in current keymaps
  82     - key behaviors
  83       + used to implement radio groups and overlays, and to deal with things
  84         like keys that physically lock; unused in current keymaps
  85     - indicator behaviours such as LED-controls-key
  86       + the only supported LED behaviour is key-controls-LED; again this
  87         was never really used in current keymaps
  88
  89 Notable additions:
  90     - 32-bit keycodes
  91     - extended number of modifiers
  92     - extended number of groups
  93     - multiple keysyms per level
  94       + this requires incompatible dataset changes, such that X11 would
  95         not be able to parse these
  96
  97
  98 Development
  99 ===========
 100
 101 xkbcommon is maintained in git at freedesktop.org:
 102     git://anongit.freedesktop.org/git/xorg/lib/libxkbcommon
 103
 104 Patches are always welcome, and may be sent to either xorg-devel@lists.x.org,
 105 or wayland-devel@lists.freedesktop.org.  Bugs are tracked in Bugzilla at:
 106     http://bugs.freedesktop.org
 107
 108 The primary author and maintainer is Daniel Stone, who can be reached at:
 109     <daniel@fooishbar.org>
 110
 111
 112 Credits
 113 =======
 114
 115 Many thanks are due to Dan Nicholson for his heroic work in getting xkbcommon
 116 off the ground initially, as well as to Ran Benita for subsequent development.