-----------------------------------------------------------------------
                            Dictionary
                       (c) 2001 by CFF-Soft
-----------------------------------------------------------------------

-----------------------------------------------------------------------
                     Dictionary quick reference
-----------------------------------------------------------------------

-----------------------------------------------------------------------
1. Installation
-----------------------------------------------------------------------
1. Copy the dic.b9k file into your usual b9k directory.
2. Copy the dictionary file(s) into the dictionary directory/directories of
your choice.
3. Enter the dictionary details into the dic.cfg file (described below).
4. Run dic.b9k. The installed dictionaries will now appear in the menu.

! Note that installing into internal memory considerably speeds up searches.
In experiment I noticed factors of 3-4 times faster. However dictionaries
might fill up too much of that valuable resource, so I do not recommend it,
except for rather small dictionaries.

! Note that transferring dictionaries might need some time. Or to be more
specific the bigger ones (1.5 Mb) took me up to 6 hours to get onto the
Communicator!

-----------------------------------------------------------------------
2. The dic.cfg file
-----------------------------------------------------------------------
This config file tells the dictionary where to find it's data files. It is
the only part that has to be 'programmed'. No, it is really easy. You just
have to enter 3 lines (or 6 for a type 1 dictionary) like this:

<name of the dictionary>
<path to the dictionary>
<type of the dictionary>

Name is just what should appear in the menu. Pick what you like to find your
dictionary again.

Path is the path to your dictionary plus the basename of the dictionary
without the .dic extension.
The basename is defined this way: The name of the dictionary without the
.dic for type 0 dictionaries. For type 1 and two it is the front part of the
name. For example if the files are named "gerengaa.dic", "gerengab.dic",
"gerengac.dic", ... then the basename is "gereng".

For the type of the dictionary enter the correct type number. There is one
twist here: As type 1 dictionaries can be searched for both languages, but
only one at a time you need to specify a search direction for them. Usual
direction is denoted with type 1, reverse direction is denoted with type -1
to reflect the opposite searching.

Confused? Her is a sample dic.cfg file from me:

Numbers German <-> English
../Small Dictionaries/test
0
Small German -> English
../Medium GerEng/gereng
1
Small English -> German
../Medium GerEng/gereng
-1
Large German -> English
../Large GerEng/gereng
2

! Note the same path for entry 2 and 3. As type 1 dictionaries support 2
different 'subdictionaries' I use both, only distinguishing them by the 1/-1
typeset.

! When creating a dic.cfg file make sure that you do not enter any empty
lines at the end. In my above example the cursor has to be placed behind the
2 when saving without a line behind it. Do not return at the last line.

-----------------------------------------------------------------------
3. The dictionary formats
-----------------------------------------------------------------------

There are 3 types of dictionaries. Type 0, 1 and 2. All behave slightly
differently.

Type 0
------
This is the format for small dictionaries. Maybe even created on the
Communicator itself. Main goal here was an easy format. Usually they are
only 1 file, sometimes 2 or 3. Dictionaries of this type are always searched
in both directions. So if you enter "a" you will get all left and all right
words starting with "a" (until screen is full). All characters are allowed
for search that you can enter. Shortest word fragment length you can search
for is 1. Search is not case sensitive.

Type 1
------
This is the format for medium dictionaries. Main goal here was to save
space. Most of these dics are a bit slower however. Usually there are 676
files that form a dictionary. Dictionaries of this type are only searched in
one direction (for speed reasons). However they still contain the
information needed for the other direction. This second direction is enabled
by entering type -1 instead of type 1 in the dic.cfg file. Only characters
from 'a' to 'z' are allowed for search. Shortest word fragment length you
can search for is 1. Search is not case sensitive.

Type 2
------
This is the format for large dictionaries. Main goal here was to provide
speed for such a size. Still in worst case you migth need to wait minutes
for a result. Usually there are 676-700 files that form a dictionary.
Dictionaries of this type are only searched in one direction (for speed
reasons). Unlike type 0 or type 1 dics the reverse direction is not possile.
Thus type 2 dics 'waste' twice as much space. Only characters from 'a' to
'z' are allowed for search. Shortest word fragment length you can search for
is 2. Search is not case sensitive.

! Type 1 and 2 dictionaries might take huge ammounts of space on your HD (18
MB or more if you use a FAT16 on a 2GB drive). Don't worry. They will take
much less on the Communicator. This is normal.

