Commit 517464eb7ad584fb387b95bccf2b22ec6f3e87af

Ran Benita 2020-01-18T23:06:58

doc/rules-format.txt: document include support Signed-off-by: Ran Benita <ran@unusedvar.com>

diff --git a/doc/rules-format.txt b/doc/rules-format.txt
index e8959fd..d97d8e8 100644
--- a/doc/rules-format.txt
+++ b/doc/rules-format.txt
@@ -40,7 +40,9 @@ Grammar
 (It might be helpful to look at a file like rules/evdev along with
 this grammer. Comments, whitespace, etc. are not shown.)
 
-File         ::= { "!" (Group | RuleSet) }
+File         ::= { "!" (Include | Group | RuleSet) }
+
+Include      ::= "include" <ident>
 
 Group        ::= GroupName "=" { GroupElement } "\n"
 GroupName    ::= "$"<ident>
@@ -59,6 +61,18 @@ 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.