kc3-lang/libxkbcommon

diff --git a/doc/rules-format.md b/doc/rules-format.md
new file mode 100644
index 0000000..96acbbf
--- /dev/null
+++ b/doc/rules-format.md
@@ -0,0 +1,106 @@
+The rules file
+==============
+
+The purpose of the rules file is to map between configuration values
+that are easy for a user to specify and understand, and the
+configuration values xkbcomp uses and understands.
+
+xkbcomp uses the xkb_component_names struct, which maps directly to
+include statements of the appropriate sections, called for short
+KcCGST (see doc/keymap-format-text-v1.txt; 'G' stands for "geometry",
+which is not supported). These are not really intuitive or straight-
+forward for the uninitiated.
+
+Instead, the user passes in a xkb_rule_names struct, which consists
+of the name of a rules file (in Linux this is usually "evdev"), a
+keyboard model (e.g. "pc105"), a set of layouts (which will end up
+in different groups, e.g. "us,fr"), variants (used to alter/augment
+the respective layout, e.g. "intl,dvorak"), and a set of options
+(used to tweak some general behavior of the keyboard, e.g.
+"ctrl:nocaps,compose:menu" to make the Caps Lock key act like Ctrl
+and the Menu key like Compose). We call these RMLVO.
+
+Format of the file
+------------------
+The file consists of rule sets, each consisting of rules (one per
+line), which match the MLVO values on the left hand side, and, if
+the values match to the values the user passed in, results in the
+values on the right hand side being added to the resulting KcCGST.
+Since some values are related and repeated often, it is possible
+to group them together and refer to them by a group name in the
+rules.
+
+Along with matching values by simple string equality, and for
+membership in a group defined previously, rules may also contain
+"wildcard" values - "*" - which always match. These usually appear
+near the end.
+
+Grammar
+-------
+(It might be helpful to look at a file like rules/evdev along with
+this grammar. Comments, whitespace, etc. are not shown.)
+
+```
+File         ::= { "!" (Include | Group | RuleSet) }
+
+Include      ::= "include" <ident>
+
+Group        ::= GroupName "=" { GroupElement } "\n"
+GroupName    ::= "$"<ident>
+GroupElement ::= <ident>
+
+RuleSet      ::= Mapping { Rule }
+
+Mapping      ::= { Mlvo } "=" { Kccgst } "\n"
+Mlvo         ::= "model" | "option" | ("layout" | "variant") [ Index ]
+Index        ::= "[" 1..XKB_NUM_GROUPS "]"
+Kccgst       ::= "keycodes" | "symbols" | "types" | "compat" | "geometry"
+
+Rule         ::= { MlvoValue } "=" { KccgstValue } "\n"
+MlvoValue    ::= "*" | GroupName | <ident>
+KccgstValue  ::= <ident>
+```
+
+Notes:
+
+- Include processes the rules in the file path specified in the ident,
+  in order. %-expansion is performed, as follows:
+
+```
+  %%:
+    A literal %.
+
+  %H:
+    The value of the HOME environment variable.
+
+  %S:
+    The system-installed rules directory (usually /usr/share/X11/xkb/rules).
+```
+
+- The order of values in a Rule must be the same as the Mapping it
+  follows. The mapping line determines the meaning of the values in
+  the rules which follow in the RuleSet.
+
+- If a Rule is matched, %-expansion is performed on the KccgstValue,
+  as follows:
+
+```
+  %m, %l, %v:
+     The model, layout or variant, if only one was given (e.g.
+     %l for "us,il" is invalid).
+
+  %l[1], %v[1]:
+     Layout or variant for the specified group Index, if more than
+     one was given (e.g. %l[1] for "us" is invalid).
+
+  %+m, %+l, %+v, %+l[1], %+v[1]
+     As above, but prefixed with '+'. Similarly, '|', '-', '_' may be
+     used instead of '+'.
+
+  %(m), %(l), %(l[1]), %(v), %(v[1]):
+     As above, but prefixed by '(' and suffixed by ')'.
+```
+
+  In case the expansion is invalid, as described above, it is
+  skipped (the rest of the string is still processed); this includes
+  the prefix and suffix (that's why you shouldn't use e.g. "(%v[1])").
diff --git a/doc/rules-format.txt b/doc/rules-format.txt
deleted file mode 100644
index d97d8e8..0000000
--- a/doc/rules-format.txt
+++ /dev/null
@@ -1,100 +0,0 @@
-The rules file
-==============
-
-The purpose of the rules file is to map between configuration values
-that are easy for a user to specify and understand, and the
-configuration values xkbcomp uses and understands.
-
-xkbcomp uses the xkb_component_names struct, which maps directly to
-include statements of the appropriate sections, called for short
-KcCGST (see doc/keymap-format-text-v1.txt; 'G' stands for "geometry",
-which is not supported). These are not really intuitive or straight-
-forward for the uninitiated.
-
-Instead, the user passes in a xkb_rule_names struct, which consists
-of the name of a rules file (in Linux this is usually "evdev"), a
-keyboard model (e.g. "pc105"), a set of layouts (which will end up
-in different groups, e.g. "us,fr"), variants (used to alter/augment
-the respective layout, e.g. "intl,dvorak"), and a set of options
-(used to tweak some general behavior of the keyboard, e.g.
-"ctrl:nocaps,compose:menu" to make the Caps Lock key act like Ctrl
-and the Menu key like Compose). We call these RMLVO.
-
-Format of the file
-------------------
-The file consists of rule sets, each consisting of rules (one per
-line), which match the MLVO values on the left hand side, and, if
-the values match to the values the user passed in, results in the
-values on the right hand side being added to the resulting KcCGST.
-Since some values are related and repeated often, it is possible
-to group them together and refer to them by a group name in the
-rules.
-
-Along with matching values by simple string equality, and for
-membership in a group defined previously, rules may also contain
-"wildcard" values - "*" - which always match. These usually appear
-near the end.
-
-Grammar
--------
-(It might be helpful to look at a file like rules/evdev along with
-this grammer. Comments, whitespace, etc. are not shown.)
-
-File         ::= { "!" (Include | Group | RuleSet) }
-
-Include      ::= "include" <ident>
-
-Group        ::= GroupName "=" { GroupElement } "\n"
-GroupName    ::= "$"<ident>
-GroupElement ::= <ident>
-
-RuleSet      ::= Mapping { Rule }
-
-Mapping      ::= { Mlvo } "=" { Kccgst } "\n"
-Mlvo         ::= "model" | "option" | ("layout" | "variant") [ Index ]
-Index        ::= "[" 1..XKB_NUM_GROUPS "]"
-Kccgst       ::= "keycodes" | "symbols" | "types" | "compat" | "geometry"
-
-Rule         ::= { MlvoValue } "=" { KccgstValue } "\n"
-MlvoValue    ::= "*" | GroupName | <ident>
-KccgstValue  ::= <ident>
-
-Notes:
-
-- Include processes the rules in the file path specified in the ident,
-  in order. %-expanasion is performed, as follows:
-
-  %%:
-    A literal %.
-
-  %H:
-    The value of the HOME environment variable.
-
-  %S:
-    The system-installed rules directory (usually /usr/share/X11/xkb/rules).
-
-- The order of values in a Rule must be the same as the Mapping it
-  follows. The mapping line determines the meaning of the values in
-  the rules which follow in the RuleSet.
-
-- If a Rule is matched, %-expansion is performed on the KccgstValue,
-  as follows:
-
-  %m, %l, %v:
-     The model, layout or variant, if only one was given (e.g.
-     %l for "us,il" is invalid).
-
-  %l[1], %v[1]:
-     Layout or variant for the specified group Index, if more than
-     one was given (e.g. %l[1] for "us" is invalid).
-
-  %+m, %+l, %+v, %+l[1], %+v[1]
-     As above, but prefixed with '+'. Similarly, '|', '-', '_' may be
-     used instead of '+'.
-
-  %(m), %(l), %(l[1]), %(v), %(v[1]):
-     As above, but prefixed by '(' and suffixed by ')'.
-
-  In case the expansion is invalid, as described above, it is
-  skipped (the rest of the string is still processed); this includes
-  the prefix and suffix (that's why you shouldn't use e.g. "(%v[1])").
diff --git a/meson.build b/meson.build
index 9729bca..2ea360d 100644
--- a/meson.build
+++ b/meson.build
@@ -543,6 +543,7 @@ You can disable the documentation with -Denable-docs=false.''')
         'doc/doxygen-extra.css',
         'doc/quick-guide.md',
         'doc/compat.md',
+        'doc/rules-format.md',
         'xkbcommon/xkbcommon.h',
         'xkbcommon/xkbcommon-names.h',
         'xkbcommon/xkbcommon-x11.h',