-----------------------------------------------------------------------
3. Getting dictionaries
-----------------------------------------------------------------------

There should be a small (or maybe not so small by the time you read this)
collection of dictionaries at cff.kfank.net
Dictionaries uploaded are mostly those I use, plus submissions from others I
see as useful.
If you do not find what you look for you'll have to create on of your own.
Try http://www3.futureware.at/2dim.htm for data files to convert to this
dictionary (see below for details).


-----------------------------------------------------------------------
4. Dictionary format
-----------------------------------------------------------------------

General
-------
All dictionary formats share some similarities. First all dictionaries are
in DOS format. Not the Communicator text format. Also all files have to be
zipped with the z9p command of FreeBas9k.
When writing files also note that there are 3 special characters. TAB, '#'
and '-' (the long one on the Communicator, not the short PC version).

The usage of the 3 is as follows:

TAB, - : Both signs are used to separate the two sides of a dictionary. The
reason there are two different symbols is that the TAB character (the
'natural' choice) cannot be entered into a DOS file on the Communicator. So
a second, unusual, symbol was taken as well to enable creation of (small)
dictionaries on the phone.

# : This character is used to denote an additional file. To explain it I
have to talk a bit more about the creation of this program: In the early
stages of developing this dictionary software I noticed that bas9k (and most
communicator apps) can only support a certain file size. Everything bigger
will crash the device. I am not sure where that barrier is, but 30-35k is
still possible, 50 is certainly not. Seems to be about the size of file
Notepad on a Win9x PC can open. But of course it happens that a dictionary
file grows larger then that. Even for the distributed files of type 1 & 2.
So the # sign was invented to concatenate files. The usage is this. At the
end of the file you want to link to another one enter a line with only the #
in it. Then in the next line enter the filename of the next dictionary.
Something like this:

#
next.dic

Pretty simple, no?

Another restriction is that either side of the dictionary (the keyword and
the description) may only have a length of 64 total. Or to be more precise
2*32 letters. Everything that does not fit into 2 lines will be discarded.
If you need more data split it up into 2 entries.
I think that is pretty much all. Now to the differences between the 3
formats:

Type 0
------

