doc/rules-format.md

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