This documentation may be freely copied, but the copyright notice must not be altered or removed. No part of this documentation may be modified or edited. Tavultesoft holds no responsibility for any errors in this documentation or the use of its software.

© 1999 Marc Durdin / Tavultesoft. All rights reserved.

This documentation was created in MS Office 97. It is available online at http://www.tavultesoft.com/keyman/docs/.

Microsoft, Word for Windows, Access, and Excel are registered trademarks, and Windows is a trademark of Microsoft Corporation.

Ami Pro is a registered trademark of Lotus Corp.

Compaq is a registered trademark of Compaq Computer Corporation.

Any other trademarks referred to remain the property of their respective holders.

Welcome to the Tavultesoft Keyboard Manager. With the Tavultesoft Keyboard Manager (Keyman), it becomes practical to enter and edit documents that use languages and scripts other than English, for a wide variety of Windows application programs such as word processors, spreadsheets, databases, and desktop publishers.

Keyman has been developed with particular reference to the languages of South-East Asia and their scripts, but it can be readily adapted for many other languages. Keyman will allow you to mix many languages in one document, in your favorite word processor.

The most important feature of Keyman is the keyboard definition language that lets you develop your own keyboard layouts for just about any language.

This manual will guide you through the basics of using Keyman and writing keyboards for it, and explain the more advanced options that Keyman gives you. Reference information is given in the Reference Documentation.

Keyman 4.0 has been totally rewritten from the ground up to support Windows 95, 98 and NT 4. This means that this version of Keyman will not run under Windows 3.1 or Windows for Workgroups. There are a number of new features:

• Integration with the Windows 95/NT language interface. This means that you will select your languages from the task bar, as in standard Windows 95. It also means that your word processor will be able to automatically switch languages when you select a Keyman keyboard.
• Separation of the keyboard language from the main Keyman program. This means you don't have the overhead of an interpreter/compiler in the Keyman program, but rather compile the keyboards in a separate program.
• Shareware registration. Keyman 4.0 is not a freeware product, but is now shareware. The cost is US$30/license. See LICENSE.TXT for more details.

The following documents should be included with your Keyman distribution:

• User documentation (Keyman40.doc)
• Keyboard definition language reference (Km40lang.doc)
• Language code sheet (Langcode.doc)
• Keyboard template sheet (Keys.doc)
• Version information sheet (Version.txt)
• License information (License.txt)

Other documentation may become available and can be downloaded from http://www.tavultesoft.com/keyman/docs/.

The Tavultesoft website, http://www.tavultesoft.com/ has support information and contact details.

The evaluation version of Keyman is licensed for 30 days use only. If you choose not to register Keyman after that time, you must uninstall Keyman from your computer. The evaluation version is also restricted in the following ways:

• You cannot develop and compile your own keyboard layouts.

After you have registered Keyman, you will receive a registration code. From the Keyman window, select About and then click on Register to enter this registration code.

More details on Keyman registration can be found in LICENSE.TXT.

Chapter 2

The Keyman distribution should be a single executable file keyman40.exe. Run this program to install Keyman. The setup program is straightforward and you should have no troubles installing. Note: If you are installing Keyman on Windows NT, you should be logged in as Administrator, as Keyman will need to modify the registry to install.

After installation, you can start Keyman from the Start Menu. If you have the unregistered version, you will have to wait several seconds for the initial splash screen to disappear; otherwise, the window will only appear briefly before Keyman starts.

In a new installation, the main Keyman window should appear. If it doesn't, or you have already been using Keyman, you can make it appear in the following different ways:

1. Use your right mouse button on the Keyman icon in the task bar, which should look something like this: . A menu will appear; select Show Keyman.
2. When Keyman is already running, select the Keyman icon in the Start Menu to display the main window.

The main window will look like the picture below. If you are running on Windows NT, you will not have the Define Languages option. See the section Differences between 95 and NT for more information.

The two options, Start on boot and Hide on startup are fairly self-explanatory, and are the only options available in Keyman 4.0. If you click the Hide button, you can display Keyman with either of the two methods listed above.

The initial Keyman distribution that you received will not have any keyboards included. You can download Keyman keyboards from the Internet. Keyman 4.0 keyboards have the file extension .kmx. Once downloaded, you should click the Install Keyboard... button in Keyman and select the keyboard you downloaded. The following dialog box will appear.

