Hi there,


before starting qvocab you should read this. This document describes
how it came about, how to use qvocab and how to reach me.


History:
========

I started developing qvocab almost by chance. Well, I've written a
similar project for Windoze some time before my transition to Linux
and just wanted to do some experiments with the Qt library. So I
remembered that project and designed the widgets as they could be
found in the Win version. After having achieved this and not knowing
what else to do ;-) I put life into the widgets and so it began...

I wasn't very good at programming that time (nor am I now) and so I
would do a lot of things in a different way nowadays.

Meanwhile Thomas Schultz <tststs@gmx.de> contributed a lot of patches,
in fact he was the only one who did the changes from 0.20.3 to 0.20.4
Thanks a lot, Thomas!


License:
========

QVocab is released under the terms of the GNU General Public License.
It is included in the COPYING file.


Databases:
==========

Records in QVocab have a fixed size and are subsequently written
into a file. Thus you can also concatenate two .qvo-Files and the
merging is done. You can also create a new `database' by simply
touch(1)ing a file that ends with `.qvo'

QVocab also supports MySQL databases (more or less). If you intend to
use this feature, please read the notes on MySQL. You'll find them in
the same directory as this README file.


How to use:
===========

Well, I hope QVocab is quite self explanatory, but here's a small
introduction on how to use it.

Installing QVocab:
------------------

Compiling should simply be done by a 

     ./configure

followed by
     
     make

and, to install it

     make install

If you want to try special parameters for the configure script (in
order to change the prefix-directory or to compile the MySQL-version)
simply type

     ./configure --help

Note: If Qt is installed and ./configure does not find it, try setting the
environment variable $QTDIR appropriately. ./configure will look for the
include files in $QTDIR/include and for the libraries in $QTDIR/lib.

Installing QVocab using RPM:
----------------------------

For rpm users, building qvocab should now be as simple as typing

     rpm -ta <qvocab-tarball>

rpm will create two files (qvocab-XXX.rpm and qvocab-convert-XXX.rpm) you
can install using "rpm -i <rpmfile>". If an earlier packaged version of
qvocab is present, you need to update it ("rpm -U <rpmfile>"). It is not yet
possible to build the MySQL-version of QVocab from the .spec file that comes
with the distribution.

This has been tested on SuSE 6.2 (i386) but should also work on RedHat and
most other rpm-based systems. If you experience problems with this way of
installing QVocab, please write to Thomas Schultz <tststs@gmx.de>.

Using QVocab:
-------------

If you start the program, you should see some buttons on the left
side, and two boxes on the right side. The lower box on the right side 
shows all `.qvo' files in the directory that is specified in the line
between both boxes. You can change the directory by editing this
field. Please note that only those files show up in the list you have
permission to alter (read/write).
If you don't already have a database you want to use, you can also
create a new one by means of the File-Menu. Select `Create new
database' there and type in the name. Please note that for the
qvo-version the same restrictions apply as for a file on the
respective filesystem. Names for MySQL databases are table names with
more constraints.
You can select a database by double-clicking on its name. The upper
box now gives you a summary of the number of words in the database.

Now you can click on `Input' in order to add new words. Both language
fields are compulsory but you can write anything you like (or
nothing) into the field for the remark. By default, the size of all
three fields must not exceed 200 (this can be changed in
fileio.h). The MySQL version has different limitations.

If you're courageous enough to face your computer ;-) you can click on 
the `Ask words' button.

=> Before the test can start you have to select the language you like
   the program to ask you.

Now the program asks you the words and you try to give the answer. You 
can also have a look at the statistics in the middle of the
window.

If you notice that there is a misspelled word in the database, just
press on the `Edit' button, that'll take you right to the word you're
being asked so that you can correct it.

A known word will move up one level (there are five of them (defined
in sourcecode)) and if you didn't know its meaning, it is moved to the 
first level again.

There is also an `Options' button that allows you to influence the way 
words are asked.

