README: move note about xkeyboard-config to its own section
[platform/upstream/libxkbcommon.git] / README.md
1 # libxkbcommon
2
3 xkbcommon is a keymap compiler and support library which processes a
4 reduced subset of keymaps as defined by the XKB specification.  Primarily,
5 a keymap is created from a set of Rules/Model/Layout/Variant/Options names,
6 processed through an XKB ruleset, and compiled into a struct xkb_keymap,
7 which is the base type for all xkbcommon operations.
8
9 From an xkb_keymap, an xkb_state object is created which holds the current
10 state of all modifiers, groups, LEDs, etc, relating to that keymap.  All
11 key events must be fed into the xkb_state object using xkb_state_update_key().
12 Once this is done, the xkb_state object will be properly updated, and the
13 keysyms to use can be obtained with xkb_state_key_get_syms().
14
15 ## Quick Guide
16
17 See [Quick Guide](doc/quick-guide.md).
18
19 ## API
20
21 While xkbcommon's API is somewhat derived from the classic XKB API as found
22 in X11/extensions/XKB.h and friends, it has been substantially reworked to
23 expose fewer internal details to clients.  The supported API is available
24 in the xkbcommon/xkbcommon-*.h files.  Additional support is provided for
25 X11 (XCB) clients, in the xkbcommon-x11 library, xkbcommon/xkbcommon-x11.h.
26
27 ## Dataset
28
29 libxkbcommon does not distribute a keymap dataset itself, other than for
30 testing purposes.  The most common dataset is xkeyboard-config, which is used
31 by all current distributions for their X11 XKB data.  More information on
32 xkeyboard-config is available here:
33     http://www.freedesktop.org/wiki/Software/XKeyboardConfig
34
35 ## Relation to X11
36
37 Relative to the XKB 1.1 specification implemented in current X servers,
38 xkbcommon has removed support for some parts of the specification which
39 introduced unnecessary complications.  Many of these removals were in fact
40 not implemented, or half-implemented at best, as well as being totally
41 unused in the standard dataset.
42
43 Notable removals:
44 - geometry support
45   + there were very few geometry definitions available, and while
46     xkbcommon was responsible for parsing this insanely complex format,
47     it never actually did anything with it
48   + hopefully someone will develop a companion library which supports
49     keyboard geometries in a more useful format
50 - KcCGST (keycodes/compat/geometry/symbols/types) API
51   + use RMLVO instead; KcCGST is now an implementation detail
52   + including pre-defined keymap files
53 - XKM support
54   + may come in an optional X11 support/compatibility library
55 - around half of the interpret actions
56   + pointer device, message and redirect actions in particular
57 - non-virtual modifiers
58   + core and virtual modifiers have been collapsed into the same
59     namespace, with a 'significant' flag that largely parallels the
60     core/virtual split
61 - radio groups
62   + completely unused in current keymaps, never fully implemented
63 - overlays
64   + almost completely unused in current keymaps
65 - key behaviors
66   + used to implement radio groups and overlays, and to deal with things
67     like keys that physically lock; unused in current keymaps
68 - indicator behaviours such as LED-controls-key
69   + the only supported LED behaviour is key-controls-LED; again this
70     was never really used in current keymaps
71
72 Notable additions:
73 - 32-bit keycodes
74 - extended number of modifiers
75 - extended number of groups
76 - multiple keysyms per level
77   + this requires incompatible dataset changes, such that X11 would
78     not be able to parse these
79
80 ## Development
81
82 An extremely rudimentary homepage can be found at
83     http://xkbcommon.org
84
85 xkbcommon is maintained in git at
86     https://github.com/xkbcommon/libxkbcommon
87
88 Patches are always welcome, and may be sent to either
89     <xorg-devel@lists.x.org> or <wayland-devel@lists.freedesktop.org>
90
91 Bugs are also welcome, and may be reported either at
92     Bugzilla https://bugs.freedesktop.org/describecomponents.cgi?product=libxkbcommon
93 or
94     Github https://github.com/xkbcommon/libxkbcommon/issues
95
96 The maintainers are
97 - Daniel Stone <daniel@fooishbar.org>
98 - Ran Benita <ran234@gmail.com>
99
100 ## Credits
101
102 Many thanks are due to Dan Nicholson for his heroic work in getting xkbcommon
103 off the ground initially.