From a26578742c9c3addd5045606269f2e5c03dd4d1a Mon Sep 17 00:00:00 2001
From: Peter Hutterer <peter.hutterer@who-t.net>
Date: Tue, 2 Jun 2020 16:11:33 +1000
Subject: [PATCH] doc: add the rules-format file (as markdown)

Useful to have this as part of the documentation. The rendering isn't great but
at least not any worse than pure text. Markdown escapes % so explaining our use
of %S and %H would require a double % - not idea. Let's just wrap it as a code
block and done.

Includes two typo fixes too, yay.

Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
---
 doc/{rules-format.txt => rules-format.md} | 10 ++++++++--
 meson.build                               |  1 +
 2 files changed, 9 insertions(+), 2 deletions(-)
 rename doc/{rules-format.txt => rules-format.md} (96%)

diff --git a/doc/rules-format.txt b/doc/rules-format.md
similarity index 96%
rename from doc/rules-format.txt
rename to doc/rules-format.md
index d97d8e8..96acbbf 100644
--- a/doc/rules-format.txt
+++ b/doc/rules-format.md
@@ -38,8 +38,9 @@ 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.)
+this grammar. Comments, whitespace, etc. are not shown.)
 
+```
 File         ::= { "!" (Include | Group | RuleSet) }
 
 Include      ::= "include" <ident>
@@ -58,12 +59,14 @@ 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:
+  in order. %-expansion is performed, as follows:
 
+```
   %%:
     A literal %.
 
@@ -72,6 +75,7 @@ Notes:
 
   %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
@@ -80,6 +84,7 @@ Notes:
 - 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).
@@ -94,6 +99,7 @@ Notes:
 
   %(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
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',