There are:


Insert/Overwrite: Should be obvious. You can also use the `Insert'-Key

Ask fragments: If this option is selected, the program splits the word 
               that is presented into parts, the comma is the token
               that divides the parts.
               For example:
                   a car, an automobile:  <your translation here>
               This would result in the program asking you 50% `a car' 
               and 50% `an automobile'
               You should keep in mind this when you add new words (i.e.,
	       try not to use a comma where it is not intended to separate
	       fragments)

Accept fragments: If you enable this option, you may answer only one of the
                  fragments. So if you're asked for `a car, an automobile',
		  you can only fill in one fragment, `a car' for example and
		  the word is regarded to be known. If you have enabled the
		  help option "Show stars and special characters" (see
		  below) QVocab automatically chooses the fragment that does
		  not include any `*'s. Thus, with this option, you can answer
		  `a car, ** **********', and it will be correct.

Distinguish case: Should be obvious.
A combobox:
   write the words: You'll have to write the words exactly as you
                    wrote them when they were added.
   oral test:       You don't write the words but just use the mouse
                    to indicate whether you knew them or you didn't
                    The left button means `ok' and the right one `no'
   words can be written and the mouse can be used, too: This enables
                    you to combine both modes, you don't waste your
                    time with writing words you know for sure but if
                    you don't know the correct spelling, you type them 
                    and let the program compare.

limit space: This limits the space to the length of the words. I
             really appreciate this because thus you can use the insert
             mode, jump with the arrow keys or the Home/End-keys and don't
	     have to care about the letters shifting to the right.

Show stars and special characters: This shows a word, for example
                    `happy about/with sb.' as `***** *****/**** sb.'
                    At the moment the substituted characters can only
                    be specified in the source code (see askformclass.cc)

Show some letters: x %   This will result in displaying a special
                    percentage of letters, `guess these words' becomes 
                    (with the `stars-help') `g**ss ***se* *o*d*' or
                    something like that.

If a word is in the fifth file, it can't climb any further. Yet you can 
move these words into a special file automatically, thus building up a 
file with well known words. Therefore you can use the `Move known
words from the 5th level into a new file'-option. The filename will be 
the same but a `.known.qvo' will be added instead of the simple `.qvo'

There is also the possibility to select special words and move or copy 
them into a separate file. Use the following options to do this. So
you can copy words you absolutely can't remember into a special
file. You can find the button to move them next to the Options button.

QVocab also remembers the date a word was last asked at. You can
specify a date, and all the words that haven't been asked from this day 
on until now are asked.

Yet this option is only valid for a specific level. If you want the
program to ask you words throughout the database, use the AutoAsk
feature. Here you can specify the number of days that must have
gone by since the word has been asked the last time.



If you want to change the words in the database, you can use the
`Edit' button. This shows you a window with most of the words
data. You can simply change a value, move around with the arrow
buttons (first, previous, next, last) and delete words.

The search is done by means of regular expressions, it can be forward
or backward, you can specify if the search should start at the
beginning (or at the end if you chose backward) or if the word you're
looking at the moment should be the initial word to start (as a matter 
of fact, the initial word is always the next word in the proper
direction). Furthermore there is the option that enables you to
perform case dependent or independent searches.


If you're looking at the main window again, you will notice the
combobox right beneath the `Edit' button. Here you can select the
level you want to be asked. The words of each level are contained in a 
`file'. I hope you don't mistake this with the database files that are 
`real' files.


Well, I think that's all to know...


Contact:
========

If you miss anything, in the program, the documentation or if you have 
other suggestions, criticism, feedback or anything else, feel free to
e-mail the authors at 

      tststs@gmx.de        (actual maintainer)
      jwieland@bigfoot.de  (original author)

Feedback is very much appreciated, don't hesitate to tell me your
experiences with qvocab.



Have fun,

Joachim Wieland
jwieland@bigfoot.de

