TealScript User's Manual

By Vince Lee, Tex Tennison, and Amanda Epume
Program Version 1.70
Last Updated: Jun 15, 1999

Description

Thank you for trying TealScript. This program is a replacement for the graffiti text recognition system. Unlike the graffiti recognition system that comes standard on all Palm organizers, TealScript is configurable, allowing you to train it to recognize your own distinct handwriting and reduce common errors. With a little practice, you can also tweak it to add your own alternative strokes or correctly recognize strokes that might confuse the built-in recognition.

Installing

This archive contains the files:

TEALSCRP.DOC
This document in text format
TEALSCRP.HTM
This document in HTML format
SCRPDOC.PRC
This document in PalmPilot document format
TEALSCRP.PRC
The TealScript program file
PROFILE.PDB
A default stroke profile file
RESCRIPT.PRC
An optional Hack App to reinstall TealScript after a system reset
HACKMSTR.PRC
An optional manager program for ReScript
REGISTER.HTM
TealPoint Registration form in HTML format
REGISTER.DOC
TealPoint Registration form in text format
Use the Pilot installer to install the program file TEALSCRP.PRC and the stroke profile PROFILE.PDB. This manual is provided in this archive as the PalmPilot document SCRPDOC.PRC, which you may also install to view with TEALDOC.

After a crash or system reset, TealScript normally need to be run again to restart recognition. You can automate this by installing Rescript and it's manager program HackMaster, but this is optional and may not work if you are running other programs that perform certain functions after a system reset. Use the PalmPilot installer to install RESCRIPT.PRC and HACKMSTR.PRC. Then run the hackmaster program on the PalmPilot and check on the checkbox next to ReScript. TealScript will be started the first time after you leave Hackmaster.

Instructions on how to use the PalmPilot installer are in the PalmPilot Handbook that came with your Pilot, PalmPilot, or WorkPad.

WARNING: Before updating or deleting TealScript, you MUST turn off global recognition on any previously-installed versions or active profiles or your Pilot will crash. If you are updating to a new version, delete the old version first, remembering to backup your old profile first if you have made any changes from the default profile.

Likewise, HackMaster hacks like ReScript will also need to be turned off before deleting or reinstalling.

Using the Program

After installing, begin using TealScript by starting it from the Palm application launcher. You'll start on the main control screen.

Main Control Screen

TealScript recognizes strokes in graffiti area by comparing them to entries in the current stroke profile. On the main control screen, you can set various options, and set or modify the current stroke profile.

Options:

Enable Globally
Turn on TealScript stroke recognition using the current profile. When this option is not selected, the default Palm graffiti recognition stays in effect outside TealScript. NOTE: The recognition handler will not survive a warm boot. Restart TealScript after after any system resets.
Allow Alternate Strokes
Recognize as valid strokes entries in the current profile marked as "alternates".
Beep on Error
Play the system error sound when a stroke is entered that does not match any entry in the current profile.
Click on entry (slows recognition)
Play the system click sound when a valid stroke is entered. Note that that this option will slightly slow down text entry recognition.
On up stroke...
Set feature to activate when a stroke is done from the graffiti area to the top of the screen. This menu takes place of the system preferences pen options when TealScript is active. Note that for pilot OS versions prior to 3.0, some features, such as beaming will have no effect.
Maintain Statistics
Maintain and update statistics whenever you enter a keystroke
EZ Capitalize on alpha-num border
This option creates a third drawing region between the number and text regions. Enter letters drawn on this line will be automatically capitalized.
Disable System Auto-Shift
Newer versions of the Palm OS automatically capitalize the beginning of words. Checking this option tells TealScript to ignore this auto-capitalization. The Shift indicator will still automatically activate, but it's effect will be ignored unless it was manually turned on by a graffiti stroke.
Profile
Choose, create, clone, rename, or delete the current stroke profile. When you first begin, it's highly recommended that you copy the default profile before making any changes.

Buttons:

Train Profile
Bring up the training screen to teach TealScript to better recognize your own distinct grafitti.
Edit Profile
Bring up the editing screen to view, adjust, or retrain individual strokes in the profile stroke library.
Test Profile
Test the current profile, showing strokes as you enter them along with their matched profile entries.
Statistics
Show statistics on stroke that were entered since the last time the current profile was set or changed.

Training Screen

The training screen allows you to easily modify whole groups of strokes in the current profile. When the Train Profile option is selected, you'll be presented with a list of character groups to train, such as "alphabetic" or "numeric". Select one, and you'll be brought to the training screen, and asked to enter a series of strokes one at a time. Simply enter all the strokes carefully, ignoring any shifting strokes you may ordinarily need to do when entering the characters. Enter the strokes naturally, but slowly and carefully enough to be representative of your handwriting.

You will be prompted with each stroke before you enter it, but you needn't use the exact suggested stroke for a particular character if there are active alternates in the current profile. The system will match each stroke to it's closest entry in the stroke profile, and adjust that entry to resemble the stroke you entered. In general, global training in this manner will help with minor differences in stroke such as a general slanting of letters, but won't help with specific instances of stoke confusion. For those cases, use the more specific training methods below.

