Step 2: Creating Additional Files for the Package
You should create some additional files for a package. Below are a list of the typical files that you would create for a package.
readme.htm
A short description of the package, its use restrictions, and what it includes. Try to keep the readme under 10 lines long. The readme is displayed in the package install dialog and should be an html file for optimal formatting.
Tip
As the package has not been installed at this stage, you should avoid using fonts that may only be available in the package. You may find that it is necessary to create an image of the text if you want the readme to be in a language not common to Windows.
Create the HTML file in any HTML editor.
Tip
If using Microsoft Word, choose HTML (clean) when saving to create a smaller file.
Note, if your HTML editor puts images into a subfolder, you will need to edit the HTML source so that all files are in the same folder -- the package builder will not maintain subfolders. You can easily edit the HTML source in Keyman Developer.
Also, if your welcome or readme files use embedded external images, stylesheets, javascript or other files, you will need to add these files to your package as well.
welcome.htm
When including an introductory help file in your package, you must name the file welcome.htm. This file will be detected during install and displayed (in a window roughly two thirds of the user's screen width) after the package install completes successfully. Make sure that you design your HTML file so that it can be resized to fit the user's screen - avoid extra wide tables or wide fixed width elements.
At this stage of the installation, fonts in the package have been installed, so you can include text that uses those fonts.
Welcome.htm will also be accessible after installation from Keyman Configuration under the Package Options menu, and from the Keyboard Help item and On Screen Keyboard toolbar button.
The intention of welcome.htm is to provide instructions on getting started with your keyboards.
Tip
Useful information to include in welcome.htm is:
key sequences - especially for characters that may not be immediately obvious.
names of fonts in the package.
names of keyboards in the package.
links to additional help on your website or more extensive documentation files in the package.
a link to an official distribution site for your package (even if it is the Tavultesoft website) - so that users know where to find the latest version of your package.
You should avoid including instructions for the use of Keyman Desktop itself - although a basic "click the Keyman icon and choose Quick French" would be helpful.
Tip
If you want links to your website to open in the user's preferred browser, preface the href link with "link:", e.g. "<a href="link:http://www.tavultesoft.com/">website</a>"
The "link:" will open the referred file in the default application - that is, a web browser for URLs and links, Notepad for .txt files, Adobe Reader for PDFs. You can use "link:" to open any of the files in the package, e.g. "link:docs.pdf" will open the file docs.pdf in Adobe Reader.
To save you the effort of writing a welcome and readme file for the Quick French example, we have placed some in the Samples/QFrench folder!
If you create documents in other formats, for example PDF or printable documentation, you should link to that in the welcome.htm.
Tip
You can include multiple "welcome.htm" files for different languages by appending a hyphen and the ISO 639-3 language code to the filename, for example welcome-fra.htm for French. This requires build 7.0.239.0 or later.
Fonts
A font is the single most important item to include with a keyboard - if the characters of the language you are supporting are not in fonts included with Windows. Installing fonts in Windows is tedious, so make sure that your users don't have to locate and install fonts themselves!
.TTF, .OTF, and .TTC fonts will be installed by the package installer, and uninstalled when the package is uninstalled. A list of the fonts installed is displayed in the Install Package dialog.
Keyboards
Add the .kmx compiled keyboard to the package. You can add multiple keyboards to the package.
Keyman Desktop Light will only allow the user to install two keyboards in a package. Which ones get installed must be chosen by the user when they install the package.
Tip
Don't forget to add the On Screen keyboard .KVK file associated with your keyboard to the package. KVK files are not compiled into the .KMX file -- although the .ICO/.BMP is.
Documentation
The two preferred documentation formats are HTML and PDF. You should avoid .DOC, .RTF, and other formats -- .DOC files in particular are not recommended due to the possibility of macro viruses.
Remember that HTML files can be displayed on any computer without additional software. PDF files require Adobe Reader or a compatible PDF viewer application. You may choose to include both and HTML documentation - PDF documents often print better than HTML documents.
Tip
If you use HTML, don't forget to also add all the included files such as images and stylesheets!
Splash Image
The splash image is a 140x250 pixel image that is displayed when the package is installed, at the left of the Package Install dialog. Including a splash image makes your package look more professional and polished, so a splash image is recommended!
User Interface Translation Files (7.0.239.0 or later)
You can include user interface translation files in your package - these will be automatically available once you install the package. The user interface files are called locale-xxx.xml, where xxx is the ISO639-3 code for the language. The basic English locale.xml file is available in [Program Files]\Tavultesoft\Keyman Developer 7.0\Redist\UI. Information on the locale.xml file format is available here.
