Chinese Tools Version 0.5a -- readme.txt

Copyright (C) 1999 Delesley Hutchins
Permission is granted to any individual or institution to use, copy, or
redistribute this software so long as all of the original files are included,
that it is not sold for profit, and that this copyright notice is retained.

WARNING: This program is ALPHA software -- use it at your own risk.

Introduction

This my first shot at a set of Chinese language tools for the BeOS.  Right now it just includes two things, a Chinese input method, which is the most important part, and a simple program to convert Big5 text files to Unicode.

The Chinese input method is fairly simple.  It uses the dictionary files that are included with cxterm, a Chinese terminal program for Unix.  The cxterm dictionaries are in a generic format that can be used to create many different kinds of input methods, even for languages other than Chinese.  I have converted most of the traditional Chinese (Big5 encoded) dictionaries already, but additional dictionaries can be found within the cxterm package or available for download on the internet.  See below for details on how to convert other dictionaries for use with the BeOS.

I am not including source code with this alpha version, because I haven't decided on an appropriate license yet, and I don't want people mucking with the code until I'm ready.  I hope to release it as open source by version 1.0, but no promises.  

If you are using the Haru font, you will notice that there are a lot of characters that it doesn't include, which not surprising considering that fact that it's a Japanese font.  Unfortunately, I could not find any free Chinese unicode truetype fonts for download -- if you find one, be sure to let me know so I can include a pointer to it here.  


Installation

First, unpack the zip archive.  Since you're reading this file, I assume you've already done this.  Then copy the "Chinese_Tools" folder to "/boot/apps."  Now double click on "install.sh", which is the installation script.   Note that the install script assumes you've put things in /boot/apps, so if you want to stick things anywhere else you'll need to follow the manual installation instructions below.  

The input server does not automatically check for new input methods, so you will need to restart your computer.  If you run into any problems, "uninstall.sh" will remove the input method.

If you want to install it by hand, follow the following steps:

1) Copy (or link) the "Chinese" folder into "/boot/home/config/etc."   This folder contains all the dictionary files that the input method needs to run.

2) Copy the "methods/chinese" add-on into the "/boot/home/config/add-ons/input_server/methods."

3) Copy (or link) all the programs in "bin" to the "/boot/home/config/bin".

To Uninstall:

1) Delete the "/boot/home/config/add-ons/input_server/methods/chinese" add-on
2) Delete the "/boot/home/config/etc/Chinese" folder
3) Delete the Chinese_Tools folder.
4) Delete the (now-broken) links in "/boot/home/config/bin"


WARNING: This program is ALPHA software.  More importantly, it's an alpha input method add-on.  That means that when it crashes, your fancy 16 processor Pentium XX super-mega-professional God Box will turn into a very expensive doorstop with pretty flashing lights.  I have tested this on exactly one system, which is almost certainly different from whatever you're running.  You have been warned.  Neither DeLesley Hutchins nor Chaoticode Software can be held liable for any damage to your computer, your data, your sanity, your love life, your dog, or anything at all.  See the file "License.txt" for the legal crap.

That said, I have done some testing, so I don't think it will crash.  But it might.  If it crashes on startup, you will have to safe boot and remove the input method or your system will be permanently unusable.  

Instructions

Currently, this uses bottomline input only, just like Chinese Windows.  I hope to fix this in the future.  As you hit each key, a window pops up at the bottom of the screen to display all the characters that match that input sequence.  <Space> or <Return> selects the current character and terminates the transaction.  The arrow keys move up or down in the list, and <Page Up> and <Page Down> scroll through the list.  If the list is empty, that means that you have entered an invalid input string.  

An input method can also define any number of "select keys" -- keys that will automatically select an item from the list.  Most of the dictionaries use the number keys 1-0 to select items 1-10.  Note that some input methods use these keys for input as well.  Pinyin, for instance uses the numbers 1-5 to specify tones.  If a key can  be used as both valid input and as a select key, it is used as input.  

