J-Ben User Manual (for J-Ben v1.2.0)

GTK+/GTKmm: J-Ben is now developed using GTK on all platforms. Any recent version should work, but here's a listing of some of the libraries in use on my Linux system:
- GTK+: 2.12.9
- GLib: 2.16.1
- Cairo: 1.4.10
- libsigc++: 2.0.18
- GTKmm/GLibmm/etc.: roughly matching versions
The Boost Libraries: J-Ben should work with boost 1.34.1 or later.

1.1.2. Linux users

Ensure you have the development packages for libboost and wxWidgets installed. Then, just "make", followed by "make install" to finish the installation.

1.1.3. Windows users

NOTE: These instructions are only for people building J-Ben from source code. If you just want to use J-Ben, proceed to Installing J-Ben.

Windows builds are more challenging in large because setting up the dependent libraries is more of a chore. This is especially true of GTK+ and GTKmm, for which at the time of writing no official all-in-one development distributions for Windows exist, and the ones which are readily available tend to be very out of date. As such, I strongly recommend -against- building from source unless you have a really good reason to do so.

That being said, the Windows development environment supported is MinGW with MSys. The Makefile provided works both under Linux and MSys. (I personally do not plan to support other build environments at this time.)

If you want to give it a try, do the following:

Ensure that you have pkg-config and makensis in your path, or add them in after starting MSys.
Change the variables in the "WINDOWS-SPECIFIC" section of the makefile as needed.
Build using the following command:
```
mingw32-make PLATFORM=windows
```

If there is demand for more detailed Windows build instructions, I will provide them in a later version of this manual.

1.1.4. Expert: "Canadian Cross" Linux->Windows builds

Most people can safely skip this section.

To attempt a "canadian cross" build, run:

make CANUCK=1 PLATFORM=windows BUILD=<release|debug|profile> \
CC=<cross-compiling gcc> CXX=<cross-compiling g++>

