8 Package for Distribution

You want to make sure your keyboard is properly documented. You also want to include documentation files in your keyboard package.

References to hazargi are for demonstration purposes and are to be replaced with the name of your project wherever they occur when working on your own project.

Package - Export your On Screen keyboard

  • Open your Keyman Project and then open the .kmn file that goes with it.
  • Click on the On-Screen area tab
  • Click the Export button
  • Navigate to the source folder under your project name
  • Change Save as type to Image (*.png)
  • Type your project name (all lowercase) for the filename
  • Click Save 
  • Select One file per shift state
  • Click OK
If you end up changing your keyboard layout later, you'll then need to change the on-screen keyboard, and then re-export the images.

Package - Steps to document and package

  1. Open your project folder in Windows Explorer. You can access this from Keyman Developer as follows:
    1. Go to the open project tab (.kpj extension)
    2. Click on Packaging tab 
    3. Click the Options button to the far right of the named .kps file
    4. Select Open containing folder
    5. Go up one level to the named project folder
  2. Open Notepad (Windows key, type Notepad) and position it beside the open folder
  3. Drag README.md to Notepad
    1. Update description (e.g. Hazargi keyboard based on Persian)
    2. Save it
  4. Drag HISTORY.md to Notepad and make any needed changes
  5. Drag LICENSE.md to Notepad and make any needed changes
  6. Change to the source folder
  7. Drag readme.htm to Notepad and make any needed changes
    LICENSE.md will need copyright information updated: both date(s) and copyright holder (which must be the name of a person or the name of a legally recognized entity). If you specify the copyright information when using the "New Project" wizard, it will take care of putting the copyright information where it needs to go.
  8. Drag welcome.htm to Notepad
  9. Copy and paste this text under where it says: Insert keyboard layout…
    Copy to clipboard
    <p><b>Unshifted</b></p> <img src='hazargiU_.png' alt='Keyboard Layout'>
  10. Change hazargi to your keyboard name
  11. Paste again below, but change Unshifted to Shifted and hazargiU_.png to hazargiU_S.png, again replacing hazargi with your keyboard name. (Note: this matches the image file name)
  12. The hazargiU_SC.png file may be deleted as it only contains invisible characters.
    Repeat these steps for additional layers besides Unshifted and Shifted if you have them, such as RightAlt
  13. We can document the invisible characters in the first paragraph. E.g.: 
    Use Ctrl-Shift-1 for the zero-width joiner, …
  14. You can add a link to a pdf file in your welcome.htm file. E.g:
    Copy to clipboard
    <p>See <a href="file:my_doc.pdf">this document</a> for all the key combinations.</p>
  15. Test it now by double-clicking on welcome.htm
  16. Create a folder within the source folder called help
  17. Change to the help folder
  18. In Windows Explorer, Right-click and select New > Text Document
  19. Name the file hazargi.php (name of your project)
  20. Drag hazargi.php to Notepad
  21. Copy and paste the following into the new document
    HTML to copy and paste:
    Copy to clipboard
    <?php $pagename = 'Hazargi Keyboard Help'; $pagetitle = $pagename; // Header require_once('header.php'); ?> <p> Hazargi keyboard based on Persian. </p> <h1>Keyboard Layout</h1> <h2>Desktop Keyboard Layout</h2> <div id='osk' data-states='default shift shift-ctrl'> </div> <h2>Mobile/Tablet Keyboard Layout</h2> <p>Due to the size and number of keys, some characters are hidden in the long press. Press and hold on the key with a little dot on the top right to reveal them.</p> <div id='osk-phone' data-states='default shift numeric'> </div>
    1. Modify as needed, particularly the correct data-states
  22. In Keyman Developer, click on the open project tab (.kpj extension)
  23. Now click on the Packaging tab and then the named project .kps link
  24. Click Add (assuming you are on the Files tab) and add the two .png files we created above
  25. On-screen bitmaps should go in your source folder and also be added to the package
  26. Remember to finalize your Icon
  27. You may want to copy information from welcome.htm to your .php file, for example (from step 13): "Use Ctrl-Shift-1 for the zero-width joiner, ..."

Explanation of Files and What They are Used for

These are the files you need to edit outside of Developer:

  1. In the top-level folder (where your .kpj file is located)
    1. README.md
    2. HISTORY.md
    3. LICENSE.md
  2. In the source folder
    1. readme.htm
    2. welcome.htm 
  3. In the 'help' folder (must be created under the 'source' folder)
    1. keyboardname.php


This file gives an overview of the keyboard for someone looking at the keyboard source files

The end user won't see this


This file gives the history of changes to the keyboard

For a brand new keyboard, just use version 1.0

If you are preparing an existing keyboard for inclusion in the Keyman keyboards collection, you may want to move the history to this document, and your version number may be based on the version number in the existing keyboard


To be included in the Keyman keyboards collection, you need to release the keyboard under the MIT license.


This file is displayed when a user begins installation of the keyboard in a desktop environment

The purpose is to give a brief description of the keyboard

Don't confuse with README.md


This file needs to provide enough information so that the user can figure out how to use all the features of the keyboard

You can use keyboard images (.png files created from Keyman Developer) and/or typing charts

By default, Keyman Developer puts welcome.htm in the source folder, but it is also possible to create a welcome folder under the source folder and put welcome.htm there (along with any files it references)


This is a help file that will be shown on the Keyman.com website -- complete with images from the On Screen keyboard.

It needs to be in the help folder under the source folder

Often it is based on the welcome.htm file

Contributors to this page: dhigby .
Page last modified on Thursday February 27, 2020 01:48:44 GMT-0000 by dhigby.


Creative Commons License
All content on this LingTranSoft wiki are by SIL International are licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.