From 494a8fbf3fdfff79cb763556db8b018b623d7ff9 Mon Sep 17 00:00:00 2001 From: Ran Benita Date: Sat, 18 Oct 2014 13:50:54 +0300 Subject: [PATCH] README: move compatibility notes to their own page Signed-off-by: Ran Benita --- Makefile.am | 1 + README.md | 43 +------------------------------------------ doc/Doxyfile.in | 1 + doc/compat.md | 46 ++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 49 insertions(+), 42 deletions(-) create mode 100644 doc/compat.md diff --git a/Makefile.am b/Makefile.am index 9071e90..b2bdbe7 100644 --- a/Makefile.am +++ b/Makefile.am @@ -9,6 +9,7 @@ EXTRA_DIST = \ test/data \ README.md \ doc/quick-guide.md \ + doc/compat.md \ doc/keymap-format-text-v1.txt \ doc/rules-format.txt diff --git a/README.md b/README.md index c4174ad..2d71d67 100644 --- a/README.md +++ b/README.md @@ -34,48 +34,7 @@ xkeyboard-config is available here: ## 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 -- key behaviors - + used to implement radio groups and overlays, and to deal with things - like keys that physically lock; 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 +See [Compatibility](doc/compat.md) notes. ## Development diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in index 910e8a7..8ef97b6 100644 --- a/doc/Doxyfile.in +++ b/doc/Doxyfile.in @@ -656,6 +656,7 @@ WARN_LOGFILE = INPUT = @abs_top_srcdir@/README.md \ @abs_top_srcdir@/doc/quick-guide.md \ + @abs_top_srcdir@/doc/compat.md \ @abs_top_srcdir@/xkbcommon/xkbcommon.h \ @abs_top_srcdir@/xkbcommon/xkbcommon-names.h \ @abs_top_srcdir@/xkbcommon/xkbcommon-x11.h \ diff --git a/doc/compat.md b/doc/compat.md new file mode 100644 index 0000000..22c6164 --- /dev/null +++ b/doc/compat.md @@ -0,0 +1,46 @@ +# Compatibility + +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 +- key behaviors + + used to implement radio groups and overlays, and to deal with things + like keys that physically lock; 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 + +On the other hand, some features and extensions were added. + +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