Version of the documentation: $Id: oohanzi-doc.xml 245 2008-02-06 03:44:41Z ldd $
Everything is at version 0.1 right now. This software is very much at the Alpha stage of its life-cycle. Expect bugs. Expect nonsensical design decisions. Expect quirks.
OOHanzi is hosted on Launchpad. Please use the Launchpad facilities to report bugs and ask questions.
I will soon put the entirety of the code base on Launchapd.
This code has been tested with Open Office 2.3.0. I have used it with older versions of Open Office (2.0.x and higher) but the latest version of the code has not been tested on anything older than 2.3.0.
You need to be able to run Java code on your computer. The extensions have been tested with Java 6 or higher.
People running Ubuntu 7.4 or 7.10 must install either sun-java6-jre or icedtea-java7-jre. (The latter seems preferable.) People running other systems should refer to their system’s documentation.
You need to get three items:
The string “[version]” stands for the version number of the respective packages. Always use the latest version numbers. Here are links to the directories containing the files above:
Make sure that your Open Office setup is set to find the Java JRE. Go in “Tools->Options”. Get to the “Java” tab (located under “Open Office.org” in the hierarchy on the left). Once you open that tab, it will take a little bit of time but Open Office will search your disk for JREs already installed. After it has found them, it will populate the table labeled “Java runtime environments (JRE) already installed:”. Select the one you want to use (usually you want the latest version), and click “Ok”.
On Ubuntu systems, Open Office is able to find all properly packaged JREs. (That is, all JREs provided by the Ubuntu repositories.)
If Open Office is unable to find your JRE, then you need to click “Add…”, find where your JRE is located and add it to the list. Because I run Ubuntu, I’ve never had to do this so I do not know the ins and outs of adding a JRE manually.
After you select your JRE, you will most likely have to restart Open Office. You will get a dialog that will tell you to do so. [NOTE: you can wait until you preform step 3 to restart Open Office.]
You must make unihan-lib-[version].jar available to the Java JRE. Whichever method you use is fine so if you already have your own method to make 3rd party jars available, use your method. Otherwise, do the following.
Go back into the same Java configuration tab as you did in step 2. This time around you need to click “Class Path…” and then “Add Archive…”. Find the unihan-lib-[version].jar that you saved in step 1 and click “Open”.
Restart Open Office so that the library will be loaded next time the JRE is run.
Start Open Office. Go in “Tools->Extension Manager…”.
Click on “Add…”, find oounihan-[version].oxt and click “Open”. Click on “Add…” again, find oohanzi-[version].oxt and click “Open”.
You’re done! You should now have menu item called “OOHanzi” in your menubar. If you do not get that menu item, then something went wrong. Contact me.
[IMPORTANT NOTE: When you use OOHanzi, if you immediately get some horrible message that says that it cannot load a Java class, it means that your java environment is not working properly.]
After installation, you have a new menu called “OOHanzi”.
[KNOWN BUG: None of the items in the menu “OOHanzi” are ever grayed out, even when they should not be usable. For instance “Clear Pronunciation” should ideally be grayed out when no text is selected. If no text is selected, there is no point using “Clear Pronunciation” since it works on the current selection. Several other items in “OOHanzi” are the same. Unfortunately, the documentation for writing extensions for OO is terrible. Most of it is in a half-baked state or out of date or does not cover everything needed. There is probably a way to ensure that menu items are active only when they should be active but I do not know how to do this.]
The functions under it are:
This removes all the pronunciation from the selected text. See the next two functions to get an idea of what this means.
Fix Pronunciation Using Unihan
This adds pronunciation to the selected text. The pronunciation is taken from the Unihan database and added as “rubies” to each character of the selected text. See this page if you don’t know the term “ruby” in this context.
The algorithm actually works in 2 steps:
- For a given character on which the user wants to add the pronunciation, it first tries to find the same character in the current document. If that character already has its pronunciation in its ruby, then that pronunciation is copied to the current character.
- If the search in step 1 fails, then Unihan is used to get the pronunciation. The pronunciation extracted from Unihan is Mandarin.
[FOR FUTURE DEVELOPMENT: Configure OOHanzi to be able to get various pronunciations out of Unihan rather than just Mandarin.]
Fix Pronunciation Using Documents
This adds pronunciation to the selected text. The pronunciation is taken from any *currently opened Text* document (i.e. Open Office Writer documents). This is like step 1 in “Fix Pronunciation Using Unihan” but the search is made across all currently opened Text documents. If the search fail, Unihan is *not* consulted.
[FOR FUTURE DEVELOPMENT: “Fix Pronunciation…” is a stupid nomenclature, change that to something more intelligent.]
Display Unihan Information
This searches the Unihan database for the currently selected character and displays a window with the data found in Unihan. See the Unihan documentation for meaning of each field.
The problem with doing Unihan lookups is that Unihan records all regular pronunciations of a character. I vaguely remember doing a computation showing that there are at most 5 pronunciations for a given character (in Mandarin). So under this item, you find 5 menu items that are used to select which pronunciation to keep. Usage scenario:
1. You select some text.
2. You use “Fix Pronunciation Using Unihan”.
After that is done, the first character has 5 pronunciations in its ruby. You cant to fix it.
You select that character.
You execute “OOHanzi->Adjust Pronunciation->Keep 3rd”.
Now that character only has the 3rd of the 5 pronunciations.
Note that it is always possible to arbitrarily edit the ruby of any character by going in “Format->Asian phonetic guide…”.
This menu contains menu items to perform searches in dictionaries hosted at various web sites. The selected text is looked up at the web site which corresponds to the menu item selected.
DDB is Charles Muller’s Digital Dictionary of Buddhism.
CJKV is Charles Muller’s Chinese Japanese Korean Vietnamese Dictionary.
[KNOWN BUG: The menu just says “CJK” which is not only incorrect (should be “CJKV”) but is probably not descriptive enough.]
Etymology is YellowBridge’s Etymology Dictionary.
This menu item brings up a dialog that allows the user to specify how “Display Unihan Information” presents information extracted from the Unihan database. It is a good idea to filter that information because Unihan contains a lot of data and some of that data is useful only to some users.
At the top of the dialog there is a checkbox labeled “Filter returned Unihan fields”. If it is unchecked, then OOHanzi does not filter the data provided by Unihan. If it is checked, OOHanzi will include only the fields listed in the “Included fields” list which appears just under the checkbox.
All fields which appear in the “Included fields” list will be displayed by “Display Unihan Information”. All fields which appear in the “Excluded fields” list will not be displayed. Use the two buttons between the two lists to move items from one list to the other.
Eventually the entire code for everything will be made available on the web. Right now however, only the OOBasic portions are available. To get to them, go into “Tools->Macros->Organize Macros->OpenOffice.org Basic…”. All the OOBasic code for OOHanzi will appear in the hierarchy under “My Macros/OOHanzi”.