Difference between revisions of "Building an XKB Keyboard"

From LSDevLinux
Jump to: navigation, search
(Try it out [Finally!])
(A First Look Around: Fix external link formatting)
Line 9: Line 9:
 
If you're reading this, I hope you know that typing the key gives you the character in the bottom-left (a) and holding Shift when typing the letter gives you (A).  The second column is normally accessed using the Right Alt (AltGr) button or Ctrl+Alt.  In this example, holding AltGr and then typing the letter gives you (ɛ) and holding both Shift and AltGr when typing gives you (Ɛ).
 
If you're reading this, I hope you know that typing the key gives you the character in the bottom-left (a) and holding Shift when typing the letter gives you (A).  The second column is normally accessed using the Right Alt (AltGr) button or Ctrl+Alt.  In this example, holding AltGr and then typing the letter gives you (ɛ) and holding both Shift and AltGr when typing gives you (Ɛ).
  
[[http://simos.info/blog/wp-content/uploads/2008/10/levels.png Levels]]
+
* [http://simos.info/blog/wp-content/uploads/2008/10/levels.png Levels]
[http://simos.info/blog/archives/747 Simos' Blog]
+
* [http://simos.info/blog/archives/747 Simos' Blog]
  
 
There are 2 important files in this section,  
 
There are 2 important files in this section,  
 
The first> is in the symbols folder ('''usr\share\x11\xkb\symbols\''') and named with a 2-letter code.  This is where your keyboard will go.
 
The first> is in the symbols folder ('''usr\share\x11\xkb\symbols\''') and named with a 2-letter code.  This is where your keyboard will go.
Ths second file is '''usr\share\x11\xkb\rules\evdev.xml''', and contains sort of a table of contents in XML format.
+
This second file is '''usr\share\x11\xkb\rules\evdev.xml''', and contains sort of a table of contents in XML format.
 
    
 
    
# You'll need root (admin) rights to do this: so I recommend opening a terminal and typing "sudo nautilus".  Once you type the password, you will recieve a window with root priveliges.
+
# You'll need root (admin) rights to do this: so I recommend opening a terminal and typing "sudo nautilus".  Once you type the password, you will receive a window with root privileges.
 
# Browse to '''usr\share\x11\xkb\symbols'''.   
 
# Browse to '''usr\share\x11\xkb\symbols'''.   
# Find the file named with the [2-letter code|http://en.wikipedia.org/wiki/ISO_3166-1] of your country. (If it does not exist, duplicate a country with keyboards similar to your own and rename it to your country code.  (ex: cm, us, cn) )  
+
# Find the file named with the [http://en.wikipedia.org/wiki/ISO_3166-1 2-letter code] of your country. (If it does not exist, duplicate a country with keyboards similar to your own and rename it to your country code.  (ex: cm, us, cn) )  
 
# Open some of the country files and get a feel for how they're set up.  Most country files will have multiple entries like the one below:
 
# Open some of the country files and get a feel for how they're set up.  Most country files will have multiple entries like the one below:
  

Revision as of 08:56, 23 June 2011

A large portion of this information comes from the thorough, yet out of date: Unreliable Guide to XKB Configuration

A First Look Around

We must first determine if your country is on the keyboard list. Under the Tools menu, click Settings, then Keyboard. Click Add Layout. You will be presented with a list of countries. Browse the list and try to find your country, or at least a keyboard similar to the custom one you envision. You'll see keys that have up to 4 characters.

|A Ɛ|
|a ɛ|

If you're reading this, I hope you know that typing the key gives you the character in the bottom-left (a) and holding Shift when typing the letter gives you (A). The second column is normally accessed using the Right Alt (AltGr) button or Ctrl+Alt. In this example, holding AltGr and then typing the letter gives you (ɛ) and holding both Shift and AltGr when typing gives you (Ɛ).

There are 2 important files in this section, The first> is in the symbols folder (usr\share\x11\xkb\symbols\) and named with a 2-letter code. This is where your keyboard will go. This second file is usr\share\x11\xkb\rules\evdev.xml, and contains sort of a table of contents in XML format.

  1. You'll need root (admin) rights to do this: so I recommend opening a terminal and typing "sudo nautilus". Once you type the password, you will receive a window with root privileges.
  2. Browse to usr\share\x11\xkb\symbols.
  3. Find the file named with the 2-letter code of your country. (If it does not exist, duplicate a country with keyboards similar to your own and rename it to your country code. (ex: cm, us, cn) )
  4. Open some of the country files and get a feel for how they're set up. Most country files will have multiple entries like the one below:
xkb_symbols "qwerty"
{
	name[Group1] = "Cameroon Languages Qwerty";
	include "level3(ralt_switch)"
	include "cm(basic)"
	key <AB01> { [              z,              Z,          U2026,          U2020 ] };
...
	key <AC01> { [              a,              A,          U025B,          U0190 ] };
...
	key <TLDE> { [          U030D,          U0303,          U0060,          U007E ] };
};

Anatomy of an XKB symbols module

The Header

xkb_symbols "qwerty"
{
	name[Group1] = "Cameroon Languages Qwerty";
	include "level3(ralt_switch)"
	include "cm(basic)"
  1. The title beside xkb_symbols is the title you will use to reference this keyboard in the config files. make it short and with no spaces. You should use the standard titles like basic, dvorak, or nodeadkeys if applicable. More standard titles here here in Layouts/Variants, section 4.
  2. Without going too far into groups, name[group1] contains, functionally, the name of your Keyboard. Accepted layouts can have only one group.
  3. Includes are imports of modules from other sections or other files in the symbols folder. They are in the format filename(module), so level3(ralt_switch) points to the file "/usr/share/X11/xkb/symbols/level3" and the module "ralt_switch". If a key is redefined by an include module, it may be important whether the import comes at the beginning or the end of the module.

The Body

 key <AB01> { [              z,             Z,          U2026,          U2020 ] };
 key <AC01> { [              a,              A,          U025B,          U0190 ] };
 key <TLDE> { [          U030D,          U0303,          U0060,          U007E ] };
};
  • AB01 is the reference to the key that is being defined. AB refers to the row, and 01 refers to a specific key on that row. You will probably want to print out this image to use as a reference. Always start counting from the left.
  • z is the unshifted character.
  • Z is the shifted character.
  • U2026 is the Unicode value for the AltGr character.
  • U2020 is the Unicode value for the Shifted AltGr Character.

Keyboard Layout Editor

There is a utility to help you create your keyboard visually. This wonderful python tool works very well with the built-in character map to build a draft of your keyboard. I used it in a workshop setting on the projector to drag-and-drop each character into place. There are 3 things that make this draft-quality for me:

  1. The file that it creates ignores any other keyboards in the file, and will create a file containing only your keyboard. Therefore, be careful that you create a temporary file and use a copy/paste workflow to move the data for testing.
  2. I don't like the way that it converts characters to their named equivalents. I would prefer that it used the Unicode value and put the Unicode name in a comment. I want to be sure that I'm using the correct letters, and names like "Armenian single guillemet" are a little distracting.
  3. It removes comments when I open a pre-made file.

Doing it manually

You may, like me, choose to construct this file manually. for one keyboard, I started with a Microsoft Keyboard Layout Creator (KLC) source file in a text editor and used regular expressions to "massage" the data into a usable format.

From an MSKLC source file and this table, you should be able to glean all information needed to build your file.

Special Features

AltGr and "Special" Shift Key

The level3 file contains all sorts of goodies that can be imported into your file. One of the most useful is Right Alt Switch (ralt_switch). This is the most common way of accessing special characters and allows you to hold the AltGr (Right Alternate) and Shift keys to get to the characters in the second column of you keyboard layout.

xkb_symbols "ralt_switch" {
 key <RALT> {
   type[Group1]="ONE_LEVEL",
   symbols[Group1] = [ ISO_Level3_Shift ]
   };
 modifier_map Mod5   { ISO_Level3_Shift };
};

Basically, it redefines your Right Alt Key to change levels. Whenever held, you get the second coumn of characters. It can be added to your keyboard with the line below.

include "level3(ralt_switch)" 

The AltGr key is often awkward for certain combinations, especially for the letters nearest it. We decided a long time ago that the semicolon key was well located and infrequently used. Therefore, we took it over for accessing our special characters. This way, typing ";a" would give us ɛ just as AltGr + A. It will display the requested character, and then the keyboard returns to normal. The code below redefines the semicolon key as a "latch" rather than a "shift", meaning that once pressed, it changes the level until the next letter is pressed. You do not need to hold the key down like the AltGr key.

partial modifier_keys

xkb_symbols "semicolon_switch" {
 key <AC10> {
 symbols[Group1] = [ ISO_Level3_Latch,	colon,	semicolon,	colon ]};
 modifier_map Mod5	{ ISO_Level3_Latch };
};

If you create code like this, you can add it at the bottom of your country file and include it in your keyboard with a reference like:

include "cm(semicolon_switch)"

I recommend that you put this include at the bottom of the module. I defined semicolon normally in the body of the module, then added the include at the end. This way, if someone does not like your special key method, they only have to comment out one line and continue using the AltGr method.

Testing the XKB

Add entries to evdev.xml

To test your keyboard, you must add your keyboard to the evdev.xml file. As before, I suggest running the following command to get a root window:

sudo nautilus

Browse to usr\share\x11\xkb\rules\evdev.xml and find the place where your country fits alphabetically.

  • If you are only adding a variant keyboard to your country, you must add from <variant> to </variant>.

Example:

<variant>
 <configItem>
  <name>ike</name>
  <description>Inuktitut</description>
  <languageList><iso639Id>iku</iso639Id></languageList>
 </configItem>
</variant>
  • If you are adding a new country, you must add a new section from <layout> to </layout>.

Example:

<layout>
 <configItem>
  <name>bg</name>
   <shortDescription>Bgr</shortDescription>
   <description>Bulgaria</description>
   <languageList><iso639Id>bul</iso639Id></languageList>
 </configItem>
 <variantList>
  <variant>
   <configItem>
    <name>phonetic</name>
    <description>Traditional phonetic</description>
   </configItem>
  </variant>
 </variantList>
 <variantList>
  <variant>
   <configItem>
    <name>bas_phonetic</name>
    <description>New phonetic</description>
   </configItem>
  </variant>
 </variantList>
</layout>

Be EXTREMELY careful to maintain the spacing and structure.

Try it out [Finally!]

To test your keyboard, you now must restart X server. The easiest way to do this is to log off and log back on. You can then go to Tools>Settings>Keyboard>Add Layout, then choose your country and layout. You will find when you make your first mistake that XKB doesn't really debug your script files in any meaningful manner, it just "plunks" when you login and gives you a generic error.