Creating A New Keyboard Layout

Creating a new keyboard layout for production is a relatively straightforward, but multi-staged process. A number of components need to be affected to get a given keyboard layout to production.

Creating the layout diagram

Initial feedback

Once a request of a layout is proposed, one should start looking at possible candidate layouts. Unless there is a particular preference for any layout from the deployment, it makes sense to go with the government approved layout for that region. However, government mandated standard layouts are often quite outdated, and may need tweaks and extensions, and it is best to gather feedback from the deployment, as well as native speakers from the region.

Creating the SVG image

Once an initial idea has been formed, a SVG image file for the layout has to be created. The SVG layouts for the existing layouts are maintained in a Git repository named projects/keyboard-layouts. Take one of the images as the starting point, and using Inkscape, modify it according to the specifications of the new layout. It is a good idea to utilize the layers feature in Inkscape to keep your work organised (for example, if it is a multi-script layout, the standard QWERTY characters should be in one layer, and the other characters in another).

Take care not to make the layout too crowded - the keys on the physical keyboard are quite small, and it can be difficult to print complicated or too many characters on a single key.

Final round of feedback and production approval

Once a layout image has been done, export a PNG or a PDF and send it to the deployment team and the native language community once again for feedback. There might be a few such feedback cycles after which the final layout is agreed upon. After a final layout has been agreed upon, you will need to send a PDF to manufacturing to see if its feasible for printing, and a few samples of may be produced.

Adding to the wiki

Add the final image to the wiki, along with the relevant snippet from the XKB data, as well as a link to the .ka file produced for OFW (the last two items are described below).

The XKB data

We currently use XKB for handling keyboard input. Using SCIM is also possible for F-11 based builds, but most of the documentation, etc are based on the assumption that XKB is being used. The XKB data files live in the xkeyboard-config package in Fedora.

For various reasons (which include temporary ugly hacks which won't go upstream), we use our own fork of the xkeyboard-config package and we maintain the source tree of this in the Git repository projects/keyboard-data.

Writing the XKB definition for a new layout is pretty straightforward. A tutorial can be found here. Once the XKB data has been finalized, add it to git and use a tag (eg: azerty-1) to identify the final version of the data file.

Keyboard ASCII Map for OFW

Generating the .ka file

If the layout is a single script layout with no QWERTY alternative (eg: the AZERTY layout, or the Spanish layout), you will need to create a Keyboard ASCII Map for Open Firmware. To do this, you will need the scripts in projects/xkb2ofw. The syntax for running the script is

parsexkb.py layout variant git_tag distro

So, for example, if the new layout is fr(olpc) and is tagged in Git as azerty-v1 and is for the distribution F-11, the command will be

parsexkb.py fr olpc azerty-v1 F-11

A file called azerty-v1.ka will be generated.

The script will warn you of possible problems with the layout, such as duplicate locations for ASCII characters or missing ASCII characters. Be sure to look carefully at such warnings and understand the cause at the keyboard layout level, as they often reveal genuine layout issues.

Testing the .ka file

The .ka files are kept in the Git repository projects/ofw-ka-files. The repository also contains a script named setka.fth. To test out the .ka file, edit the setka.fth file appropriately (you will need to add a line after line #28), and put it, along with the .ka file in a USB stick. Load the script and the .ka file from the OFW prompt with the command:

fload setka.fth azerty-1

(where azerty-1 refers to the entry for the newly created .ka file.)