docs(linux): document how to migrate from kmfl to keyman/create .kmp files for Keyman out of .kmn used with kmfl

[ermshiperete]

We should document somewhere how kmfl users can get their keyboards migrated to the .kmp format used by Keyman. Some of them have custom keyboards that are not available on keyman.com.

A starting point would be this:

You'll need node.js, version 18.0 or later. On Ubuntu 24.04 this can be installed with:

sudo apt install npm

For older Ubuntu versions consult the nodejs.org website.

npm install -g @keymanapp/kmc

Create a file mykeyboard.kpj:

<KeymanDeveloperProject>
  <Options>
    <Version>2.0</Version>
  </Options>
</KeymanDeveloperProject>

Create a file source/mykeyboard.kps:

<Package>
  <Info>
    <Name>MyKeyboard</Name>
  </Info>
  <Files>
    <File>
      <Name>../build/mykeyboard.kmx</Name>
    </File>
  </Files>
  <Keyboards>
    <Keyboard>
      <Name>MyKeyboard</Name>
      <ID>mykeyboard</ID>
    </Keyboard>
  </Keyboards>
</Package>

Move your .kmn file to source/mykeyboard.kmn.

Build with:

kmc build mykeyboard.kpj

In the current version (17.0.326) this will fail with
TypeError: Cannot read properties of undefined (reading 'description'),
but it will already have created the .kmp file in the build
subdirectory. You can install the .kmp file with:

km-package-install -f build/mykeyboard.kmp

(To properly do this without an error, you'll have to add some additional
fields to the .kps file. It's easiest to let the kmconvert tool generate
a template which will contain all necessary fields:

kmconvert template -id mykeyboard

Unfortunately this tools isn't available for Linux yet.)

References

• bug(developer): kmc: TypeError: Cannot read properties of undefined (reading 'description') #11856
• feat(developer): convert kmconvert (Delphi) to node, kmc generate #10509

[ermshiperete]

Fixed by keymanapp/help.keyman.com#1335