decode_vkb
==========

decode_vkb is a perl script to decode binary virtual keyboard definition
files from Nokia n800 Internet tablet and other Maemo devices to a XML
format for editing them. The generated XML-files can be encoded back to 
binary .vkb format using gen_vkb utility from Nokia.

(C) 2007 Kimmo Jukarainen <kimju-2007@inside.org>

This program is licensed under GPLv2. See LICENSE.txt

Status, BUGS and known (mis)features:
=====================================

Currently the script can decode all .vkb files from the current
n800 software image (4.2007.26-8) to XML-files that gen_vkb can
encode back to identical original files.

* Except: fr_FR
  For some reason this .vkb includes "numeric" flag for it's first
  keyboard section. The decoder script notices the flag and adds
  "numeric"-attribute to corresponding <keyboard>-tag in the XML.

  The gen_vkb seems to accept this attribute (at least it doesn't
  complain about it like it does for other unknown attributes), but
  it still writes numeric as zero in generated vkb.

  Probably I still have wrong value for the attribute, but I can't
  figure out the correct syntax. Or there might be a bug in gen_vkb
  utility.

* Of the layout types, only NORMAL and THUMB can be found in
  official .vkbs. The rest are tested to encode/decode back to
  same, but no guarantees.

* Normal keys (type 0x00) are supported.

* Sliding keys (type 0x01) are supported. They are created by
  placing several <slide> tags inside a <key type="SLIDE"></key>
  block.

* Multiple keys (type 0x04) are supported, but are not present in
  any official .vkbs so support is untested. 
  Multiple keys are created by placing several <key> tags inside 
  a <multiple></multiple> block.

* Modifier keys (type 0x02) are not supported. A <key> with
  modifier="MODIFIER" attribute seems to generate .vkb code just like
  normal keys (except for the type), but this doesn't seem to be right
  as there is no information about the modifier itself. See below
  for raw keys.

* Raw keys with scancodes are not supported. A <key> with both
  raw="RAW" and scancode="xx" attributes generates .vkb code with
  scancodes, but the generated attribute field in vkb doesn't reflect
  this in any way, even when file format specification says that there
  should be raw-flag in attributes. So there's no way to be able to
  decode the generated file correctly.

  Maybe this is a bug in gen_vkb, or maybe raw should be used together 
  with some other option, like for example the modifier key?


Version history:
================
* Version: 0.01 - 2007-08-21
  - initial release


Used documentation sources:
===========================

* "How to extend Hildon Input Methods"
  <http://maemo.org/development/documentation/how-tos/3-x/howto_him_bora.html>
- Partial documentation for the XML-format.

* Nokia's XML -> .vkb generator
  <http://repository.maemo.org/pool/scirocco/non-free/libi/libimlayouts/>
- Generator package contains partial documentation for the .vkb format
  in "/usr/share/libimlayouts/fileformat.html":
    "OSSO Virtual Keyboard File Format Specification", 
    "version 0.53, 31.01.2006"
- some XML tag names and attributes were guessed by running 
  "strings gen_vkb"
- The gen_vkb can be used without full maemo development environment, just
  extract both gen_vkb and libimlayouts.so.* from the .debs (ar x foo.deb;
  tar xzvf data.tar.gz) and then running it like this:
    LD_PRELOAD=./libimlayouts.so.0.0.0 ./gen_vkb fi_FI.xml

* Czech keyboard
  <http://upir.cz/maemo/>
  <http://upir.cz/maemo/dists/bora/czech/source/czkeyboard_0.1-1.tar.gz>
- The source package contains partially reverse engineered documentation
  for the .vkb format in "doc/vkb-format-v2". Buggy, but still useful
  addition.