The first time you input a character, you will notice a long delay before the selection list finishes drawing.  This is not a bug in the input method; it's due to the fact that the BeOS font renderer is REALLY SLOW.  Once the character glyphs are cached it should operate at normal speed.  I am currently exploring workarounds around this.  For the time being, you can max out the font cache using the Fonts preference panel.  After you have been typing Chinese for a while (thus caching most commonly used characters) open the panel again and click on "Save Cache."

With the exception of the English input method, all methods currently input single characters only.  Phrase dictionaries will be added in a future release.

I have included most of the traditional Chinese dictionaries from cxterm.  Unfortunately, the only ones I actually know how to use are English and Pinyin, so I don't really know if the other methods are operating the way they're supposed to.  If the behavior of a particular input method is not what it's supposed to be, please send me a bug report.  See below for more more information.

The program convertBig5 is a simply command-line utility to convert Big5 text files to UTF8 for use with the BeOS.  It converts Big5 text on stdin to UTF8 on stdout.  Use it like this:

myprompt$  convertBig5 < mytext.big5 > mytext.utf8

There is exactly one option that you can set, and that's the default dictionary that the method loads on startup.  In the "Chinese/dictionaries" folder there's a file called 
"-default-", which is a symbolic link to the default dictionary.  The normal default method is Pinyin, but you can point the link to whatever you want.  Just make sure the link is valid;  if it's not, the input method won't work. 


Dictionary Files

The dictionary files are simple UTF8 text files, take a look in the the "Chinese/dictionaries" directory.  The file format should be self-explanatory.   In addition to traditional Chinese, cxterm also includes dictionaries for simplified Chinese (GB encoded), Japanese, and Korean.  I have not even attempted to use or test these -- they probably won't work at all with this version of the input method.   Note that this version is not 100% compatible with cxterm; you will have to do a little bit of work to get new dictionary files to work.

The first thing you need to do to get a new dictionary working is convert the dictionary to utf8 format.  The utility convertBig5 in the bin directory will convert Big5 encoded dictionaries, but you'll have to write your own converter for other encodings.  

Now open up the dictionary in a unicode text editor (such as StyledEdit) and change the "ENCODING" field to "UTF8".  You will also want to remove any "\XXX" escape sequences -- the dictionary loader will otherwise treat these as simple ASCII strings and might become confused.  The loader also ignores all the movement and editing key information -- look at the default dictionaries to see what it does handle.   

Lastly, the dictionary entries must be sorted.  To this, copy all the header information to a clipping file, and save the dictionary without any headers.  Open up the Terminal, go the appropriate directory, and type 
  $ sort Mydict > Mydict.new
  $ mv  Mydict.new Mydict
Now reload the dictionary in StyledEdit and put the header stuff back.

If you do get a dictionary working let me know and I can add it to the next release.  


Bugs and Future Plans

Please mail bug reports to chaoticode@hotmail.com.  Put the message 
"Bug Report: Chinese Tools" in the message header.  I don't have an automatic tracking system yet, but I will try to get back to you as soon as possible.  

My personal E-mail address is dshutch@mail.utexas.edu.  You can send feedback or suggestions to either address.  

I don't have a web page for this up yet, but I should have up one fairly soon.  
Check the next update for more info.  

Please keep in mind that I am a full time student, have two other projects for the BeOS, and a part time job.  This project is currently a very low priority, so it may take me a while, if ever, to get back to you.  I do have to use this stuff for my own papers in Chinese, so I will release updates now and then, but I'm not going to post any definite schedule.  

Here are the currently known... er.. "features":

There's no Chinese input method icon.  

This currently uses bottomline input only.  I need to add support for input-method aware views.

There is no support for phrase dictionaries.

The selection list uses a BListView, which results in funky <Page Up>  and <Page Down> behavior. 

The selection list always displays the number of the character only, regardless of whatever the actual selector key is.

There is no way to set input method preferences.  

Autoselect is currently funky.  There needs to be more intelligent selection support. 

I need to convert the simplified character dictionaries.  

I need to add proper Bopomofo,  Big5 code, and GB code dictionaries.  
