Regular Readme
==============
gjiten Manual V2.0

Botond Botyanszki

 <boti@rocketmail.com>

Copyright   1999 - 2001 Botond Botyanszki

Permission is granted to copy, distribute and/or modify this document under the
terms of the GNU Free Documentation License (GFDL), Version 1.1 or any later
version published by the Free Software Foundation with no Invariant Sections,
no Front-Cover Texts, and no Back-Cover Texts. You can find a copy of the GFDL
at this link or in the file COPYING-DOCS distributed with this manual.

This manual is part of a collection of GNOME manuals distributed under the
GFDL. If you want to distribute this manual separately from the collection, you
can do so by adding a copy of the license to the manual, as described in
section 6 of the license.

Many of the names used by companies to distinguish their products and services
are claimed as trademarks. Where those names appear in any GNOME documentation,
and the members of the GNOME Documentation Project are made aware of those
trademarks, then the names are in capital letters or initial capital letters.

DOCUMENT AND MODIFIED VERSIONS OF THE DOCUMENT ARE PROVIDED UNDER THE TERMS OF
THE GNU FREE DOCUMENTATION LICENSE WITH THE FURTHER UNDERSTANDING THAT:

 1. DOCUMENT IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTY OF ANY KIND,
    EITHER EXPRESSED OR IMPLIED, INCLUDING, WITHOUT LIMITATION, WARRANTIES THAT
    THE DOCUMENT OR MODIFIED VERSION OF THE DOCUMENT IS FREE OF DEFECTS
    MERCHANTABLE, FIT FOR A PARTICULAR PURPOSE OR NON-INFRINGING. THE ENTIRE
    RISK AS TO THE QUALITY, ACCURACY, AND PERFORMANCE OF THE DOCUMENT OR
    MODIFIED VERSION OF THE DOCUMENT IS WITH YOU. SHOULD ANY DOCUMENT OR
    MODIFIED VERSION PROVE DEFECTIVE IN ANY RESPECT, YOU (NOT THE INITIAL
    WRITER, AUTHOR OR ANY CONTRIBUTOR) ASSUME THE COST OF ANY NECESSARY
    SERVICING, REPAIR OR CORRECTION. THIS DISCLAIMER OF WARRANTY CONSTITUTES AN
    ESSENTIAL PART OF THIS LICENSE. NO USE OF ANY DOCUMENT OR MODIFIED VERSION
    OF THE DOCUMENT IS AUTHORIZED HEREUNDER EXCEPT UNDER THIS DISCLAIMER; AND

 2. UNDER NO CIRCUMSTANCES AND UNDER NO LEGAL THEORY, WHETHER IN TORT
    (INCLUDING NEGLIGENCE), CONTRACT, OR OTHERWISE, SHALL THE AUTHOR, INITIAL
    WRITER, ANY CONTRIBUTOR, OR ANY DISTRIBUTOR OF THE DOCUMENT OR MODIFIED
    VERSION OF THE DOCUMENT, OR ANY SUPPLIER OF ANY OF SUCH PARTIES, BE LIABLE
    TO ANY PERSON FOR ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR
    CONSEQUENTIAL DAMAGES OF ANY CHARACTER INCLUDING, WITHOUT LIMITATION,
    DAMAGES FOR LOSS OF GOODWILL, WORK STOPPAGE, COMPUTER FAILURE OR
    MALFUNCTION, OR ANY AND ALL OTHER DAMAGES OR LOSSES ARISING OUT OF OR
    RELATING TO USE OF THE DOCUMENT AND MODIFIED VERSIONS OF THE DOCUMENT, EVEN
    IF SUCH PARTY SHALL HAVE BEEN INFORMED OF THE POSSIBILITY OF SUCH DAMAGES.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Table of Contents

Introduction
History
Installation
Dictionary files
Usage

    Word dictionary usage
    Kanji dictionary usage
    Command Line
    KanjiPad

