General
All the code contributions should be made through Bugzilla 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 are currently available. People are very welcome to contribute them. The only wish 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 (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.in).
4. The vendor element in base.xml.in 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.in, 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.in. 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 description. First - as the group name in the symbols file, second - as the translatable description in rules/base.xml.in. For the layout and default variants (including the variants not marked as default explicitly - but used as such because of the rules, see above), both description and group names are just the country name in English (for example, 'India' ). For non-default variants, the group name should be the country name and description (from base.xml.in) separated by the minus character (for example, 'Russia - Winkeys' ).
6. 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.
7. The authors are highly encouraged to use include statements wherever possible - it makes the resulting code more compact and easier to manage.
8. The key mappings have to be sorted alphabetically, by the keycode name.
9. 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).
-- Main.SergeyUdaltsov - 11 Jan 2009