(This has not yet been tested; I'm working on it!)

1.2. Installing J-Ben from a precompiled package

1.2.1. Windows users

Most users should use the regular J-Ben installer package, which should be available from the project web site. This installer is most suitable for standard installs of J-Ben.

If you are installing J-Ben onto a USB thumb drive or similar device, you may want to instead download one of the zipped (.zip or .7z) versions of the program and extract it by hand. In this case, to run the program you will want to look for jben.exe, located in the J-Ben\bin folder.

When you run J-Ben for the first time, it will prompt you as to whether you want to run J-Ben in "standard" or "mobile" mode. This simply refers to where J-Ben will store its data files. If you're running on a thumb drive or similar, select "mobile", and your data files will be saved to the thumb drive. If you've installed J-Ben permanently on your system, select "standard", and your files will be stored in your user's Application Data folder. (Usually this is C:\Documents and Settings\<username>\Application Data.)

1.2.2. Linux users

At the time of writing, no precompiled packages exist. I have plans to eventually have J-Ben added to Debian, and if I can make a Linux Standard Base-compliant package I would like to do that as well. For the time being though, it is necessary to compile from source.

#!/bin/sh
cd <path_to_jben>
./jben

Put that in /usr/bin or similar, do a chmod +x on it and that'll make things simpler.

1.3. Optional: Installing stroke order diagrams

The kanji dictionary can be supplemented with kanji stroke order diagrams. J-Ben is licensed to use the 3rd public release of the SODER project's stroke order diagrams, however to save on download size these are not included in the main J-Ben packages. They are available from theJ-Ben download page along with the rest of the J-Ben packages. Download one of these packages and decompress it into the "sods" directory of J-Ben. If there is no "sods" directory, create one. Then, go to Edit->Preferences, and in the Kanji Dictionary preferences tab, enable either regular or animated stroke order diagrams. You should be set. (As a last note, packages directly from KanjiCafe can also be used, but they must be marked as utf8-hex.)

Chapter 2. General usage

2.1. The main interface

J-Ben's main window has two tabs, providing a bidirectional word dictionary and a kanji (character) dictionary. These dictionaries are dependent upon the various dictionary files (EDICT2, KANJIDIC/KANJD212/KANJIDIC2, KRADFILE/RADKFILE) freely available from Monash University on Jim Breen's homepage.

2.1.1. The word dictionary

The word dictionary performs a very simple search based upon the ENTIRE QUERY - it doesn't try to match all the words or some of the words, but rather treats your query as a phrase and matches only the whole phrase. Results are arranged with exact matches first, followed by "begins with" matches, "ends with" matches, and finally, everything else. Japanese searches work best because of the structure of EDICT2, but English searches work fairly well as well.

The word dictionary ties into the vocab study list. You can step through or jump to a random word in your vocab list using the buttons at the bottom of the dictionary tab.

2.1.2. The kanji (character) dictionary

The kanji dictionary searches for one or more kanji characters and displays detailed information about each one. Because of the amount of data available for each character, and because most people don't need much of the data available, the output can be customized through the preferences editor.

Information provided includes (but is not limited to) the following:

Japanese-style readings (kun-yomi) and "Chinese-style" sound-based readings (on-yomi)
Special readings for use in names (nanori)
Stroke count
Jouyou grade level
Dictionary reference codes
Korean and "Pinyin" readings
JIS and Unicode values in hexadecimal
Various radical information

Display of stroke order diagrams can be toggled here. This is dependent upon installing a set of stroke order diagrams.

The kanji dictionary ties into both the kanji and vocab study lists. You can move through your kanji study list using the forward, backward, and random buttons at the bottom of the dictionary tab. Further, if you search for a single kanji and it is in your list, the dictionary will recognize this and allow you to step through your list from the current character. Finally, all character searches are cross-referenced with your vocab study list, and if any of your vocab contain the kanji, they will be listed as well.

2.2. Kanji search

If you do not know how to type a kanji, or are unable to, J-Ben has two methods to allow you to look kanji up and copy them to the clipboard.

The first method is handwriting recognition. This is available via the menu item "Tools->Handwriting Recognition for Kanji". Using this, draw the character using your mouse. As you draw the character, the window will show you the 5 best matches for what you have drawn. This method uses the database from JStroke/KanjiPad/im-ja, and at last count supports searching for 2116 characters.

The second method is the new integrated kanji search, available via "Tools->Kanji Search". This method allows you to choose one or more search methods to quickly find kanji. These search methods all use the standard dictionary files, with the exception of handwriting recognition as previously described.

The integrated search currently supports the following search methods:

Stroke count. Allows for including common miscounts and a +/- search range.
SKIP code, as used in Halpern dictionaries. (An explanation can be found here.) Allows wildcard searches by specifying "0" as any of the 3 index numbers. Also allows a +/- search range, which is applied to both the second and third index.
Handwriting Recognition. This is functionally identical to that provided by the standalone handwriting "pad", but can also be used through this interface.

All selected search methods are applied together, from top to bottom.

More methods will be added in future versions. My highest priority is multiradical search support as seen in JWP/JWPce/Gjiten/WWWJDIC. Other methods will be added as requested by users and as time allows.

2.3. Kanji drilling

J-Ben provides an easy-to-use kanji "flash card" mode. This can be accessed via the "Practice->Kanji" menu item. It requires that you define a kanji study list before using it.

The kanji practice mode is intended as a basic self-study tool, and does not ask you to input any answers to questions or anything similar. It will display information about a kanji with some of the information hidden from view, and it is your job to guess, either mentally or on a separate sheet of paper, what the missing information is. After doing this, you can look at the hidden fields, and you decide for yourself whether or not you remembered the character properly or not.

This is a self-graded test; you decide for each character whether you got it "Correct" or "Wrong", and the program will simply track your answers and help you study the ones you had trouble with. The program will continue to drill you through the characters you mark as "Wrong", and at the end of the test will present you with a score and a list of the characters you got wrong.

The first step in using this mode is to select which characters to test yourself on. You start by choosing how many characters you want to test, and then you pick whether to select the kanji randomly from your list or in order from a certain index of your list. The former method may be better for general review, while the latter would be good for practicing through sets of new characters in your list.

The second step is choosing the type of test. If you want to practice writing characters by hand, you will probably want to try the "writing kanji" option. However, if just reading the characters is sufficient, which may be fairly true if you only read or type Japanese, then you might be better served focusing on "reading kanji".

After clicking "Start Drill", test mode begins. While in test mode, any active dictionary searches will be cleared, and you will be unable to access the word and kanji dictionaries until you finish. The screen will display 4 textboxes containing information about the kanji: the character itself, its on-yomi (sound-based) reading, its kun-yomi (Japanese style) reading, and its meaning in English. Some of the textboxes will be covered up, depending on which test mode you chose: for "writing kanji" only the kanji character is covered, while for "reading kanji" everything except the kanji character is covered. You can uncover each of the textboxes simply by clicking on them. After reviewing each flash card, you choose whether you got it "Correct" or "Wrong", and then the program will go to the next card in your list.

After running through all of the flash cards, if you marked any of them as wrong, the program will continue to drill you through the ones you missed. At this point your score won't change; this is just extra practice and if you want you can click "Stop Test" to skip it. I recommend running through this, though. The extra review ends once you've marked each kanji as "Correct".

At the end of the test (or if you select "Stop Test"), the Test Results message box will appear. It will tell you what your score was, how much of the test you finished, and which kanji you missed, if any.

2.4. Study lists

2.4.1. The kanji study list

The kanji study list is used for storing any kanji characters you are studying. It's used by the kanji dictionary and is required for kanji drilling mode. This list can be added to and sorted based on newspaper frequency and Jouyou grade level.

2.4.1.1. Adding characters to the list

If you don't know where to start on studying kanji, I personally recommend using the Kanji menu to add kanji to your list by Jouyou grade level. This is done by selecting Kanji -> Add Kanji to List -> By Jouyou Grade Level, and selecting a range of grades to add from the dialog which appears. Alternatively, you can select By Newspaper Frequency Ranking and choose kanji to add in that way.

Alternatively, you can import a list from a text file, or you can manually edit the list using the Kanji Study List editor.

2.4.1.2. Importing study lists

The "Add Kanji From File" button will let you import a plain text file into J-Ben, from which all the kanji characters will be detected and added to your study list. The text file must be encoded in UTF-8. If you are unsure about this, it is probably safer to just copy and paste the file directly into the editor window and then press Apply.

2.4.1.3. Manually editing the list

The Kanji Study List editor lets you manually edit your kanji list. You can type kanji in by hand, or copy and paste them from another application. This editor is accessible via "Edit->Kanji Study List".

When you hit the Commit button, your changes are saved. Only kanji which are in the kanji dictionary will be retained; any other characters are discarded. Duplicates are also automatically removed. So, you could simply copy and paste a vocab list into the kanji list editor, hit commit, and you would end up with a list of all the kanji used in that list.

If you don't like the changes you've made, just hit the Revert button, and the list will return to the way it was.

2.4.1.4. Sorting the list

After adding characters to the list, it is strongly recommended to sort the list. The editor allows 3 methods of sorting: by Jouyou grade level, by newspaper frequency, or by both (using an outer sort by grade level and an inner sort by newspaper frequency). Currently you can only sort in ascending order.

2.4.1.5. Clearing the study list

All operations on the kanji list are additive: even importing a list from a file doesn't replace the list, but rather just adds to it. In the case you actually want to replace the current kanji list with another, or just start from scratch, select Clear Kanji List from the Kanji menu.

2.4.2. The vocab study list

The vocab study list can be edited via the "Edit->Vocab Study List" menu item. This study list is primarily used as a cross-referencing resource for the kanji dictionary. The list is formatted with each line representing one Japanese word or phrase. Either manually type in the list, or copy and paste it from another program, and press Apply or OK.

Chapter 3. Preferences editor

Configuring J-Ben is done through the Preferences editor. Currently, you can configure the kanji dictionary, the display fonts, and J-Ben's mobile/standard mode.

3.1. Configuring the kanji dictionary

Most configuration options have to do with the various data contained within KANJIDIC. KANJIDIC has tons of information, and much of it is overkill for the purpose of most students. A set of fairly sane defaults are chosen, but you can modify these as necessary. Most options are self-explanatory.

If you own a paper kanji dictionary, or a set of kanji flash cards, you may want to check through the dictionary reference codes. Index codes for many dictionaries and several flash card sets are included. For example, I personally use the Kodansha Kanji Learner's Dictionary by Jack Halpern, so I usually have this code enabled so I can very easily reference it if I'm not satisfied with the output of KANJIDIC.

If you set up a vocab study list, then there's a useful option to display words in your vocab list which use the kanji you're looking up. This option is strongly recommended. If there's nothing in your study list, or nothing that matches your search, then this option doesn't display any extra information.

The "other information" option is for the various other "excessive" data contained in KANJIDIC but which I feel most Japanese learners usually will not need. This includes JIS and Unicode hex codes, various radical index numbers, Korean and "Pinyin" romanizations, dictionary cross-reference codes, and any other KANJIDIC fields not handled elsewhere.

Finally, if you install one or more of the KanjiCafe.com stroke order diagram packs, you can toggle whether to show them here.

3.2. Configuring the display fonts

J-Ben uses four special fonts for displaying text in the program. Here, you can change how they are set. Each font is described below.

Japanese Font, Normal: General purpose Japanese display font. Used for most Japanese text display throughout the program.
Japanese Font, Large: Used for displaying the "header" character in kanji dictionary output.
English Font, Normal: General purpose English font. Used for dictionary output and some other places where Japanese is not expected.
English Font, Small: Used for displaying disclaimer/copyright related text in some places.

3.3. Other options

Currently only one "other option" is supported: the J-Ben "mobile mode" toggle. As mentioned earlier, this simply adjusts where J-Ben's configuration file(s) are saved. If mobile mode is checked, then settings will be saved based upon the working directory. Usually, this means that it'll save to the program's root folder, which is ideal for USB thumb drives. If mobile mode is not checked, then J-Ben will save to the user's "home" or "Application Data" folder.

(Note for Linux users: mobile mode is currently a Windows-only option. Also, because of this, you probably will not have an "Other" tab.)