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