Add a proper README

Signed-off-by: Daniel Stone <daniel@fooishbar.org>

diff --git a/README b/README
index d9851d1..e9d6aba 100644 (file)
--- a/README
+++ b/README
@@ -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.