1The rules file 2============== 3 4The purpose of the rules file is to map between configuration values 5that are easy for a user to specify and understand, and the 6configuration values xkbcomp uses and understands. 7 8xkbcomp uses the xkb_component_names struct, which maps directly to 9include statements of the appropriate sections, called for short 10KcCGST (see doc/keymap-format-text-v1.txt; 'G' stands for "geometry", 11which is not supported). These are not really intuitive or straight- 12forward for the uninitiated. 13 14Instead, the user passes in a xkb_rule_names struct, which consists 15of the name of a rules file (in Linux this is usually "evdev"), a 16keyboard model (e.g. "pc105"), a set of layouts (which will end up 17in different groups, e.g. "us,fr"), variants (used to alter/augment 18the respective layout, e.g. "intl,dvorak"), and a set of options 19(used to tweak some general behavior of the keyboard, e.g. 20"ctrl:nocaps,compose:menu" to make the Caps Lock key act like Ctrl 21and the Menu key like Compose). We call these RMLVO. 22 23Format of the file 24------------------ 25The file consists of rule sets, each consisting of rules (one per 26line), which match the MLVO values on the left hand side, and, if 27the values match to the values the user passed in, results in the 28values on the right hand side being added to the resulting KcCGST. 29Since some values are related and repeated often, it is possible 30to group them together and refer to them by a group name in the 31rules. 32 33Along with matching values by simple string equality, and for 34membership in a group defined previously, rules may also contain 35"wildcard" values - "*" - which always match. These usually appear 36near the end. 37 38Grammar 39------- 40(It might be helpful to look at a file like rules/evdev along with 41this grammer. Comments, whitespace, etc. are not shown.) 42 43File ::= { "!" (Group | RuleSet) } 44 45Group ::= GroupName "=" { GroupElement } "\n" 46GroupName ::= "$"<ident> 47GroupElement ::= <ident> 48 49RuleSet ::= Mapping { Rule } 50 51Mapping ::= { Mlvo } "=" { Kccgst } "\n" 52Mlvo ::= "model" | "option" | ("layout" | "variant") [ Index ] 53Index ::= "[" 1..XKB_NUM_GROUPS "]" 54Kccgst ::= "keycodes" | "symbols" | "types" | "compat" | "geometry" 55 56Rule ::= { MlvoValue } "=" { KccgstValue } "\n" 57MlvoValue ::= "*" | GroupName | <ident> 58KccgstValue ::= <ident> 59 60Notes: 61 62- The order of values in a Rule must be the same as the Mapping it 63 follows. The mapping line determines the meaning of the values in 64 the rules which follow in the RuleSet. 65 66- If a Rule is matched, %-expansion is performed on the KccgstValue, 67 as follows: 68 69 %m, %l, %v: 70 The model, layout or variant, if only one was given (e.g. 71 %l for "us,il" is invalid). 72 73 %l[1], %v[1]: 74 Layout or variant for the specified group Index, if more than 75 one was given (e.g. %l[1] for "us" is invalid). 76 77 %+m, %+l, %+v, %+l[1], %+v[1] 78 As above, but prefixed with '+'. Similarly, '|', '-', '_' may be 79 used instead of '+'. 80 81 %(m), %(l), %(l[1]), %(v), %(v[1]): 82 As above, but prefixed by '(' and suffixed by ')'. 83 84 In case the expansion is invalid, as described above, it is 85 skipped (the rest of the string is still processed); this includes 86 the prefix and suffix (that's why you shouldn't use e.g. "(%v[1])"). 87