Usually, you will want to copy the keyboard into the Keyman directory so that you won't accidentally delete it. If the language the keyboard is designed for is not already defined, you can define it in this dialog box; usually the given name is correct and you shouldn't modify it.

After you click OK, the keyboard will be installed ready for use.

Tavultesoft has a web page where keyboards have been collected and placed in one easy location: http://www.tavultesoft.com/keyman/keyboards/. It is a good idea to look there first if you are trying to find a keyboard. Other places where Keyman keyboards may be found are also listed on this page.

Using the Keyman keyboards in Windows is simple: simply click the Keyman icon in the task bar, and select the appropriate language.

The Keyman icon will be located at the bottom right of the screen, in the following Window (Note: the icons you see may be different to the ones here):

The Keyman icon changes to show your current Keyboard. The standard English icon is . Other languages may use a two letter code like this, or a different symbol altogether. When you left-click the icon, a menu will appear, looking like this:

Simply click the language you wish to use. You may need to select an appropriate font in your application as well.

You can also change keyboards by pressing Left Alt+Shift or Ctrl+Shift. You can select the hotkey combination from the standard Keyboard Control Panel applet. See Advanced options for more information on this.

There are several minor differences between Windows 95 and NT. The primary difference is that under NT, you cannot fully define your own languages. Keyman will let you type in those languages, but they will not be visible to Control Panel. This is unfortunately a limitation of the way in which Windows NT works. The second, minor, difference is that Microsoft-defined Windows NT keyboards have a .dll extension instead of a .kbd extension. Note that this does not refer to Keyman keyboards, which always have a .kmx extension.

Because of the way Keyman integrates into the Windows language interface, you can also use the Windows 95 Keyboard Control Panel applet to change many of your keyboard options. The most important option is the ability to change the language a Keyman keyboard is associated with. To do this, install the keyboard in the normal way, and then in the Keyboard Control Panel, select Language Properties to change the default keyboard associations. However this is not usually recommended, as it will reduce the usefulness of the Windows multi-language interface.

Chapter 3

There are two main steps to writing a keyboard program. The first step is to arrange the layout of the characters on the keyboard. Then, you enter the keyboard program according to your layout.

This chapter shows you the basic steps in writing a keyboard program; we will be using a simplified French keyboard as an example to follow through.

It is important to remember that a Keyman keyboard has a source file and a compiled file. The source file has the extension .kmn. The compiled file has the extension .kmx. You cannot installed a source file into Keyman 4.0, and you cannot edit a compiled file. See the section Compiling Keyboards for information on how to convert a source file into a compiled file.

1. Even if you have some experience in writing CC tables, you should still read this chapter, as it shows you the basic steps and structure of a keyboard file, which is slightly different to CC tables. However, your experience should help you learn the format more quickly.

You will be designing a simplified French keyboard for people who don’t know the standard French keyboard layout; you will have to go through both steps mentioned above. This French keyboard (Quick French) doesn’t follow the standard French layout; instead, it uses a basic English keyboard with some deadkeys to define vowel diacritics and other French characters needed.

You will need to know the character codes in the font that goes with this keyboard (for Quick French, Times New Roman and Arial work fine); the characters you will be using may be upper-ascii. If you do not have a font for the language you will be working with, you will need to obtain or create one; Keyman does not do anything about fonts.

First of all, you have to know what codes are used for the characters you are mapping with your keyboard program. (You can use the Character Map application that is provided with Windows to help you find these codes.)

For the Quick French keyboard, you will need all the vowels with different diacritics, some French symbols, and c-cedilla (upper and lower case); the codes needed are listed below, along with some others that are used by other European languages:

Now that you know the character codes needed, you must decide how you want to key them. For the purposes of this example, the codes will be keyed according to the following table:

The basic design of the keyboard is done. There will be more to come, but first you are going to write the first version of the keyboard program.

Before you start this section, start a text editor (such as Windows Notepad), and begin editing a new file. The Tavultesoft Integrated Keyboard Editor has been designed for this purpose and works closely with Keyman (see chapter 6). (DOS text editors are okay, too, but not quite as convenient.)