Troubleshooting

    File errors
    Japanese input (mostly Kinput2)
    Window manager and Kinput2 problems
    Fonts and mojibake
    Pasting from Netscape
    Settings
    Bugs

Future Improvements
Feedback
Credits

Introduction

Gjiten is a Japanese dictionary program. It also has a kanji dictionary. Any
combination of stroke number, radicals and search key can be used for kanji
lookups. Gjiten requires a working X Input Method [e.g. kinput2] for Japanese
input.

This program is licensed under the terms of the GNU GPL, a copy of which you
should have received with this package. See the file COPYING for more details.

History

I wrote gjiten because I needed a free software dictionary for my Japanese
studies and wasn't satisfied with xjdic. Learning all xjdic's keys and running
it in the ugly kterm isn't my taste. The other reason is that I've been using
so much software written by the Open Source Software community without any
contributions, so I thought it was time to write something ;) Hopefully someone
finds this little program useful. Older relesases (pre 2.0) used some code from
xjdic written by Jim Breen, but this has been removed.

Installation

Rolling your own from a tarball:

            % tar zxpvf gjiten-x.x.tar.gz
            % cd gjiten-x.x
            % ./configure
            % make
            % make install

Or you can make a binary rpm the following way. You need to be root for this.

            % rpm -tb gjiten-x.x.tar.gz

The rpm package should be created under /usr/src/RPM/RPMS/`uname -m`/ See rpm
(8) for details.

Installation from binary rpm:

            % rpm -i gjiten-x.xxx.rpm

Upgrading from rpm:

            % rpm --upgrade gjiten-x.xxx.rpm

Creating a debian package from the tarball:

            % tar zxpvf gjiten-x.x.tar.gz
            % cd gjiten-x.x
            % dpkg-buildpackage -rfakeroot


This should create ../gjiten_x.x-1_i386.deb.

Then you should install this binary package with dpkg -i.

Dictionary files

Gjiten needs dictionary files to function. You will need the kanjidic
dictionary file for kanji lookups for KanjiDic and other dictionary files for
the word dictionary in edict format. You can get these from ftp://
ftp.cc.monash.edu.au. You should download kanjidic.gz and edict.gz. There are
some other dictionary files also you might be interested in. (j_places,
compdic, etc.) gunzip the dictionary files to the Path To Dictionary Files set
in Preferences. This should be the same directory where the radkfile and vconj
files got installed. [default: /usr/share/gjiten/]. The source tarball contains
a script dicfiles/getdics that will download a bunch of dictionary files with
wget.

The Debian distribution contains three dictionary packages that you can install
via apt-get: enamdict, edict and kanjidicic

As of v2.0 Gjiten uses the GTK2 and GNOME2 libraries. These handle text as
unicode internally unlike their previous versions. Gjiten now needs the
dictionary and data files in UTF-8 encoding instead of EUC-JP. Please convert
the dictionary and data files to UTF-8. You can use iconv for this.

            % iconv -f EUC-JP -t UTF-8 dictfile -o dictfile.utf8


If the dictionary file is not UTF-8, Gjiten will complain after you add them in
the preferences.

The datafiles radkfile.utf8 and vconj.utf8 are needed by Gjiten. Please copy
these into the directory of your dictionary files.

Usage

Start up gjiten.

Set the Preferences first, otherwise gjiten might not work correctly. Add the
dictionary files to the list that you want to use with the word dictionary.

Please note that the kanjidic dictionary file should not be added to the list
together with the other word dictionary files, it has a separate file entry
box.

Word dictionary usage

You can set the search options with the toggle buttons. Experiment with them a
little to see what they do. Select the dictionary file in the pulldown menu
under general options that you want to search in.

The Auto Adjust Options can be quite a handy feature. Gjiten will search for
matches setting the English Search Options in the following order if it doesn't
find any match for your prior criteria: Whole Expressions -> Whole Words -> Any
Matches. Similarly in the case of a Japanese search it will set the toggle
buttons from top to bottom.

