Quickstart

When you start JGloss for the first time, you should set the dictionary files which you want to use. Choose the Preferences item from the Edit menu, and select the Dictionaries tab in the newly opened window. Add the dictionaries you want to use and click OK. Note that dictionary entries will be chosen in the order of the dictionaries, so put your preferred dictionaries higher in the list.

Use the Import item from the File menu to open the import dialog. To import a file, select the File tab and enter the URL of the file you want to import. To choose a local file, click the Choose file button. Alternatively you can select the Text tab and paste the text to import in the area below.

Once you have made the text selection, click Import, and the text will be parsed and annotations will be added by looking up words in the dictionaries. After some time (this can take rather long for larger texts) the annotated document will be displayed in the window.

Figure 3-1 shows the JGloss window after some text is imported. The left part of the window shows the annotated document. An annotated word is shown in light red, with the reading annotation above and the translation annotation below the word. The right part of the window contains the annotation editor. For every annotated word, the word and its current reading and translation is shown. For the selected annotation at the top of the list, the annotation editor shows the current reading and translation, the dictionary form of the entry, and all readings and translations found in the dictionaries. You can use the annotation editor to change the reading and translation of a word, either by selecting one of the listed entries, or by selecting the current reading/translation item and entering the new text.

The heuristics used for generating the annotations are not perfect. For example, if you import a text using the edict dictionary file, is assigned the reading instead of and is assigned the reading instead of the more common . This happens because the application picks the first reading and translation found in the dictionary. Also, the algorithm used for verb/adjective deinflection can produce false results. What follows is that you should not trust the automatic annotations too much and that the document will require some editing.

To edit an annotation, select it in the annotation editor. The annotation editor will expand the annotation and show the dictionary lookup result, and the annotation will be highlighted red in the document view. Use the down key to select an entry with the appropriate reading or translation and hit the space bar. This will make the selected entry the reading/translation of the annotation. To manually edit the text of an annotation, select the Reading or Translation item and hit space to start editing.

When you have finished editing your document, you can export it to different formats. Select HTML from the Export entry in the File menu. In the file chooser you can select which type of annotations will be written. Select a file name and save the HTML file. If you are using a current version of the Microsoft Internet Explorer, which already (more or less) supports the Ruby Annotation XHTML specification, the ruby will be rendered above the annotated word by the browser. Translations will be shown in a popup window if you move the mouse over a word.

The Document View

The left part of the window shows the annotated document. Annotated words will have a colored background. You can change the colors or switch them off in the preferences dialog and toggle the display of reading and translation annotations in the View menu. If you left-click on an annotated word, the annotation will be selected in the annotation editor. A right-click will select the word and pop up a context menu with options for this annotation (see the Section called Annotation). To look up the currently selected text in the dictionaries, select Word Lookup. To add an annotation, select some text and use Annotate Selection in the Edit menu (see the Section called Edit).

The Annotation Editor

The annotation editor is used to edit the reading and translation annotations of annotated words in the document. It is displayed in the right half of the JGloss window (see Figure 3-1). Each annotated word has an entry in the editor, ordered by its appearance in the document. The entries are displayed as a list, with the currently selected annotation expanded to show the dictionary search results. If an entry is selected, the annotation will be highlighted in the document view.

You can use the keyboard to navigate in the editor. The cursor up/down keys will move the selection by one item. To move to the next annotation press N, to move to the previous annotation press P. Pressing space will do something useful, depending on what kind of item is currently selected. Look at the table below for the full list of keyboard commands. Right-clicking an entry with the mouse will show a context menu for the chosen item (see the Section called Annotation).

Each annotated word has one or more readings. If a word has no kanji characters, the reading will span the whole word. Otherwise, a reading annotation is added to every kanji substring of the word. The annotation editor shows the reading, or list of readings. To edit a reading, select the item and hit space, or click it twice and wait a moment. When you are done with editing, press return, and the document view will be updated with the new reading. The second item shows the current translation. It is edited in the same way as a reading.

The dictionary form item shows the dictionary form of the annotated word. This form will be used for a user dictionary entry, the annotation list and the LaTeX export format. The dictionary form will be set when you select the reading from one of the dictionary entries. To edit it manually, hit space when the dictionary entry item is selected. This will show the word and reading part of the entry, which you can edit like the reading/translation items.

Some text documents you can find on the net are already annotated with readings by placing the reading in brackets after a word. These readings can be recognized by the text parser during importing and used as reading annotation. They are shown in the Reading from document items. Selecting one and hitting space will make it the reading of the annotation. If you are using a dictionary which provides readings but no translations, entries from this dictionary will also be displayed this way. The ChaSen parser will also provide readings for some words.

For every dictionary in which an entry for the annotated word is found, an item will be generated showing the dictionary name. Under the name, for each entry the dictionary word and reading will be shown, and under that one item for every translation. If you select a reading and hit space, the reading will be made the new reading annotation, and likewise for a translation. If a dictionary entry was found using verb/adjective de-inflection, the item will show the dictionary form of the word and in brackets the grammatical form in which the word appears in the document. Note that this algorithm may show wrong grammatical forms and therefore this feature should not always be trusted.

Importing text documents

To create a new annotated document, select Import or Import Clipboard from the File menu. Import Clipboard will create a new document from the content of the system clipboard, it can be configured in the General Preferences dialog.

