kc3-lang/libxkbcommon/doc/rules-format.md
Branch :
Log
| Author | Commit | Date | CI | Message |
|---|---|---|---|---|
 |
fab9d25b | 2025-06-17 11:43:22 | rules: Add support for layout-specific options Enabled specifying a layout index for each option, so that it applies only if the layout matches. The layout index is specified by appending immediately after the option name the `!` specifier delimiter and then the layout index, in decimal form and 1-indexed. Note that `!` was chosen instead of the usual `:` specifier delimiter, because some options contains `:`, e.g. `grp:menu_toggle`. `!` *cannot* clash with component names, because `!` is a token in the rules files and thus cannot be used as in component names. It is also vaguely similar to `:`, compared to e.g. `@` or `#`. Example: given the following rules: ! layout[any] option = symbol * opt1 = +s1:%i l2 opt2 = +s2:%i it may result in the following configurations: | Layout | Option | Symbols | | -------- | -------- | ------------ | | `l1` | `opt1` | `+s1:1` | | `l2` | `opt1` | `+s1:1` | | `l1` | `opt2` | `` | | `l2` | `opt2` | `+s2:1` | | `l1,l2` | `opt1` | `+s1:1+s1:2` | | `l1,l2` | `opt1!1` | `+s1:1` | | `l1,l2` | `opt1!2` | `+s1:2` | | `l1,l2` | `opt2` | `+s2:2` | | `l1,l2` | `opt2!1` | `` | | `l1,l2` | `opt2!2` | `+s2:2` | | |
|
52a4d9b0 | 2025-06-17 11:03:12 | rules: Require layout or variant to enable %i expansion Before this commit, the following rule would always match: ! model = symbols * = s:%i and set symbols to `s:1`, but the `:%i` is aimed to be used only when the rules header specifies the layout or the variant. Let’s be strict and disallow matching this kind of buggy rule. Emit an error message so that we can detect it. | |
|
0106b357 | 2025-06-17 12:06:32 | registry: Add rxkb_option_is_layout_specific() Enable to query if an option accepts layout index specifiers to restrict its application to the corresponding layouts. | |
|
f7a61da7 | 2025-06-10 17:33:24 | doc: Update new layout count ranges | |
|
6d67bce5 | 2025-06-08 10:01:02 | doc: Towards and exhaustive compatibility page We need to track the compatibility with X11 with as much details as possible: - Transparency; - Facilitate answering issues by just pointing to the relevant page item; - Efficient reference documentation for development. | |
|
23598fa1 | 2025-03-25 22:52:06 | Enable merge mode “replace” in include statements Previously only the merge modes “override” and “augment” were available in include statements, using the prefix ‘+’ and ‘|’ respectively. While on one hand `replace` include statement can be used in keymap files, on the other hand *rules* files have no way to express the *replace* mode. This commit enables the merge mode “replace” using the prefix `^`. This prefix was chosen due to its similarity with the `XOR` bit operator, which convey *mutual exclusion*. Other candidates: - `!` conveys some kind of higher precedence, akin to CSS `!important`. But it conflicts with the section header `!`, which is a token in the current parser. It would require special handling, not worth it. It also convey the meaning of negation, which is confusing. - `&` has the advantage of not corresponding to a token in the rules parser. `^` seems however to stand out more and it is less likely to trigger erroneous comparison with `|` and `&` bit operators. | |
|
6fc6e64b | 2025-03-26 10:35:22 | rules: Added extended wild cards <none>, <some> and <any> Added the following wild cards to the rules file syntax, in addition to the current `*` legacy wild card: - `<none>`: Match *empty* value. - `<some>`: Match *non-empty* value. - `<any>`: Match *any* (optionally empty) value. Its behavior does not depend on the context, contrary to the legacy wild card `*`. This will enable writing much simpler rules, see [!764] for an example of tricky rules in the `xkeyboard-config` project, that would benefit from the new wild cards. [!764]: https://gitlab.freedesktop.org/xkeyboard-config/xkeyboard-config/-/merge_requests/764 The verbose wild cards are preferred to single characters: - More intuitive: self-explanatory. - Does not steal syntax from other token. - Extensible syntax, should we need it. A previous proposal used the characters (`!`, `+`, `?`) for their similarity with the corresponding syntax of regular expressions (negative assertion & quantifiers), in line with `*`. But `!` is not that intuitive after all and conflict with its role as section header. Furthermore, `+` is also used as a merge mode. Finally, nothing beats whole short words for readability. | |
|
04220319 | 2025-03-08 17:57:56 | doc: Warn about the options order Options are always applied depending of their order in the relevant rules files, independently of their order in the relevant RMLVO config. Since this is counter-intuitive (e.g. when using `xkbcli`), let’s highlight this in the documentation. | |
|
4ea9d431 | 2023-11-16 17:12:03 | rules: Add support for :all qualifier Some layout options require to be applied to every group to maintain consistency (e.g. a group switcher). Currently this must be done manually for all layout indexes. This is error prone and prevents the increase of the maximum group count. This commit introduces the `:all` qualifier for KcCGST values. When a rule with this qualifier is matched, it will expands the qualified value (and its optional merge mode) for every layout, e.g. `+group(toggle):all` (respectively `|group(toggle)`) would expand to `+group(toggle):1+group(toggle):2` (respectively `|group(toggle):1|group(toggle):2`) if there are 2 layouts, etc. If there is no merge mode, it defaults to *override* `+`, e.g. `x:all` expands to `x:1+x:2+x:3` for 3 layouts. Note that only the qualified *value* is expanded, e.g. `x+y:all` expands to `x+y:1+y:2` for 2 layouts. `:all` can be used in combination with special layout indexes. Since this can lead to an unexpected behaviour, a warning will be raised. | |
|
cdafba4f | 2024-09-24 15:23:16 | rules: Add support for index ranges There is a lot of repetition in the current rules files provided by xkeyboard-config, because the MLVO mappings need to match on the exact layout/variant index. This also prevents to increase the number of maximum groups, because it does not scale. We introduces the following new special layout/variant indexes: - “single”: matches a single layout; same as with no index. - “first”: matches the first layout/variant, no matter how many layouts are in the RMLVO configuration. It allows to merge `layout` and `layout[1]` patterns. - “later”: matches all but the first layout. This is an index range. - “any”: matches layout at any position. This is an index range. We also introduces the new `%i` expansion, which correspond to the index of the matched layout in a mapping with an index range. Example: layout[later] = symbols my_layout = +my_symbols:%i * = +%l[%i]:%i Let’s have a look at concrete examples from xkeyboard-config: ! model layout = symbols * * = pc+%l%(v) ! model layout[1] = symbols * * = pc+%l[1]%(v[1]) ! model layout[2] = symbols * * = +%l[2]%(v[2]) ! model layout[3] = symbols * * = +%l[3]%(v[3]) ! model layout[4] = symbols * * = +%l[4]%(v[4]) ! layout option = symbols * grp:toggle = +group(toggle) ! layout[1] option = symbols * grp:toggle = +group(toggle):1 ! layout[2] option = symbols * grp:toggle = +group(toggle):2 ! layout[3] option = symbols * grp:toggle = +group(toggle):3 ! layout[4] option = symbols * grp:toggle = +group(toggle):4 With this commit we can now simplify it into: ! model layout[first] = symbols * * = pc+%l[%i]%(v[%i]) ! model layout[later] = symbols * * = +%l[%i]%(v[%i]):%i ! layout[any] option = symbols * grp:toggle = +group(toggle):%i The latter rule will work even if we increase XKB_MAX_GROUPS, whereas the former would require to add the missing entries for the new groups. In order to maintain consistent rules, we now disallow layout and variant to have different indexes. For example, the following mapping are now invalid: - layout variant[1] - layout[1] variant[2] - layout[1] variant - layout[first] variant[1] - layout[first] variant - layout variant[any] - etc. | |
|
05ba96db | 2024-08-20 16:41:38 | rules: Fix wild card handling The handling of wild card `*` is different in libxkbfile and X server: wild card matches empty strings for model and option but not for layout nor variant, while in libxkbcommon wild cards always match empty strings. See: - https://gitlab.freedesktop.org/xorg/lib/libxkbfile/-/blob/bf985c68acb1244f51ec91414532a2347fbc1c4c/src/maprules.c#L687 - https://gitlab.freedesktop.org/xorg/lib/libxkbfile/-/blob/bf985c68acb1244f51ec91414532a2347fbc1c4c/src/maprules.c#L712 The difference of handling between the components is unfortunately not documented, but we should follow the behavior of the original implementations for consistency. - Fixed by implementing the same behavior than libxkbfile. - Added tests and fixed failing tests. - Improve the documentation of rules to highlight the special behavior. | |
|
32179d91 | 2024-03-01 08:44:35 | doc: Improve rules - Improved introduction - Added examples - Added RMLVO resolution process | |
|
79502700 | 2023-11-14 10:10:50 | Doc: fix malformed links and some typos | |
 |
c1b6c79a | 2023-07-31 22:35:16 | doc: fix some Doxygen warnings ``` libxkbcommon/doc/introduction-to-xkb.md:67: warning: unable to resolve reference to 'rule-file-format' for \ref command libxkbcommon/doc/introduction-to-xkb.md:181: warning: unable to resolve reference to 'keymap-text-format-v1' for \ref command libxkbcommon/doc/rules-format.md:10: warning: unable to resolve reference to 'xkb-intro' for \ref command ``` Signed-off-by: Ran Benita <ran@unusedvar.com> | |
|
fc664cf1 | 2023-05-13 05:30:11 | Improve documentation - Add introduction to XKB - Embrace Doxygen features - More cross links | |
 |
d7b39f6f | 2020-07-10 08:50:02 | Add /etc/xkb as extra lookup path for system data files This completes the usual triplet of configuration locations available for most processes: - vendor-provided data files in /usr/share/X11/xkb - system-specific data files in /etc/xkb - user-specific data files in $XDG_CONFIG_HOME/xkb The default lookup order user, system, vendor, just like everything else that uses these conventions. For include directives in rules files, the '%E' resolves to that path. Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net> | |
|
a2657874 | 2020-06-02 16:11:33 | 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> |