For Japanese input, you have to activate (shift-space for kinput2 in my case)
the program on your system that can convert and pass Japanese text to GTK. Cut
and paste works well also! ;)

Kanji dictionary usage

I'll refer to the kanji dictionary part of gjiten as KanjiDic.

If you know the stroke number of the kanji, enable the Search By Strokes
option. Set the stroke number. If you are not exactly sure, use the +/- field
also.

Enable the Search By Radical option if you know the radical(s) of the kanji.
Either enter the radical directly through your XIM, or click on the Show
Radical List for the radical window. Here you can click on the appropriate
radical to pop it into the radical search entry. You can enter up to 10
radicals.

If you want to search by a keyword also, then enable the Search By Key option.
A keyword can be anything that the Kanjidic file contains. Usually this will be
a reading (in kana) or an english meaning of the kanji. But it can be a
kanjidic code also. For example entering S8 here would give all the kanji with
8 strokes. Read Jim Breen's documentation about the kanjidic file if you want
to know more about these.

KanjiDic has real-time kanji lookup. This means that while you are entering
radicals it will look up and show the kanji matching your criteria without
having to press the search every time you enter a radical. If only 1 kanji is
found then an info window will pop up with the information about the kanji. If
more than one is found then you have to click on the kanji to get the info
about it. You can customize these info fields shown in the Preferences.

Command Line

Issue the command gjiten --help to get a list of all the command line arguments
that gjiten understands. Here is the important part:

 gjiten options
              -k, --kanjidic              Start up Kanjidic instead of Word dictionary
              -w, --word-lookup=WORD      Look up WORD in first dictionary
              -l, --kanji-lookup=KANJI    Look up KANJI in kanji dictionary
              -c, --clip-kanji            Look up kanji from clipboard
              -v, --clip-word             Look up word from clipboard


Tip

As a useful utilization of these I assigned a shortcut ctrl-alt-w with my
window manager to the command gjiten -v. In the Sawfish window manager you can
add this command to your existing shortcuts as run-shell-command. So I just
have to highlight the text then press ctrl-alt-w and gjiten gets fired up with
the search results already looked up. You can add another shortcut for the
kanji lookup.

KanjiPad

KanjiPad is a separate application written by Owen Taylor. It is a handwriting
recognition program for kanji. Does a quite good job in many cases and might be
faster to use then KanjiDic. Select the kanji that appears on the right side of
KanjiPad after recognition, then you can paste this into KanjiDic or the into
word dictionary for further lookups. Read it's README for more info.

The latest version of KanjiPad can be downloaded from http://www.gtk.org/
~otaylor/kanjipad/

Troubleshooting

Here are some common errors and their solutions users usually get when running
gjiten.

File errors

If you get a message unable to open file: vconj.utf8 or unable to open file:
radkfile.utf8 then you need to put these two data files in the same directory
with your dictionary files set under the Path To Dictionary Files under
Preferences. Please read the installation instructions again.

Japanese input (mostly Kinput2)

Gjiten doesn't have any code that has to do with Japanese input. The GTK
library handles this completely. So if your XIM doesn't work, don't blame me!
;)

Few things that might help to make it work for you: Make sure your XIM works
fine with other applications. Try Kterm for example. If it works with Kterm,
then try a GTK+ program.

Kinput2 needs LC_ALL to be set to ja_JP in order to work, otherwise the input
window won't pop up. You don't need to export this, Gjiten will do it for you
if you enable it in the Preferences (under fonts).

You also need the Japanese locale for glibc to be able to input with kinput2.
Under debian, you will have to put ja_JP.EUC-JP EUC-JP into /etc/locale.gen,
then rerun locale-gen Other distributions should ship this with a locales
package.

Window manager and Kinput2 problems

There was no solution to this problem in the docs, though lately it appeared in
the kinput2(1) manual.

Contributed by John Seebach <jseebach(at)mindless.com>