Selecting Import will show the Import dialog. In the text field you can enter an HTTP URL or the file name of a local document. The document should be plain text. There is some support for importing HTML documents, but it will only work for documents with simple layout. If you click the Choose File button, a file chooser dialog will pop up and let you select a local file. The character encoding of the file can be selected in the Character encoding ... popup menu. You can usually leave it on the <auto> setting, which will make JGloss auto-detect the encoding of the file. If the auto-detection fails for a file, you can select the encoding manually. You can choose the text parser for the automatic annotation in the Text Parser part of the dialog (see the Section called Text Parser selection). Clicking the Import button will import the selected file.

If a reading is supplied for a annotated word, this reading will be used for the reading annotation, and the first translation found with this reading will be used for the translation annotation. Otherwise, the first reading and translation found in a dictionary will be used for the annotation. You can change the annotations later manually.

Exporting annotated documents

JGloss supports the exporting of annotated documents in several formats, described below. You can select one of the formats from the Export submenu in the File menu.

A common option for all formats is the character encoding of the generated file. What format you use depends mainly on what application you want to use the exported file with. Modern web browsers should support all of the encodings. For other applications, if you are working on Windows, you should try Shift-JIS and on Unix EUC-JP. If the document or your annotations contain characters not in ASCII or the Japanese character set (e. g. umlauts), you should use UTF-8, which takes more disk space but can represent all characters.

With the write "hidden" annotations switch you can control how to treat annotations which are marked as hidden in the annotation editor. If it is unchecked, the annotations for hidden words will not be written to the generated document.

The User Dictionary

The user dictionary is a special dictionary to which you can add words from within the annotation editor. The user dictionary will always be shown in the list of dictionaries and cannot be deleted. You can use the user dictionary to add words which don't appear in any of the other dictionaries. Another use of the user dictionary is the selection of a preferred reading/translation for a word with several readings/translations. Since during a import the first reading/translation found for a word is choosen and the user dictionary is first in the list, entries in the user dictionary will be preferred.

To add an entry to the user dictionary, select an annotation in the annotation editor and choose Add to Dictionary from the Annotation menu. The dictionary form and current translation will be used for the new entry. There currently is no way to delete or edit an entry from within JGloss, but you can edit the dictionary file. The dictionary is saved in EDICT format to the file .jgloss-userdictionary in the user's home directory.

The Word Lookup Dialog

You can look up words in the dictionaries from the word lookup dialog. Enter a Japanese or English word in the Enter Expression text field and click the Search button. The results will be displayed in the lower area of the dialog window. The part of the entry which matched the expression will be highlighted blue for each result line. Hitting the Clear will delete the current search expression. If you select the arrow to the right of the text field, a popup menu listing previous search expressions will be shown.

You can select the search mode from the Search Options part of the dialog. Exact matches will only return entries where the entered expression is identical to the word, reading or one of the translations of the entry. Starts with Expression and Ends with Expression will find entries where the word, reading or one of the translations have the search expression at the beginning/end. Any Match will return entries where the search expression appears anywhere within the result. Note that the dictionary formats may not support all of the search options. For example, the EDICT implementation does not do "ends with" searches for readings so you might not get all possible matches if you use this search mode.

The Best Match search option will automatically adapt the search mode such that the least number of results are found. If a Best Match search is performed, Exact matches will be tried first and if no results are found, the other search options are tried one after the other until a match is found or all options have been tried.

The Use Deinflection checkbox enables the use of the verb/adjective deinflection algorithm for the search expression. The algorithm tries to derive the base form of the search expression by looking at the hiragana ending. This might find entries for inflected word forms, but may also yield confusing results, since the algorithm does only work for some verb forms.

You can limit the search to a single dictionary by selecting the Search Dictionary radio button and selecting the dictionary from the popup menu to the right. If the Search all Dictionaries radio button is selected, all dictionaries made available to JGloss in the preferences will be searched.

If you use the JGloss word lookup dialog to look up words copied from other programs, you might want to enable the automatically search clipboard content option in the dialog window. If the option is selected, every time the JGloss window is brought to the front, the content of the clipboard is entered in the Search Expression field and searched using the current search settings. This way you can look up words in other programs by simply selecting the word, copying it to the clipboard and bringing the word lookup dialog to the foreground.

Text Parser selection

JGloss can use two different parsers for the automatic annotation of Japanese text, the Kanji parser and the ChaSen parser. Select the parser by clicking the respective radio button. The ChaSen parser will only be available if the chasen program is installed (see below).

If the annotate first occurrence option is selected, each word in a document is only annotated the first time it appears. This decreases the RAM usage and the time it takes to display the document. The Guess paragraph breaks option controls how line breaks in the imported document are converted to paragraph breaks. If the option is selected, JGloss tries to determine if a line break in the imported document signifies the end of a paragraph or if it is used for formatting reasons only. In the second case, it will be ignored.

Some documents you can find on the internet already have reading annotations added to kanji words in the form of some hiragana enclosed in brackets after the kanji word. The parsers can generate reading annotation entries for these words. You can select the brackets used in the document for reading annotations with the Brackets used... box. If the document contains no reading annotations, you can select none or simply ignore this setting.

The Preferences Dialog

The preferences dialog contains four panels, one with general preferences, one for setting the visual appearance of the annotated document, one for managing the dictionaries and one for editing the list of words excluded from annotation. You can access the dialog by selecting Preferences from the Edit menu.

JGloss menus