Change Log
- Added some code to make things a bit more user friendly when a JRE is not properly installed.
- Modified the way web browsers are launched.
- Changed the nomenclature of menus and some functions.
- General fixes to improve stability in Windows.
Status
This documentation deals with version 0.2 of OOHanzi. This software is very much at the Alpha stage of its life-cycle. Expect bugs. Expect nonsensical design decisions. Expect quirks.
Imagine a paper even before it is at the draft stage, when it is still just a bunch of thoughts quickly put together. Or notes taken at a conference. At this stage, OOHanzi is very much the programmatic equivalent of that paper or those notes.
Acknowledgments
My thanks go to Charles Muller for prompting me to release this and for testing and reporting bugs. I was planing to release it for a long time but never got around to it. When he asked to see what this was all about, I had to finally package it for other people.
Support
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.
Prerequisites
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.
Linux: People running Ubuntu 7.4 or 7.10 must install either sun-java6-jre or icedtea-java7-jre. (The latter seems preferable.) Other distributions probably have equivalent packages that can be installed.
Windows:There are many options for Windows. It is possible to download Open Office together with a Java 6 from the Open Office web site. This is the option I used when I installed OO in Windows for testing OOHanzi. I know nothing about the other options.
People running other systems should refer to their system’s documentation.
Installation
-
If you use the Open Office Quickstarter, please pay attention to the following. If you don’t know what the Quickstarter is, please read page 6 of this document. Note that the OO Quickstarter is installed by default in Windows. Here is the important part: if you use the Quickstarter, then whenever the instructions tell you to restart Open Office, you must also go into the Quickstarter and select “Exit Quickstarter”. If you do not exit the Quickstarter, Open Office will not be unloaded from memory and thus will not restart when you open it again. It will just work from what is already loaded.
-
You need to get three items:
- http://lddubeau.com/downloads/java/unihan-lib-[version].jar
- http://lddubeau.com/downloads/openoffice/extensions/oounihan-[version].oxt
- http://lddubeau.com/downloads/openoffice/extensions/oohanzi-[version].oxt
The string “[version]” stands for the version number of the respective packages. Always use the latest version numbers. It is normal if all three files do not have the same version number. 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. If you use the Quickstarter, please also exit the Quickstarter. [NOTE: you can wait until you preform step 4 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 3. This time around you need to click “Class Path…” and then “Add Archive…”. Find the unihan-lib-[version].jar that you saved in step 2 and click “Open”.
Restart Open Office so that the library will be loaded next time the JRE is run. If you use the Quickstarter, remember to exit the Quickstarter too.
-
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.]
Upgrading
When you get a newer version of an oxt file you can just double click on it and Open Office will install it over the old version. However, I have noticed that Open Office does not register menu changes until I restart it. This seems to be a quirk in how Open Office operates.
Upgrading to a new jar requires that you uninstall the older jar and install the new one. Go to the menu item “Tools->Options”. Go to the Java tab. Click “Class Path…”, remove the old archive and add the new one.
Usage
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:
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.
Lookup
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.
Etymology is YellowBridge’s Etymology Dictionary.
Fill Rubies 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.]
Fill Rubies 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.
Adjust Rubies
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…”.
Clear Rubies
This removes all the rubies from the selected text.
Preferences
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.
Other known bugs
In Ubuntu, when running Open Office 2.3.0 the dialog windows are sometimes not sized properly. This is a random bug which I have been able to reproduce with extensions produced by other people so I know it is not a bug in OOHanzi. I’ve also been able to reproduce it with new “virgin” installations of Open Office so I know it is not a bug in my configuration. My best guess it is that this is a bug in Open Office itself. I have reported the bug. As far as I know, this bug does not happen in Windows.
Hacking
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”.
Version of the documentation: $Id: oohanzi-doc.xml 256 2008-02-07 19:36:31Z ldd $