The most simple format. It only has one file (or more if they are linked
with the # symbol). All files are searched through. Just create as decribed
above.
Note that these dictionaries are searched in both ways, so only one term per
side should be used. If there are more then one like this
abermalig afresh, again, all over again, anew
split them up into 4 separate lines:
abermalig afresh
abermalig again
abermalig all over again
abermalig anew
Also note that there should be no special characters in the file that cannot
be created on your Communicator keyboard. You will be unable to search for
those. I'd strongly recommend to stick to the 26 letters or numbers.

Type 1
------

Probably the most complicated format. Here you need to create 676 subfiles
(or some more if linked again). Give them a 6 character name like gereng for
an German-English dictionary. Then append to this basename every combination
of 2 letters. So you get gerengaa.dic, gerengab.dic, gerengac.dic, ...,
gerengaz.dic. Then gerenga.dic, gerengbb.dic, ... until you reach
gerengzz.dic. I am sorry it is this complicated, but it was impossible to
get a decent speed without this structure.
Now a medium dictionary has to be devided into these files as follows. Every
German word (to stick with the example) that starts wih 'a' and is
translated into an English word that starts with 'a' is put into
gerengaa.dic.
Like the pair "Abenteuer - adventure".
Similar a "rauben - plunder" would be put into gerengrp.dic
So the right filename is determined by the first letter of the key and the
first letter of the translation.
Note again that these dictionaries can be searched in 2 directions. So you
have to split terms like described for type 0 dictionaries.
Also note that there should be no special characters in the file that cannot
be created on your Communicator keyboard. You will be unable to search for
those. I'd strongly recommend to stick to the 26 letters or numbers. Note
that the fist character has to be a letter.
PS: don't forget to zip all the files at the end.

Type 2
------

Type 2 is almost identical to type 1 when you look at the files. Again you
need to create 676 subfiles (or some more if linked). Again they are name
with 6 character name like gereng for an German-English dictionary. Then
append to this basename every combination of 2 letters. So you get
gerengaa.dic, gerengab.dic, gerengac.dic, ..., gerengaz.dic. Then
gerenga.dic, gerengbb.dic, ... until you reach gerengzz.dic. I am sorry it
is this complicated, but it was impossible to get a decent speed without
this structure.
However the distribution of data is different for large dics:
Every German word (to stick with the example) that starts with 'ab' is put
into gerengab.dic.
Like the pair "Abenteuer - adventure".
Similar a "rauben - plunder" would be put into gerengra.dic
So the right file is always the first 2 letters of the keyword.
Note again that these dictionaries are only searched in 1 direction. As a
result you do not need to split up the definition side.
A line like
abermalig afresh, again, all over again, anew
would be perfect here, no need to split up.
Also note that there should be no special characters in the key half (left
half) that cannot be created on your Communicator keyboard. You will be
unable to search for those. I'd strongly recommend to stick to the 26
letters or numbers. Note that the first 2 characters of the key have to be
letters. It it however possible to use special chars in the description part
of an entry without problems.
Again don't forget to zip all the files at the end.

-----------------------------------------------------------------------
4. Utils
-----------------------------------------------------------------------

As you should know by now creating a type 1 or 2 dictionary is a pain. This
was of course also noticed by me. As a result I did some C++ files and a b9k
file that easens stuff a bit. All these files are quick hacks. They are
neither good, nor efficient nor userfriendly nor anything. So don't kill me
for em, ok?
Files are available in c++ sourcecode and windows console executable format.
The files do this:

General files and Quick dictionary related ones:
------------------------------------------------
correct: Corrects some (all I encountered so far) of the sequences in the
Quick format. Like converting a "?" to "-".

convert: Converts some characters into enterable ones. Like an  to an e. Or
a  (that is an A with two dots above it in case you cannot read it) to
'Ae', the official German substitude. Full conversion modifies both sides,
the key and the description (for type 0 and 1 dics) while a partial
conversion only converts the key part.

splice: Converts a line like
abermalig afresh, again, all over again, anew
to 4 separate lines like this:
abermalig afresh
abermalig again
abermalig all over again
abermalig anew
Useful when doing type 0 or type 1 dictionaries.

Special files:
--------------
mkmed: Converts a medium sized dictionary into the 676 files needed for a
type 1 dictionary. Does not split up files that are bigger then 30k.
mklarge: Converts a big dictionary into the 676 files needed for a type 2
dictionary. Does not split up files that are bigger then 30k.

B9K files:
----------
zip: After entering the base name of a type 1 or 2 dictionary Zip will z9p
every possible 2 letter extension of that basename. This might need 30 mins
or more. Zip will not zip any additional linked files. You have to do that
yourself.

-----------------------------------------------------------------------
5. Thanks...
-----------------------------------------------------------------------

Thanks go to Yellow Computing, http://www.yellow.de/ for creating
Pro'Lingua. They made me realize how useful such a software might be.
Again thanks go to Yellow Computing for only doing an English-German
dictionary. Also tnx for making that one such expensive that I could not
afford it. Both that facts made me consider doing my own dictionary system.
Big thanks go to Conrad, http://www.conrad.uk.net/, for creating the great
tool FreeBas9k. Could not have done it without him as Nokia did not send me
a SDK so far :(
I also want to thank the IDP, the Internet Dictionary Project located at
http://www.june29.com/IDP/ for their dictionaries. Those served me very well
when testing this program.
Big thanks go to Mauro Vezzosi for answering multiple of my questions on
news://9k.apps.bas9k. Without him the program would be a lot slower and
bigger.
A thank you also goes to Alex Komissarov, same newsgroup, for ponting me to
other dictionary resources then IDP, finally leading me to Futureware.
Huge thanks also go to said Futureware and their Quick dictionary
(http://www3.futureware.at/quick.htm). Most of my dictionaries are converted
versions of theirs.

Hmmm... Hope I did not forget anyone. Sorry if I did - no bad thoughts in
it.

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

General License for Non-Commercial Use
All software presented is copyright CFF-Soft 1993-2001
(http://cff.kfrank.net).
You may freely use this software for non-commercial purposes.
It may not be used for commercial purposes without an additional license.
If you distribute any copies, you must include this file and these
conditions must apply to the recipient.
No warranty of fitness for any purpose whatever is given, intended, or
implied.
You use this software entirely at your own risk. If you choose to use it, by
your actions you acknowledge that any consequential damage whatever is your
responsibility, not mine.

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