Profile Edit Screen

On the profile screen, a list of the strokes in the current profile appears on the left. The current stroke in the list appears below. On the right are various adjustable settings corresponding to the current stroke. You can quickly seek to entries in the stroke list by entering that key corresponding to those entries as a graffiti stroke. Note that if you have global recognition enabled, this will be dependent on the accuracy of your current stroke profile.

Settings:

Key
The keystroke generated when the current stroke is entered. This is not changeable in an existing stroke.
Class
Three settings: Standard, Alternate, or Distort
Standard
A normal graffiti stroke
Alternate
A special or ususual stroke. Alternate strokes are in a separate category so that they can be easily turned off from the main menu should a particular user find them confusing.
Distort
A misshapen entry meant to help the graffiti recognition understand even an incomplete or badly entered stroke. Distort entries are unaffected by the global training screen accessible from the main menu.
Squelch
A value that allows you to deemphasize the current entry, forcing the recognition system to be more stringent when trying to match this entry to an entered stroke. Use this to compensate for the fact that simpler strokes with few angles are easier to match than more complex ones. Do this by increasing the squelch of simple strokes that are being false detected in place of more complex strokes. Use care when setting this value, however, as too high a squelch will make this stroke unrecognized when it should.
Cutoff
The Cutoff sets a minimum match percentage for this stroke to be considered recognized. Most of the time, this is a better way to prevent a particular character from being falsely detected as other characters. Note that the cutoff percentage is considered after the squelch value has been applied to the detected match percentage.
Active in Alpha Area
When checked, this stroke is valid entered in the alpha entry area on the left side of the graffiti area.
Active in Number Area
When checked, this stroke is valid entered in the numeric entry area on the right side of the graffiti area. Note that either this or the previous option must be set for a stroke to ever be recognized.
Normal Mode
This stroke is valid with no shift modes active
Punctuation Mode
This stroke is valid when punctuation shifted
Symbol Mode
This stroke is valid when symbol shifted. Note that at least one of the three above options must be set.

Buttons:

Add New
Add a new entry into the stroke profile.
Retrain
Retrain the stroke corresponding to the current entry.
Remove
Delete the current entry from the stroke profile.
Done
Return to the main screen.

AscII Strokes

Normally, when you create a stroke entry, you can choose the stroke from the a presented list of strokes. If you wish, however, you can create strokes for character not in the list by choosing the last "ASCII..." option at the bottom of the list. Do this to create strokes for special characters in the Palm fontset for for special one-stroke capital letters. You'll be prompted to enter an ascii value from 1 to 255 for the new stroke.

Test Screen

The test screen provides a text field where you can test how the current stroke profile recognizes your text entry. As you enter each character, the stroke you entered appears on the left, while it's match in the profile (if found) appears on the right. A match percentage is displayed showing how close the two strokes are to each other mathematically.

When you encounter a stroke that isn't recognized by the current profile, you can add it by clicking on the "Add New" button. You'll be asked to set basic parameters for the stroke, including the key character it represents.

Statistics Screen

The statistics screen shows various statistics about your graffiti entry under the current profile, such as stroke count, writing rate (in strokes per minute), corrections, and unrecognized strokes. Statistics are tabulated if the statistics checkmark is set in the main screen, and are reset whenever the profile lookup system is updated to reflect changes made in the current profile.

Also shown are the top five missed strokes (strokes following a backspace) and misentered strokes (stokes preceeding a backspace). These two lists are present to help identify common entry errors and thus aid you in fine-tuning a stroke profile.

Tuning

Tuning a stroke profile to improve recognition accuracy involves two steps, identifying the cause of problems and fixing them using a number of methods.

Identifying Problems

To identify problems, enter text in the Test Screen and watch which strokes get matched to each entry. Verify that mismatches are not due to sloppy or misentered strokes or errors in the stroke profile. If the entered stroke shown in the test screen doesn't look like the desired character, of course there's no way the recognition system will be able to match it. Make note if a stroke is mismatched to another entry, as you may be able to fix the mismatch by adjusting the two strokes. You can also check statistics to identify which character may need specific retraining or aliasing, described below.

Retrain Stroke Entry

The simplest fix for some problems is to retrain a single entry in the current profile to more closely reflect your own writing. Be sure that the stroke is still close enough to the standard stroke and is not too close to the stroke for another character.

Adding Entries Aliases

Sometimes, it's not wise to change an entry too much, as it will keep TealScript from recognizing someone else's strokes for the same character. Also, if there is a wide variance in how you make a particular stroke from time to time, it may not be possible for one stroke entry to match all the time. For instance, if you have a tendency to sometimes make an incomplete 'S' character, you shouldn't retrain the system to recognize your 'S' as the only 'S'.

