From a26578742c9c3addd5045606269f2e5c03dd4d1a Mon Sep 17 00:00:00 2001 From: Peter Hutterer 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 --- 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" @@ -58,12 +59,14 @@ Kccgst ::= "keycodes" | "symbols" | "types" | "compat" | "geometry" Rule ::= { MlvoValue } "=" { KccgstValue } "\n" MlvoValue ::= "*" | GroupName | KccgstValue ::= +``` 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', -- 2.7.4