Certain window managers (I've seen this problem with WindowMaker, Sawmill, and
KWM, but there are probably more as well) don't handle kinput2 pop-up windows
particularly well. You'll know you're using one of those Window Managers if you
fire up gjiten, try to start the conversion widget, and get a window that
blinks uncontrollably and doesn't allow you to enter anything to be converted.

Fortunately, there are some workarounds. First, try adding the following lines
to the kinput2 section of your .Xdefaults or .Xresources:

  Kinput2*useOverrideShellForMode: true
  *preeditType: OverTheSpot


Next, you need to tell your window manager how to deal with a kinput2 window.
I've only tested this with WindowMaker, because that's what I use, so outside
of that, your on your own.

If you're using WindowMaker, try adding the following lines to ~/GNUstep/
Defaults/WMWindowAttributes :

  Kinput2 = {
   DontSaveSession = Yes;
   KeepInsideScreen = Yes;
   KeepOnTop = Yes;
   NoAppIcon = Yes;
   NoHideOthers = Yes;
   NoKeyBindings = Yes;
   NoMouseBindings = Yes;
   NoResizebar = Yes;
   NotClosable = Yes;
   NotMiniaturizable = Yes;
   Omnipresent = Yes;
   SkipWindowList = Yes;
   Unfocusable = Yes;
 };


You may either need to log out of your X session and start again, or try:

% xrdb -load .Xresources

in order for the changes to your X resources to take effect.

Fonts and mojibake

Mojibake occurs when you get garbage instead of Japanese characters. With GTK2
and Gjiten, this will be in the form of empty boxes in place of Japanese
characters. This is a font problem.

Antialiasing (with GDK) and Japanese don't work well at the time. You should
disable it in the Preferences.

You also need to select a fontset that has Japanese characters to be used with
Gjiten. "Sans" and "Serif" and also "unifont" should usually work.

kinput2 needs LC_ALL to be set to ja_JP. If you don't have the LANGUAGE
environment variable set, then this will also default to ja_JP and all the
widget text and menus will be in Japanese. If you wan't English then check the
"Force LANGUAGE=C" option in the Preferences.

The last three options under the Fonts tab need gjiten to be restarted for
these to take effect, because they are setting environment variables.


User Settings
====================
User settings are stored in `<system config path>/gjiten/gjiten.config` .
Under Ubuntu this amounts to `~/.config/gjiten/gjiten.conf`.



Future Improvements
====================

Check out https://github.com/DarkTrick/gjiten/ for the latest release. Read the
TODO file to see what's planned for future releases. Feel free to me with other
suggestions.


Bugs / Feedback
================

File on Github: https://github.com/DarkTrick/gjiten/issues

If you file bugs please try to include the following information:
- gjiten version ( `gjiten --version` )
- distribution and other info about your OS
  (under Ubuntu: `lsb_release --all`)
- gtk release ( `pkg-config --modversion gtk+-3.0` )
- output of `gdb gjiten` and/or `strace gjiten`
- and any other info you might think is important.


Troubleshooting
=====================

Pasting from Netscape
---------------------

If pasting Japanese text from Netscape into Gjiten has no effect, only
non-japanese can be pasted, then set the LC_ALL environment variable to ja_JP
in your shell before starting Netscape (export LC_ALL=ja_JP for bash). This
solved the problem in my case.





Credits
=======

Thanx go to:

  ● Mike Fabian <mfabian at suse dot de> for various patches and suggestions,

  ● Yamagata Hiroo <hiyori13 at alum dot mit dot edu> for translation
    revisions,

  ● John Seebach <jseebach at mindless dot com> for doc and makefile fixes,

  ● Jason Vertrees <tree at computer dot org> and his professor Manabu Mizobe
    for the Japanese translation of the docs and HP, I was to lazy to do it :-)

  ● Ryan Nielsen <ran at gondolin dot fortyoz dot org> for his feature
    enhancing patch.

  ● Jim Breen <j.breen at csse dot monash dot edu dot au> for creating and
    maintaining the Japanese-English dictionary files and xjdic,

  ● The Glade people, for making my job easier,

  ● People who write free software. You know who you are!