www/ Software/ XKeyboardConfig/ Rules

General

All the code contributions should be made through GitLab on freedesktop.org. The component name is xkeyboard-config.

Types

There are no special rules for new types. They are going to be introduced very conservatively.

Geometries

There are relatively few geometry descriptions that are currently available. People are very welcome to contribute them. The only recommendation is to have them visually pleasant and precise.

Models

  1. Most of PC keyboard models should be defined by the following actions:

    • adding new xkb_symbols section to symbols/inet
    • extending $inetkbds list in rules/base.lists.part
    • adding new model section to rules/base.xml (in modelList)

  2. It is recommended to use {v}{m} pattern for the model name, where {v} is abbreviated vendor name. {m} is the model name. Recommended vendor abbreviations:

    • 'a4tech' - A4Tech
    • 'acer' - Acer
    • 'cherry' - Cherry
    • 'chicony' - Chicony
    • 'compaq' - Compaq
    • 'dell' - Dell
    • 'genius' - Genius
    • 'logi' - Logitech
    • 'microsoft' - Microsoft
    • 'samsung' - Samsung

  3. The name of xkb_symbols section (in symbols/inet) should be same as the new element in the $inetkbds list (in base.lists.part), same as name element (in base.xml).

  4. The vendor element in base.xml has to be specified.

  5. While defining xkb_symbols, it is strongly recommended to include (where applicable) shared sections for the media and navigation keys:

    • acpi_common
    • media_common
    • media_acpi_common
    • media_nav_acpi_common
    • media_nav_common
    • nav_common
    • nav_acpi_common

    These sections should be used even if not all of the keys specified in that section are present in the defined model. The syntax is standard:

    include "inet(media_common)"

    For example, if keys prev/next/play/stop have the mapping as defined in media_common (and other keys do not exist in the keyboard at all) - this is a good case for including entire media_common anyway

  6. The key mappings have to be sorted alphabetically, by the keycode name.

  7. If your keyboard model mapping is entirely covered by some existing section symbols/inet (some keycodes may be not actually used by your keyboard), do not create a new section consisting of a single include statement. Instead, create an alias in rules/base.m_s.part file and add it into rules/base.xml, as usual.

Layouts, Variants

  1. Every layout/variant has to define a single group: group 1. Layouts with multiple groups are not accepted.

  2. Every layout/variant has to be defined for some particular country, it should go into the file symbols/{cc} where {cc} is 2-letter country code from ISO 3166-1 alpha 2. The language-based layout/file names are not accepted. If several countries are using the same layout (for example, several countries share the same language), it should be fully defined for one country only - and included by reference into the files for other countries

  3. Every layout/variant has to be registered in rules/base.xml.

    There is only one exception: default variants. These are the variants which are either marked by "default" keyword in the symbols file (it is recommended to put them first and name them basic), or used as default because of some rule in the rules/base file (usually by modifying rules/base.ml_s.part component).

  4. There are popular variant names which are used by many countries, so they should be considered as first candidates (where applicable) for new variants. They are:

    • 'dvorak' - for national variants of the Dvorak layout
    • 'intl' - for variants suitable for multiple languages; usually - for the official state language(s) and some other frequently used foreign languages.
    • 'mac' - for variants specific to Macintosh keyboards
    • 'nodeadkeys' - for variants without dead keys (if the some other national variants are using them)
    • 'phonetic' - for variants which are using phonetic resemblance (usually - based on standard Americal layout)
    • 'sundeadkeys' - for variants with dead keys
    • 'us' - for variants which are using standard American layout as a basis, adding some national characters
    • 'winkeys' - for variants which are not standardized nationally but used in Microsoft Windows

  5. Every layout/variant has to provide a full description. First - as the group name in the symbols file, second - as the translatable description in rules/base.xml.

    The general approach for the descriptions is to follow "" or <"Language> ()" convention, for example: "English" or "Russian (legacy)". The usual practice is to use the country name as variation name, for example: "French (Canada)". The language has to be chosen as the one that is most frequently used with that layout/variant. That language has to be put first into the languageList attribute in base.xml (if the variant record does not have own languageList, the parent layout's languages are used).

  6. For the layouts/variants that are "exotic", it is recommended to use base.extras.xml instead of base.xml. The word "exotic" is used in statistical sense only.

    There is no formal definition of "exotic", because in most cases it is not possible to prove the actual number of users. There are several "usual suspects" for the "exotic" section:

    • The layouts for endangered/extinct languages/scripts. The statistics can be taken from http://www.ethnologue.com/. The potential candidates are languages with <100K speakers. If the number of speakers is <10K, the language most probably belongs to "extras"
    • The languages that are used most frequently with layouts made for other languages. If most of the texts using the language L1 are typed using layouts made for L2 (more popular), the own layout for L1 may be considered as exotic, even if the language L1 itself is popular. That is the a possible scenario for national minorities using the languages with the alphabet similar to the alphabet used by the language of the larger nation in the same country.
    • The exotic layouts for popular languages. If some relatively small group of people are using some variant suitable for their needs. Typical examples: variants for programmers, for typography, for particular group of sciences, for sacred texts etc.

    That's typical, but not the only possible scenarios for putting layout/variants into the "extras" section.

    The maintainer of xkeyboard-config typically questions the popularity of newly submitted layouts/variants. If no conclusive proof of number of users is provided, the layout can be put into the extras section (the maintainer reserves that right).

    Putting layout/variant into the extras section is just a representation of the fact that layout is not popular enough to be included into the main section. The GUI tools can use any approach to displaying (or not displaying) "extras" - this issue is out of scope of xkeyboard-config.

    It is recommended to put "exotic" variants into the end of the corresponding symbols file - after the delimiter line:

    // EXTRAS:

  7. The short description (shortDescription tag) is recommended for the indicators that use labels (as opposite to flags) for providing the user with the information about currently used layout/variant. This description is expected to contain the 2-letter ISO639-1 code (in lowercase) of the primary language - or, if no ISO639-1 exists for that language, it can be 3-letter code from ISO639-2 or ISO639-3. That code is made translatable, so that localized GUI can display some abbreviations suitable for the current locale. If some variant does not provide own short description, the short description from the parent layout is expected to be used.

  8. For layouts/variants using more than 2 shift levels, it is highly recommended to include level3(ralt_switch) symbols definition - for standard switching to levels 3 and 4 using AltGr key.

  9. The authors are highly encouraged to use include statements wherever possible - it makes the resulting code more compact and easier to manage.

  10. The key mappings have to be sorted alphabetically, by the keycode name.

  11. When you contribute model-specific layout/variant (for example, German for Macintosh), try to separate layout-specific mappings from the general ones, common to any national layout on that hardware. Usually, alphanumeric and punctuation key mappings are layout-specific, while navigation keys, functional keys, modifiers etc are model-specific. Consider putting model-specific keys mappings to the model-specific definitions (usually it is a section of symbols/inet file).

  12. It is recommended to use -U 7 rather than -u option with diff, that makes patches easier to apply (see https://bugs.freedesktop.org/show_bug.cgi?id=106261)