From 3923aa71c23f572096aeb3fee36f62b6cafb95e7 Mon Sep 17 00:00:00 2001 From: Ran Benita Date: Sun, 9 Feb 2014 11:27:34 +0200 Subject: [PATCH] doc: move some file comments into txt files in doc/ Signed-off-by: Ran Benita --- doc/keymap-format-text-v1.txt | 359 ++++++++++++++++++++++++++++++++++++++++++ doc/rules-format.txt | 86 ++++++++++ src/xkbcomp/compat.c | 173 -------------------- src/xkbcomp/keycodes.c | 73 --------- src/xkbcomp/rules.c | 78 --------- src/xkbcomp/types.c | 105 ------------ 6 files changed, 445 insertions(+), 429 deletions(-) create mode 100644 doc/keymap-format-text-v1.txt create mode 100644 doc/rules-format.txt diff --git a/doc/keymap-format-text-v1.txt b/doc/keymap-format-text-v1.txt new file mode 100644 index 0000000..95849fc --- /dev/null +++ b/doc/keymap-format-text-v1.txt @@ -0,0 +1,359 @@ +The xkb_keycodes section +======================== + +This is the simplest section type, and is the first one to be +compiled. The purpose of this is mostly to map between the +hardware/evdev scancodes and xkb keycodes. Each key is given a name +by which it can be referred to later, e.g. in the symbols section. + +Keycode statements +------------------ +Statements of the form: + + = 49; + = 10; + +The above would let 49 and 10 be valid keycodes in the keymap, and +assign them the names TLDE and AE01 respectively. The format is +always used to refer to a key by name. + +[The naming convention just denoted the position of the key +in the main alphanumric section of the keyboard, with the two letters +specifying the row and the two digits specifying the column, from +the bottom left.] + +In the common case this just maps to the evdev scancodes from +/usr/include/linux/input.h, e.g. the following definitions: + + #define KEY_GRAVE 41 + #define KEY_1 2 + +correspond to the ones above. Similar definitions appear in the +xf86-input-keyboard driver. Note that in all current keymaps there's a +constant offset of 8 (for historical reasons). + +If there's a conflict, like the same name given to different keycodes, +or same keycode given different names, it is resolved according to the +merge mode which applies to the definitions. + +Alias statements +---------------- +Statements of the form: + + alias = ; + +Allows to refer to a previously defined key (here ) by another +name (here ). Conflicts are handled similarly to keycode +statements. + +LED name statements +------------------- +Statements of the form: + + indicator 1 = "Caps Lock"; + indicator 2 = "Num Lock"; + indicator 3 = "Scroll Lock"; + +Assigns a name to the keyboard LED (a.k.a indicator) with the given +index. The LED may be referred by this name later in the compat section +and by the user. + + +The xkb_types section +===================== + +This section is the second to be processesed, after xkb_keycodes. +However, it is completely independent and could have been the first +to be processed (it does not refer to specific keys as specified in +the xkb_keycodes section). + +This section defines key types, which, given a key and a keyboard +state (i.e. modifier state and group), determine the shift level to +be used in translating the key to keysyms. These types are assigned +to each group in each key, in the xkb_symbols section. + +Key types are called this way because, in a way, they really describe +the "type" of the key (or more correctly, a specific group of the +key). For example, an ordinary keymap will provide a type called +"KEYPAD", which consists of two levels, with the second level being +chosen according to the state of the Num Lock (or Shift) modifiers. +Another example is a type called "ONE_LEVEL", which is usually +assigned to keys such as Escape; these have just one level and are +not affected by the modifier state. Yet more common examples are +"TWO_LEVEL" (with Shift choosing the second level), "ALPHABETIC" +(where Caps Lock may also choose the second level), etc. + +Type definitions +---------------- +Statements of the form: + + type "FOUR_LEVEL" { ... } + +The above would create a new type named "FOUR_LEVEL". +The body of the definition may include statements of the following +forms: + +- level_name statements (mandatory for each level in the type): + + level_name[Level1] = "Base"; + + Gives each level in this type a descriptive name. It isn't used + for anything. + Note: A level may be specified as Level[1-8] or just a number (can + be more than 8). + +- modifiers statement (mandatory, should be specified only once): + + modifiers = Shift+Lock+LevelThree; + + A mask of real and virtual modifiers. These are the only modifiers + being considered when matching the modifier state against the type. + The other modifiers, whether active or not, are masked out in the + calculation. + +- map entry statements (should have at least as many mappings as there + are levels in the type): + + map[Shift+LevelThree] = Level4; + + If the active modifiers, masked with the type's modifiers (as stated + above), match (i.e. equal) the modifiers inside the map[] statement, + then the level in the right hand side is chosen. For example, in the + above, if in the current keyboard state the Shift and LevelThree + modifiers are active, while the Lock modifier is not, then the + keysym(s) in the 4th level of the group will be returned to the + user. + +- preserve statements: + + map[Shift+Lock+LevelThree] = Level5; + preserve[Shift+Lock+LevelThree] = Lock; + + When a map entry matches the active modifiers and the level it + specified is chosen, then these modifiers are said to be "consumed"; + for example, in a simple US keymap where the "g" key is assigned an + ordinary ALPHABETIC key type, if the Lock (Caps Lock) modifier is + active and the key is pressed, then a "G" keysym is produced (as + opposed to lower-case "g"). This is because the type definition has + a map entry like the following: + + map[Lock] = Level2; + + And as such the Lock modifier is consumed. This information is + relevant for applications which further process the modifiers, + since by then the consumed modifiers have already "done their part" + and should be masked out. + + However, sometimes even if a modifier is actually used to choose + the shift level (as Lock above), it should *not* be reported as + consumed, for various reasons. In this case, a preserve[] statement + can be used to augment the map entry. The modifiers inside the square + brackets should match one of the map[] statements in the type. The + right hand side should consists of modifiers from the left hand + side; these modifiers are then "preserved" and not reported as + consumed. + + +The xkb_compat section +====================== + +This section is the third to be processed, after xkb_keycodes and +xkb_types. + +Interpret statements +-------------------- +Statements of the form: + + interpret Num_Lock+Any { ... } + interpret Shift_Lock+AnyOf(Shift+Lock) { ... } + +The xkb_symbols section (see below) allows the keymap author to perform, +among other things, the following things for each key: + +- Bind an action, like SetMods or LockGroup, to the key. Actions, like + symbols, are specified for each level of each group in the key + separately. + +- Add a virtual modifier to the key's virtual modifier mapping (vmodmap). + +- Specify whether the key should repeat or not. + +However, doing this for each key (or level) is tedious and inflexible. +Interpret's are a mechanism to apply these settings to a bunch of +keys/levels at once. + +Each interpret specifies a condition by which it attaches to certain +levels. The condition consists of two parts: + +- A keysym. If the level has a different (or more than one) keysym, the + match fails. Leaving out the keysym is equivalent to using the NoSymbol + keysym, which always matches successfully. + +- A modifier predicate. The predicate consists of a matching operation + and a mask of (real) modifiers. The modifiers are matched against the + key's modifier map (modmap). The matching operation can be one of the + following: + + * AnyOfOrNone - The modmap must either be empty or include at least + one of the specified modifiers. + * AnyOf - The modmap must include at least one of the specified + modifiers. + * NoneOf - The modmap must not include any of the specified modifiers. + * AllOf - The modmap must include all of the specified modifiers (but + may include others as well). + * Exactly - The modmap must be exactly the same as the specified + modifiers. + + Leaving out the predicate is equivalent to using AnyOfOrNone while + specifying all modifiers. Leaving out just the matching condition + is equivalent to using Exactly. + +An interpret may also include "useModMapMods = level1;" - see below. + +If a level fulfils the conditions of several interpret's, only the +most specific one is used: + +- A specific keysym will always match before a generic NoSymbol + condition. + +- If the keysyms are the same, the interpret with the more specific + matching operation is used. The above list is sorted from least to + most specific. + +- If both the keysyms and the matching operations are the same (but the + modifiers are different), the first interpret is used. + +As described above, once an interpret "attaches" to a level, it can bind +an action to that level, add one virtual modifier to the key's vmodmap, +or set the key's repeat setting. You should note the following: + +- The key repeat is a property of the entire key; it is not level-specific. + In order to avoid confusion, it is only inspected for the first level of + the first group; the interpret's repeat setting is ignored when applied + to other levels. + +- If one of the above fields was set directly for a key in xkb_symbols, + the explicit setting takes precedence over the interpret. + +The body of the statement may include statements of the following +forms (all of which are optional): + +- useModMapMods statement: + + useModMapMods = level1; + + When set to 'level1', the interpret will only match levels which are + the first level of the first group of the keys. This can be useful in + conjunction with e.g. a virtualModifier statement. + +- action statement: + + action = LockMods(modifiers=NumLock); + + Bind this action to the matching levels. + +- virtual modifier statement: + + virtualModifier = NumLock; + + Add this virtual modifier to the key's vmodmap. The given virtual + modifier must be declared at the top level of the file with a + virtual_modifiers statement, e.g.: + + virtual_modifiers NumLock; + +- repeat statement: + + repeat = True; + + Set whether the key should repeat or not. Must be a boolean value. + +LED map statements +------------------ +Statements of the form: + + indicator "Shift Lock" { ... } + +This statement specifies the behavior and binding of the LED (a.k.a +indicator) with the given name ("Shift Lock" above). The name should +have been declared previously in the xkb_keycodes section (see LED +name statement), and given an index there. If it wasn't, it is created +with the next free index. +The body of the statement describes the conditions of the keyboard +state which will cause the LED to be lit. It may include the following +statements: + +- modifiers statement: + + modifiers = ScrollLock; + + If the given modifiers are in the required state (see below), the + LED is lit. + +- whichModifierState statment: + + whichModState = Latched+Locked; + + Can be any combination of: + + * base, latched, locked, effective + * any (i.e. all of the above) + * none (i.e. none of the above) + * compat (legacy value, treated as effective) + + This will cause the respective portion of the modifer state (see + struct xkb_state) to be matched against the modifiers given in the + "modifiers" statement. + + Here's a simple example: + + indicator "Num Lock" { + modifiers = NumLock; + whichModState = Locked; + }; + + Whenever the NumLock modifier is locked, the Num Lock LED will light + up. + +- groups statment: + + groups = All - group1; + + If the given groups are in the required state (see below), the LED + is lit. + +- whichGroupState statment: + + whichGroupState = Effective; + + Can be any combination of: + + * base, latched, locked, effective + * any (i.e. all of the above) + * none (i.e. none of the above) + + This will cause the respective portion of the group state (see + struct xkb_state) to be matched against the groups given in the + "groups" statement. + + Note: the above conditions are disjunctive, i.e. if any of them are + satisfied the LED is lit. + + +The xkb_symbols section +======================= + +This section is the fourth to be processed, after xkb_keycodes, +xkb_types and xkb_compat. + +TODO + + +Virtual modifier statements +=========================== + +Statements of the form: + virtual_modifiers LControl; + +Can appear in the xkb_types, xkb_compat, xkb_symbols sections. +TODO diff --git a/doc/rules-format.txt b/doc/rules-format.txt new file mode 100644 index 0000000..e8959fd --- /dev/null +++ b/doc/rules-format.txt @@ -0,0 +1,86 @@ +The rules file +============== + +The purpose of the rules file is to map between configuration values +that are easy for a user to specify and understand, and the +configuration values xkbcomp uses and understands. + +xkbcomp uses the xkb_component_names struct, which maps directly to +include statements of the appropriate sections, called for short +KcCGST (see doc/keymap-format-text-v1.txt; 'G' stands for "geometry", +which is not supported). These are not really intuitive or straight- +forward for the uninitiated. + +Instead, the user passes in a xkb_rule_names struct, which consists +of the name of a rules file (in Linux this is usually "evdev"), a +keyboard model (e.g. "pc105"), a set of layouts (which will end up +in different groups, e.g. "us,fr"), variants (used to alter/augment +the respective layout, e.g. "intl,dvorak"), and a set of options +(used to tweak some general behavior of the keyboard, e.g. +"ctrl:nocaps,compose:menu" to make the Caps Lock key act like Ctrl +and the Menu key like Compose). We call these RMLVO. + +Format of the file +------------------ +The file consists of rule sets, each consisting of rules (one per +line), which match the MLVO values on the left hand side, and, if +the values match to the values the user passed in, results in the +values on the right hand side being added to the resulting KcCGST. +Since some values are related and repeated often, it is possible +to group them together and refer to them by a group name in the +rules. + +Along with matching values by simple string equality, and for +membership in a group defined previously, rules may also contain +"wildcard" values - "*" - which always match. These usually appear +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.) + +File ::= { "!" (Group | RuleSet) } + +Group ::= GroupName "=" { GroupElement } "\n" +GroupName ::= "$" +GroupElement ::= + +RuleSet ::= Mapping { Rule } + +Mapping ::= { Mlvo } "=" { Kccgst } "\n" +Mlvo ::= "model" | "option" | ("layout" | "variant") [ Index ] +Index ::= "[" 1..XKB_NUM_GROUPS "]" +Kccgst ::= "keycodes" | "symbols" | "types" | "compat" | "geometry" + +Rule ::= { MlvoValue } "=" { KccgstValue } "\n" +MlvoValue ::= "*" | GroupName | +KccgstValue ::= + +Notes: + +- 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 + the rules which follow in the RuleSet. + +- 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). + + %l[1], %v[1]: + Layout or variant for the specified group Index, if more than + one was given (e.g. %l[1] for "us" is invalid). + + %+m, %+l, %+v, %+l[1], %+v[1] + As above, but prefixed with '+'. Similarly, '|', '-', '_' may be + used instead of '+'. + + %(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 + the prefix and suffix (that's why you shouldn't use e.g. "(%v[1])"). diff --git a/src/xkbcomp/compat.c b/src/xkbcomp/compat.c index fffb2d3..64e3537 100644 --- a/src/xkbcomp/compat.c +++ b/src/xkbcomp/compat.c @@ -54,179 +54,6 @@ #include "vmod.h" #include "include.h" -/* - * The xkb_compat section - * ===================== - * This section is the third to be processed, after xkb_keycodes and - * xkb_types. - * - * Interpret statements - * -------------------- - * Statements of the form: - * interpret Num_Lock+Any { ... } - * interpret Shift_Lock+AnyOf(Shift+Lock) { ... } - * - * The xkb_symbols section (see symbols.c) allows the keymap author to do, - * among other things, the following for each key: - * - Bind an action, like SetMods or LockGroup, to the key. Actions, like - * symbols, are specified for each level of each group in the key - * separately. - * - Add a virtual modifier to the key's virtual modifier mapping (vmodmap). - * - Specify whether the key should repeat or not. - * - * However, doing this for each key (or level) is tedious and inflexible. - * Interpret's are a mechanism to apply these settings to a bunch of - * keys/levels at once. - * - * Each interpret specifies a condition by which it attaches to certain - * levels. The condition consists of two parts: - * - A keysym. If the level has a different (or more than one) keysym, the - * match failes. Leaving out the keysym is equivalent to using the - * NoSymbol keysym, which always matches successfully. - * - A modifier predicate. The predicate consists of a matching operation - * and a mask of (real) modifiers. The modifers are matched against the - * key's modifier map (modmap). The matching operation can be one of the - * following: - * + AnyOfOrNone - The modmap must either be empty or include at least - * one of the specified modifiers. - * + AnyOf - The modmap must include at least one of the specified - * modifiers. - * + NoneOf - The modmap must not include any of the specified modifiers. - * + AllOf - The modmap must include all of the specified modifiers (but - * may include others as well). - * + Exactly - The modmap must be exactly the same as the specified - * modifiers. - * Leaving out the predicate is equivalent to usign AnyOfOrNone while - * specifying all modifiers. Leaving out just the matching condtition - * is equivalent to using Exactly. - * An interpret may also include "useModMapMods = level1;" - see below. - * - * If a level fulfils the conditions of several interpret's, only the - * most specific one is used: - * - A specific keysym will always match before a generic NoSymbol - * condition. - * - If the keysyms are the same, the interpret with the more specific - * matching operation is used. The above list is sorted from least to - * most specific. - * - If both the keysyms and the matching operations are the same (but the - * modifiers are different), the first interpret is used. - * - * As described above, once an interpret "attaches" to a level, it can bind - * an action to that level, add one virtual modifier to the key's vmodmap, - * or set the key's repeat setting. You should note the following: - * - The key repeat is a property of the entire key; it is not level-specific. - * In order to avoid confusion, it is only inspected for the first level of - * the first group; the interpret's repeat setting is ignored when applied - * to other levels. - * - If one of the above fields was set directly for a key in xkb_symbols, - * the explicit setting takes precedence over the interpret. - * - * The body of the statment may include statements of the following - * forms (all of which are optional): - * - * - useModMapMods statement: - * useModMapMods = level1; - * - * When set to 'level1', the interpret will only match levels which are - * the first level of the first group of the keys. This can be useful in - * conjunction with e.g. a virtualModifier statement. - * - * - action statement: - * action = LockMods(modifiers=NumLock); - * - * Bind this action to the matching levels. - * - * - virtual modifier statement: - * virtualModifier = NumLock; - * - * Add this virtual modifier to the key's vmodmap. The given virtual - * modifier must be declared at the top level of the file with a - * virtual_modifiers statement, e.g.: - * virtual_modifiers NumLock; - * - * - repeat statement: - * repeat = True; - * - * Set whether the key should repeat or not. Must be a boolean value. - * - * Led map statements - * ------------------------ - * Statements of the form: - * indicator "Shift Lock" { ... } - * - * This statement specifies the behavior and binding of the LED (a.k.a - * indicator) with the given name ("Shift Lock" above). The name should - * have been declared previously in the xkb_keycodes section (see Led - * name statement), and given an index there. If it wasn't, it is created - * with the next free index. - * The body of the statement describes the conditions of the keyboard - * state which will cause the LED to be lit. It may include the following - * statements: - * - * - modifiers statment: - * modifiers = ScrollLock; - * - * If the given modifiers are in the required state (see below), the - * led is lit. - * - * - whichModifierState statment: - * whichModState = Latched + Locked; - * - * Can be any combination of: - * base, latched, locked, effective - * any (i.e. all of the above) - * none (i.e. none of the above) - * compat (legacy value, treated as effective) - * This will cause the respective portion of the modifer state (see - * struct xkb_state) to be matched against the modifiers given in the - * "modifiers" statement. - * - * Here's a simple example: - * indicator "Num Lock" { - * modifiers = NumLock; - * whichModState = Locked; - * }; - * Whenever the NumLock modifier is locked, the Num Lock LED will light - * up. - * - * - groups statment: - * groups = All - group1; - * - * If the given groups are in the required state (see below), the led - * is lit. - * - * - whichGroupState statment: - * whichGroupState = Effective; - * - * Can be any combination of: - * base, latched, locked, effective - * any (i.e. all of the above) - * none (i.e. none of the above) - * This will cause the respective portion of the group state (see - * struct xkb_state) to be matched against the groups given in the - * "groups" statement. - * - * Note: the above conditions are disjunctive, i.e. if any of them are - * satisfied the led is lit. - * - * Virtual modifier statements - * --------------------------- - * Statements of the form: - * virtual_modifiers LControl; - * - * Can appear in the xkb_types, xkb_compat, xkb_symbols sections. - * TODO - * - * Effect on keymap - * ---------------- - * After all of the xkb_compat sections have been compiled, the following - * members of struct xkb_keymap are finalized: - * darray(struct xkb_sym_interpret) sym_interprets; - * darray(struct xkb_led) leds; - * char *compat_section_name; - * TODO: virtual modifiers. - */ - enum si_field { SI_FIELD_VIRTUAL_MOD = (1 << 0), SI_FIELD_ACTION = (1 << 1), diff --git a/src/xkbcomp/keycodes.c b/src/xkbcomp/keycodes.c index 59916b7..b7e70ce 100644 --- a/src/xkbcomp/keycodes.c +++ b/src/xkbcomp/keycodes.c @@ -29,79 +29,6 @@ #include "expr.h" #include "include.h" -/* - * The xkb_keycodes section - * ======================== - * - * This is the simplest section type, and is the first one to be - * compiled. The purpose of this is mostly to map between the - * hardware/evdev scancodes and xkb keycodes. Each key is given a name - * by which it can be referred to later, e.g. in the symbols section. - * - * Keycode statements - * ------------------ - * Statements of the form: - * = 49; - * = 10; - * - * The above would let 49 and 10 be valid keycodes in the keymap, and - * assign them the names TLDE and AE01 respectively. The format is - * always used to refer to a key by name. - * - * [ The naming convention just denoted the position of the key - * in the main alphanumric section of the keyboard, with the two letters - * specifying the row and the two digits specifying the column, from - * the bottom left.] - * - * In the common case this just maps to the evdev scancodes from - * /usr/include/linux/input.h, e.g. the following definitions: - * #define KEY_GRAVE 41 - * #define KEY_1 2 - * Similar definitions appear in the xf86-input-keyboard driver. Note - * that in all current keymaps there's a constant offset of 8 (for - * historical reasons). - * - * If there's a conflict, like the same name given to different keycodes, - * or same keycode given different names, it is resolved according to the - * merge mode which applies to the definitions. - * - * Alias statements - * ---------------- - * Statements of the form: - * alias = ; - * - * Allows to refer to a previously defined key (here ) by another - * name (here ). Conflicts are handled similarly. - * - * LED name statements - * ------------------------- - * Statements of the form: - * indicator 1 = "Caps Lock"; - * indicator 2 = "Num Lock"; - * indicator 3 = "Scroll Lock"; - * - * Assigns a name to the keyboard LED (a.k.a indicator) with the given index. - * The led may be referred by this name later in the compat section - * and by the user. - * - * Effect on the keymap - * -------------------- - * After all of the xkb_keycodes sections have been compiled, the - * following members of struct xkb_keymap are finalized: - * xkb_keycode_t min_key_code; - * xkb_keycode_t max_key_code; - * unsigned int num_aliases; - * struct xkb_key_alias *key_aliases; - * char *keycodes_section_name; - * The 'name' field of leds declared in xkb_keycodes: - * darray(struct xkb_led) leds; - * Further, the array of keys: - * struct xkb_key *keys; - * had been resized to its final size (i.e. all of the xkb_key objects are - * referable by their keycode). However the objects themselves do not - * contain any useful information besides the key name at this point. - */ - typedef struct { enum merge_mode merge; diff --git a/src/xkbcomp/rules.c b/src/xkbcomp/rules.c index b8c8e0c..c0fd656 100644 --- a/src/xkbcomp/rules.c +++ b/src/xkbcomp/rules.c @@ -52,84 +52,6 @@ #include "include.h" #include "scanner-utils.h" -/* - * The rules file - * ============== - * The purpose of this file is to map between configuration values that - * are easy for a user to specify and understand, and the configuration - * values xkbcomp uses and understands. - * xkbcomp uses the xkb_component_names struct, which maps directly to - * include statements of the appropriate sections, called for short - * KcCGST (see keycodes.c, types.c, compat.c, symbols.c; geometry.c was - * removed). These are not really intuitive or straight-forward for - * the uninitiated. - * Instead, the user passes in a xkb_rule_names struct, which consists - * of the name of a rules file (in Linux this is usually "evdev"), a - * keyboard model (e.g. "pc105"), a set of layouts (which will end up - * in different groups, e.g. "us,fr"), variants (used to alter/augment - * the respective layout, e.g. "intl,dvorak"), and a set of options - * (used to tweak some general behavior of the keyboard, e.g. - * "ctrl:nocaps,compose:menu" to make the Caps Lock key act like Ctrl - * and the Menu key like Compose). We call these RMLVO. - * - * Format of the file - * ------------------ - * The file consists of rule sets, each consisting of rules (one per - * line), which match the MLVO values on the left hand side, and, if - * the values match to the values the user passed in, results in the - * values on the right hand side being added to the resulting KcCGST. - * Since some values are related and repeated often, it is possible - * to group them together and refer to them by a group name in the - * rules. - * Along with matching values by simple string equality, and for - * membership in a group defined previously, rules may also contain - * "wildcard" values - "*" - which always match. These usually appear - * near the end. - * - * Grammer - * ------- - * (It might be helpful to look at a file like rules/evdev along with - * this grammer. Comments, whitespace, etc. are not shown.) - * - * File ::= { "!" (Group | RuleSet) } - * - * Group ::= GroupName "=" { GroupElement } "\n" - * GroupName ::= "$" - * GroupElement ::= - * - * RuleSet ::= Mapping { Rule } - * - * Mapping ::= { Mlvo } "=" { Kccgst } "\n" - * Mlvo ::= "model" | "option" | ("layout" | "variant") [ Index ] - * Index ::= "[" 1..XKB_NUM_GROUPS "]" - * Kccgst ::= "keycodes" | "symbols" | "types" | "compat" | "geometry" - * - * Rule ::= { MlvoValue } "=" { KccgstValue } "\n" - * MlvoValue ::= "*" | GroupName | - * KccgstValue ::= - * - * Notes: - * - 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 - * the rules which follow in the RuleSet. - * - 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). - * %l[1], %v[1]: - * Layout or variant for the specified group Index, if more than - * one was given (e.g. %l[1] for "us" is invalid). - * %+m, %+l, %+v, %+l[1], %+v[1] - * As above, but prefixed with '+'. Similarly, '|', '-', '_' may be - * used instead of '+'. - * %(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 - * the prefix and suffix (that's why you shouldn't use e.g. "(%v[1])"). - */ - /* Scanner / Lexer */ /* Values returned with some tokens, like yylval. */ diff --git a/src/xkbcomp/types.c b/src/xkbcomp/types.c index 5b7ccbb..f98d97a 100644 --- a/src/xkbcomp/types.c +++ b/src/xkbcomp/types.c @@ -30,111 +30,6 @@ #include "expr.h" #include "include.h" -/* - * The xkb_types section - * ===================== - * This section is the second to be processesed, after xkb_keycodes. - * However, it is completely independent and could have been the first - * to be processed (it does not refer to specific keys as specified in - * the xkb_keycodes section). - * - * This section defines key types, which, given a key and a keyboard - * state (i.e. modifier state and group), determine the shift level to - * be used in translating the key to keysyms. These types are assigned - * to each group in each key, in the xkb_symbols section. - * - * Key types are called this way because, in a way, they really describe - * the "type" of the key (or more correctly, a specific group of the - * key). For example, an ordinary keymap will provide a type called - * "KEYPAD", which consists of two levels, with the second level being - * chosen according to the state of the Num Lock (or Shift) modifiers. - * Another example is a type called "ONE_LEVEL", which is usually - * assigned to keys such as Escape; these have just one level and are - * not affected by the modifier state. Yet more common examples are - * "TWO_LEVEL" (with Shift choosing the second level), "ALPHABETIC" - * (where Caps Lock may also choose the second level), etc. - * - * Type definitions - * ---------------- - * Statements of the form: - * type "FOUR_LEVEL" { ... } - * - * The above would create a new type named "FOUR_LEVEL". - * The body of the definition may include statements of the following - * forms: - * - * - level_name statements (mandatory for each level in the type): - * level_name[Level1] = "Base"; - * - * Gives each level in this type a descriptive name. It isn't used - * for any thing. - * Note: A level may be specified as Level[1-8] or just a number (can - * be more than 8). - * - * - modifiers statement (mandatory, should be specified only once): - * modifiers = Shift+Lock+LevelThree; - * - * A mask of real and virtual modifiers. These are the only modifiers - * being considered when matching the modifier state against the type. - * The other modifiers, whether active or not, are masked out in the - * calculation. - * - * - map entry statements (should have at least as many mappings as there - * are levels in the type): - * map[Shift+LevelThree] = Level4; - * - * If the active modifiers, masked with the type's modifiers (as stated - * above), match (i.e. equal) the modifiers inside the map[] statement, - * then the level in the right hand side is chosen. For example, in the - * above, if in the current keyboard state the Shift and LevelThree - * modifiers are active, while the Lock modifier is not, then the - * keysym(s) in the 4th level of the group will be returned to the - * user. - * - * - preserve statements: - * map[Shift+Lock+LevelThree] = Level5; - * preserve[Shift+Lock+LevelThree] = Lock; - * - * When a map entry matches the active modifiers and the level it - * specified is chosen, then these modifiers are said to be "consumed"; - * for example, in a simple US keymap where the "g" key is assigned an - * ordinary ALPHABETIC key type, if the Lock (Caps Lock) modifier is - * active and the key is pressed, then a "G" keysym is produced (as - * opposed to lower-case "g"). This is because the type definition has - * a map entry like the following: - * map[Lock] = Level2; - * And as such the Lock modifier is consumed. This information is - * relevant for applications which further process the modifiers, - * since by then the consumed modifiers have already "done their part" - * and should be masked out. - * - * However, sometimes even if a modifier is actually used to choose - * the shift level (as Lock above), it should *not* be reported as - * consumed, for various reasons. In this case, a preserve[] statement - * can be used to augment the map entry. The modifiers inside the square - * brackets should match one of the map[] statements in the type. The - * right hand side should consists of modifiers from the left hand - * side; these modifiers are then "preserved" and not reported as - * consumed. - * - * Virtual modifier statements - * --------------------------- - * Statements of the form: - * virtual_modifiers LControl; - * - * Can appear in the xkb_types, xkb_compat, xkb_symbols sections. - * TODO - * - * Effect on keymap - * ---------------- - * After all of the xkb_types sections have been compiled, the following - * members of struct xkb_keymap are finalized: - * struct xkb_key_type *types; - * unsigned int num_types; - * char *types_section_name; - * TODO: virtual modifiers. - */ - enum type_field { TYPE_FIELD_MASK = (1 << 0), TYPE_FIELD_MAP = (1 << 1), -- 2.7.4