A keyboard program is divided into two sections: the header, and the rules. The header lets you define the name of the keyboard, hotkeys, and other general settings. The rules are divided into groups where you define how the keyboard responds to keystrokes. Every keyboard program must have both of these sections. A keyboard program normally has the extension .KMN and is an ANSI text file.

1. A keyboard program is in ANSI text format, not ASCII text format, because Windows uses the ANSI character set. If you are using a DOS text editor, you must remember that the characters you see on the screen aren’t necessarily the same as the ones you’d see if you used a Windows text editor, such as Notepad.

A Keyboard Program can have a comment at any point. The comment is identified by a letter ‘c’, with a space on either side (unless the comment is at the start of the line, in which case you only need a space on the right). The end of the line marks the end of the comment.

Blank lines are ignored by Keyman; you can have them anywhere in a keyboard program.

Examples:

It is a good idea to use comments to document your keyboard program. They will help you remember why you did something in a particular way, and they will also help other people understand the program.

Add some comments to the start of the Quick French keyboard program, in your text editor, describing who wrote it, when it was written, and anything else needed, such as instructions on how to use the keyboard (from the tables above). You could even add a copyright notice, for a keyboard that uses complex algorithms, for example.

Example:

The header is easy to create; it consists of statements that help Keyman identify the keyboard and set default options for it. Each statement in the header must be on a separate line and is usually written with capital letters, although that is not required. Keeping the statements in the header in upper case helps you identify them easily, and keeps them consistent with keyboard programs other people might write.

You can give your keyboard program a different name, if you wish.

The Quick French keyboard is intended to be used in Keyman 4.0. Therefore, add the following line to your program:

Those five statements are the only ones required in the header. You can add comments to the ends of the statements to help other people understand them.

Your Quick French keyboard should so far look like this:

Before we start on the rules, we will define some terms:

The simplest rule you can have tells Keyman to convert one key into another. A rule of this sort is represented in Keyman in the following way:

These different ways of representing a single character follow the SIL-CC conventions. The first three ways are the most often used, and octal representation is rarely used. Multiple characters (a string) can be represented in quotes simply by having more than one character in the string. You can have any combination of these representations in a rule, with spaces between them.

For example, to convert the key "a" to the character "z", you would include the following line in your keyboard program:

Or, to convert "?" to "Hello World!", you would have this line:

You can use either single or double quotes.