Instead, you should add another 'S' entry to the profile for an incomplete 'S' so that both a full and incomplete 'S' strokes will be properly recognized. Indeed, the default stroke profile provided with TealScript has aliases for under and over-rotated 'O' characters, sloppy 'S's and many others.

The easiest way to make alias entries in from the test profile. When you encounter a stroke that isn't recognized by the current profile, you can add it by clicking on the "Add New" button.

When making an entry alias, be sure to set the class to "Distort", so that training operations will ignore the stroke. Otherwise, repeated global training will tend to water-down the aliases for each character until they all look alike.

Adjusting Squelch Value

As a final adjustment, the recognition system can be told to make some strokes more difficult to match. This can be used to keep some strokes from interfering with similar ones. The first step in doing this is to add a squelch value. A higher squelch will make a stroke appear less often. Relatively smooth and simple strokes have a tendency to come up more often than complex or angular ones, and may require some squelch. Be very careful in changing squelch, however, as it will make that character harder to recognize. In many cases, adding an alias is a better way to correct a particular misrecognition problem.

Cutoff Value

A cutoff value can keep a sloppy-entered or malformed stroke from appearing as an incorrect low-percentage match to another stroke. To do this, set cutoff value for the stroke that is incorrectly coming up as a match. The cutoff value for a stroke entry should be set after testing that entry repeatedly in the test screen. Set the value lower than any possible valid entry, but high enough to filter out invalid matches.

Alternate Strokes

Once you have good recognition happening, you may wish to add your own alternate strokes into the stroke profile. The default profile has some simple alternates such as a lower case 'e'. When adding alternates, make sure that they aren't too similar to existing graffiti strokes. For instance, a lower case 'n' may not be a good idea because many people's graffiti 'h' look too much like an 'n', particularly when they are writing quickly. When adding an alternate, it's a good idea to flag it as being in the "alternate" class, so even if it works for you, you can quickly turn it off temporarily in the main menu for someone else.

How the matching system works

When a stroke is entered into the graffiti area, it's broken down mathematically and compared to each of the entries in the stroke profile. The comparisons are done using different criteria, each of which are given a weighing factor in calculating the total match percentage for the pair. This match percentage is modified by the entry's squelch value, if present, and the resulting value is compared to the entry's cutoff value. If higher, the entry is considered a possible match. The best of these matches is returned as the final match.

The weighting factors for the criteria used to perform the matches can be modified via a Control screen reachable via menu item in the Main or Profile Test screens. It is highly unlikely that adjusting the weighing factors will result in improved recognition, but for curiosity's sake the factors are described in the (i) information button on the Control screen.

Backing up Profiles

To back up a profile during hotsync, select the "Details" menu item from the profile edit screen.

Compatibility

As we cannot control the style and robustness of other products, we cannot guarantee compatibility with PalmPilot applications beyond those included from Palm Computing. However, we try to resolve compatibility issues as best we can.

Defragger
Be sure to disable TealScript before running a memory management program like Defragger, or changing the state of any hack that may patch into graffiti recognition routines. We're currently looking into compatibility issues with PiLock.
SymbolHack, SelectHack, and CorrectHack
We suspect one or more of these programs to be incompatible with TealScript for unknown reason, perhaps due to stack memory limitations, causing random crashes, particularly on non-PalmIII Pilots.
Screenwrite Is incompatible, as it patches into the default system graffiti system.
ShiftHack Use the new "Disable Auto-Shift" option in TealScript to perform the same operation.
System Shortcuts The special Palm OS backdoor/debugging dot (.) shortcuts won't work with TealScript active. Disable TealScript before using them.

Revision History

Contact Info

TealScript by TealPoint Software
(c)1998 All Rights Reserved.
TealPoint Software
454 Las Gallinas Ave PMB #318
San Rafael, CA 94903-3618
We look forward to hearing from you.

Please visit us at www.tealpoint.com, or
email us at contact@tealpoint.com.

Thank you.

Registering

Currently, you may register by snail mail, electronically through our website with a credit card and a secured server, or through PilotGear HQ at 1-800-741-9070. For the first option, the enclosed registration form is provided for your convenience. You may use this form or simply send the following to the address above.

Disclaimer

We at TealPoint Software are committed to providing quality, easy-to-use software. However, this product is provided without warranty and the user accepts full resposibility for any damages, consequential or otherwise, resulting from its use.

This archive is freely redistributable, provided it is made available only in its complete, unmodified form with no additional files and for noncommercial purposes only. Any other use must have prior written authorization from TealPoint Software.

Unauthorized commercial use includes, but is not limited to:

  1. A product for sale.
  2. Accompanying a product for sale.
  3. Accompanying a magazine, book or other publication for sale.
  4. Distribution with "Media", "Copying" or other incidental costs.
  5. Available for download with access or download fees.
This program may be used on a trial basis for 30 days. The program will continue to function afterwards. However, if after this time you wish to continue using it, please register with us for the nominal fee listed in the program.

If you do choose to register with us and are using ReScript, please also register HackMaster with DaggerWare if you have not already done so.
Thank you.