  General README file for kdrill  v6.2, August 24, 2003
     (by Philip Brown)

KDRILL REQUIRES the X Windowing System to run. Specifically, X11-R5 !! 
(or better).

This README file is a condensed overview of what the program does.
For installation instructions, and tweaking things, see the INSTALL file.

Otherwise, you can continue reading this file for the overview, or view the
"online" version with screenshots at

http://www.bolthole.com/kdrill/

These days, you're probably better off looking at the website.

kdrill quizzes you on [kanji/kana phrase/english] translations.
It can also be used as an electronic Japanese<->English dictionary.
For a more detailed summary, skip to "KDRILL SUMMARY", below

If you wish to drill yourself on just single hiragana or katakana letters,
check out the 'makedic' directory.

Kdrill supports an additional (and rather large!) dictionary: "edict".
Given the memory usage, the edict dictionary is optional.
If you do not choose to install it, kdrill will still work fine.
   
If you care about what has changed since older versions,you can read
the bottom of the "PATCHLIST" file. I recommend "tail -30 PATCHLIST"



 ************************************************************


             KDRILL SUMMARY
            ----------------

  Kdrill is a program to quiz folks on
   { english }       { english }
   { kanji   }  <->  { kanji   }
   { kana    }       { kana    }


It will quiz you on either the whole dictionary [around 6000 kanji?] 
OR specific kanji, that you hand-pick.
There are also other ways to narrow down which kanji you are quizzed on.


   For gruesome details, you should either read the manpage
       ("nroff -man kdrill.man | more" is the hard way)
       or go to the website, 




   --------------------------------------------------

REQUIREMENTS
************

KDRILL REQUIRES the X Windowing System to run. Specifically, X11 R5 !! 
(or better).

This is because MIT X11R4's Athena Widgets do not handle 16-bit fonts
properly. If you happen to have a 16-bit capable libXaw, (or maybe if you
just grab and compile the R5 or R6 Xaw lib) you should be okay anyway.

It ALSO requires that you have a sane and proper kanji24 & kanji16 font.
Some strange sites have goofed up fonts in the distribution, where the
font index of a character is NOT the JIS reference.
IF this is the case, I suggest you get a new distribution of your
windowing system, and send a nasty note to your vendor.
If this is not within your power, then look in "readfile.c" for the
BROKENFONTS definition, and play with the number until things align.
(Untested by me, but methinks it should work)


ALSO NEEDED:

  I use the PD kanjidic file from ftp.monash.edu.au: I do not include
it, as it is 700K.
By permission of Jim, I do include a SHORTENED dictionary, "kanjidic".
You should replace it with the full one.
Some mirror sites are:
ftp.uwtc.washington.edu.
  (look in either pub/nihongo, or pub/Japanese/JimBreen), and also at
ftp.cdrom.com
  /pub/japanese/monash


------------------------------------------------------------
For quizzing on specific characters, create a "usefile".
There are multiple ways to do this.

One way is to hand-edit a file. You have to put one number per line, in hex,
at the beginning of the line. Anything after will be treated as a comment, so
you can notate the meaning of each kanji.

**OR**... you can use the search window to find kanji you care about, then
click on the "usefile" button there. Once you have more than 10, you can then
just enable usefile usage,in the options window,and go from there.
Your usefile collection should be saved when you quit the program by
pressing "Quit".



------------------------------------------------------------
DICTIONARY FORMAT:

This is documented in documents at the kanjidic site. But for quick 
reference;

The approximate format of any kanjidic file used should be:

kk 3333 .... Fxxx Gxxx Hxxx Nxxx Uxxx.... nnnn  nnnn  nn {english} {english}

Where kk is the 16-bit kanji value seen as two 8-bit vals.(MSB,LSB)
'....' is any char any number of times, except for things starting with
"F" or "G"

Fxxx is a frequency of use rating.
Gxxx is a grade level rating.

H, N, and U entries may or may not be present.

nn is 16-bit kana interpretation with spaces between different ones.
(annoyingly, there are a bunch of other strange 8-bit formatting issues I
 had to deal with, but if you care, you'll have to get the docs that come
 with the dictionary.)

There may be any number of {english} segments, also.
Note that the braces {} MUST be included there.

Unfortunately, "kanjidic" does not have english translations for some
entries, and does not have kana for others. Unless the program is in 
 -notallT mode, entries will be skiped if they do not have the required
information to display. 

TO CHANGE FONTS, startup files, etc, you can either edit the 'fallback'
resources in "init.c", or make up a resource file "KDrill", and stick it
in your local app-defaults file. (Or load them with xrdb)
Sample KDrill file included in the archive.


Adding new entries to the usefile is fairly simple. search through the
dictionary for potential entries, then use "xfd -fn kanji24" to check out
what the characters actually look like, to make sure.
OR... use the nifty new "search" feature!!! :-)
OR... play in order, and note down ones you need
OR... play in "logfile" mode, which will automatically output ones you
      missed to a logfile. This logfile will automatically be read in
      the next time you start play!


------------------------------------------------------------


  I hope this program can be used as an example of a well-written
Xwindows program. I now have just about everything a good program should
have. I hope. If you think of any possible improvements, whether they are
to do with coding, or just minor layout improvements, please let me know.

 Philip Brown
 phil@bolthole.com



Many thanks to the various users who have given me feedback.
Bug reports, and comments, are always welcome. If you want kdrill to get
better, send me an email!

SEE ALSO:

ftp://ftp.bolthole.com/kdrill/zidian.README
for information on how to use kdrill for Chinese learning
