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.

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

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

README.md

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

The end user won't see this

HISTORY.md

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

LICENSE.md

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

readme.htm

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

welcome.htm

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

keyboardname.php

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