A use of the decimal representation is, for example, in the British English keyboard, where the hash sign (#) is converted into a pounds sign (£, decimal code 163):

Often you will want to know the previous characters that have been typed and translate the keystrokes accordingly. Keyman remembers the characters that came out on the screen, and not the actual keys typed. It is important to remember this, because some programs such as SIL’s Keyswap (for DOS) work with sequences of keys rather than characters. The characters that came out on the screen are called the context. The context is represented in a rule to the left of the keystroke, before the plus sign. For example,

In this example, if you type a "^" (caret) followed by the letter "e", it will come out with the European letter "ê". The caret is the context, the letter "e" is the key, and the letter "ê" is the output.

You can add some of the rules to the Quick French keyboard program now. Add the rules for all the "a"-related characters; you will quickly see how many rules it would require for a complex keyboard. Another example rule for the Quick French keyboard program is:

In this example, Keyman will create a store called "lwrvowel", and make the contents of the store equal to "aeiou".

For example, you could have the following:

This example would convert any of the characters "!", ".", and "?" to a "GO!". (This example is actually not very useful.)

This rule would convert all lower case vowels to upper case. Or,

This one capitalizes any lower-case vowel following a full-stop, question, or exclamation mark.

The Quick French example keyboard can make use of this quite easily; an example will be shown for "^" and a vowel:

So far, your Quick French keyboard should look like this:

Before you go any further, you should test your keyboard. Save your file, and start a command prompt. Type the following command from the Keyman directory to compile your keyboard:

If any errors occur, refer to the section Compiling Keyboards.

After this, open Keyman and install the keyboard. You should be able to use the keyboard in a word processor now.

Load a text-editor or word-processor, such as Notepad, or WinWord. Select the Quick French keyboard and try it out. Type sequences like ^a^e’a’e. Once you are sure that that is all right, then try typing something like this: "A problem in the keyboard." (Include the quotes.) You can see the problem: when you type something in quotes, if the letter after the quote character is a vowel, it will be converted.

Open up your keyboard program again. The problem exists with two lines; both of the lines regarding quotes will need to be changed. But first you have to decide how you are going to represent the quote character when it is to be used as a quote character. Probably the easiest way is just to type it twice.

The line you need to add is this; this will fix it for double quotes; add another line to fix it for single quotes.

Another thing that would be nice is to make the diacritics as deadkeys. A deadkey is a key that does not come out on the screen when it is pressed, but is still remembered in the context. Many European keyboards use deadkeys.

We will show you the line needed; you will need to remove the old rule to do with carets and explain it for the caret (^) character:

You will want to add the deadkey rules for all the other characters; don’t forget to use a different deadkey identifying number for each one. You will also need to modify the quote modification statements talked about above, to work with the deadkey better; it becomes simpler, as shown below:

You should add this sort of statement for all the diacritics, in case you wish to use the original character.

There are some other characters we haven’t got support for yet: «, », ç, and Ç. We decided to represent the "«" and "»" characters with double less-than and double more-than symbols. You should be able to add rules for these, as well as for the "ç" and "Ç" symbols.

But what if someone wanted to type "<<<<<<< *** >>>>>>>", for instance, as a divider to a section of a book. They wouldn’t want it to come out as "«««< *** »»»>". So we will make use of a deadkey to have it come out correctly, as shown below:

You should be able to see what this does. Test your keyboard again; there should not be any more problems. You have completed the Keyman keyboard tutorial.

The following chapter will explain some of the more advanced features of the Keyman keyboard language; you could use them to extend this keyboard.

Chapter 4

This chapter will build on what you have already learnt from chapter 4; it will be assumed that you understand the basic Keyman keyboard program format.

The following subjects will be discussed in this chapter:

• Compiling keyboards
• Multiple groups
• Constraints
• Groups without the "using keys" keywords
• Virtual keys
• Other features

In chapter 4, you learnt how to create a file with one group. Multiple groups can be useful for doing further processing such as changing characters in certain contexts, or, as is done for some South-East Asian languages, syllable splitting.

Any output in a group will affect groups called by it, as well as groups after it. The current context will be modified to add the changes made by a group, before returning to the previous group, or jumping to another one.

The rules are represented in the following way:

Several of the example keyboards on the Tavultesoft website illustrate the usage of these statements and rules. To sum up:

A constraint rule can just be something like the following line:

This would restrict two vowels from being typed in a row; the second key would just be ignored.

With what you have learnt so far, any letter, number, or punctuation mark can be identified as a key in a rule. However, you cannot test the Ctrl and Alt states of these keys; with some keyboards, it is necessary to do so.

Virtual keys allow you to do that. A virtual key keyword can identify almost any key on the keyboard; a few specialized ones are either reserved or unable to be used.

Virtual keys are allowed only in the key section of a rule, not in the context or the output. A virtual key is identified by an opening bracket character (‘[’). It ends at a closing bracket character (‘]’). Inside the brackets, you can have a combination of shift-key codes and the actual virtual key, which is identified by a "K_" at the start of the keyword.

The keyboard shown further on gives the virtual keys for all keys on the standard US 101 key keyboard. (Note: The arrangement may not be identical to your keyboard.)

1. You must not use virtual keys in the output. Keyman will recognize them, but output will be garbled. This version of Keyman does not support virtual keys in the output.

For example, to test for the scroll lock key, you would have the following line:

If you want to test for a key that is used with shift, ctrl, alt, or caps lock, then you would proceed it with one of the following keywords:

So, if you wanted to test for Right alt + the letter "e", you would have the following line:

This version of Keyman does not let you use stores for virtual keys.

There are three optional header statements that Keyman recognizes, all working with caps lock.

When you are making your keyboard, you may find that some lines are very long and are hard to read if made shorter. Keyman has a way of getting around this: by putting a backslash (\) on the very end of the line, Keyman is told that the line should be joined with the next one. You can do this for multiple lines if necessary, up to 1K (about 1000 characters) long. The backslash must come after comments if you have them. For example,