README

   1 Overview {#mainpage}
   2 ========
   3
   4 xkbcommon 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_state_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 supported API is available
  29 in the <xkbcommon/xkbcommon-*.h> files. Additional support is provided for
  30 X11 (XCB) clients, in the xkbcommon-x11 library, <xkbcommon/xkbcommon-x11.h>.
  31
  32 The xkbcommon API and ABI are stable. We will attempt to not break ABI during
  33 a minor release series, so applications written against 0.1.0 should be
  34 completely compatible with 0.5.3, but not necessarily with 1.0.0.  However, new
  35 symbols may be introduced in any release.  Thus, anyone packaging xkbcommon
  36 should make sure any package depending on it depends on a release greater than
  37 or equal to the version it was built against (or earlier, if it doesn't use
  38 any newly-introduced symbols), but less than the next major release.
  39
  40
  41 Relation to X11
  42 ===============
  43
  44 Relative to the XKB 1.1 specification implemented in current X servers,
  45 xkbcommon has removed support for some parts of the specification which
  46 introduced unnecessary complications.  Many of these removals were in fact
  47 not implemented, or half-implemented at best, as well as being totally
  48 unused in the standard dataset.
  49
  50 Notable removals:
  51     - geometry support
  52       + there were very few geometry definitions available, and while
  53         xkbcommon was responsible for parsing this insanely complex format,
  54         it never actually did anything with it
  55       + hopefully someone will develop a companion library which supports
  56         keyboard geometries in a more useful format
  57     - KcCGST (keycodes/compat/geometry/symbols/types) API
  58       + use RMLVO instead; KcCGST is now an implementation detail
  59       + including pre-defined keymap files
  60     - XKM support
  61       + may come in an optional X11 support/compatibility library
  62     - around half of the interpret actions
  63       + pointer device, message and redirect actions in particular
  64     - non-virtual modifiers
  65       + core and virtual modifiers have been collapsed into the same
  66         namespace, with a 'significant' flag that largely parallels the
  67         core/virtual split
  68     - radio groups
  69       + completely unused in current keymaps, never fully implemented
  70     - overlays
  71       + almost completely unused in current keymaps
  72     - key behaviors
  73       + used to implement radio groups and overlays, and to deal with things
  74         like keys that physically lock; unused in current keymaps
  75     - indicator behaviours such as LED-controls-key
  76       + the only supported LED behaviour is key-controls-LED; again this
  77         was never really used in current keymaps
  78
  79 Notable additions:
  80     - 32-bit keycodes
  81     - extended number of modifiers
  82     - extended number of groups
  83     - multiple keysyms per level
  84       + this requires incompatible dataset changes, such that X11 would
  85         not be able to parse these
  86
  87
  88 Development
  89 ===========
  90
  91 An extremely rudimentary homepage can be found at:
  92     http://xkbcommon.org
  93
  94 xkbcommon is maintained in git at github.com:
  95     https://github.com/xkbcommon/libxkbcommon
  96
  97 Patches are always welcome, and may be sent to either xorg-devel@lists.x.org,
  98 or wayland-devel@lists.freedesktop.org.
  99
 100 Bugs are tracked in Bugzilla at:
 101     https://bugs.freedesktop.org/describecomponents.cgi?product=libxkbcommon
 102 Or in github at:
 103     https://github.com/xkbcommon/libxkbcommon/issues
 104
 105 The maintainers are Daniel Stone and Ran Benita, who can be reached at:
 106     <daniel@fooishbar.org>
 107     <ran234@gmail.com>
 108
 109
 110 Credits
 111 =======
 112
 113 Many thanks are due to Dan Nicholson for his heroic work in getting xkbcommon
 114 off the ground initially.