== Summary (jargon)==

The vocabulary trainer is a php based web-application,
using the WikiData XML API provided by Omegawiki
to provide a flashcard system for training vocabulary.

The default setup looks up data across the internet from
omegawiki.org.

Data is fetched lazily as-needed, and then cached locally,
on a per-exercise basis.

Have fun, and good luck learning! 

== INSTALL ==

Requirements:
* PHP 5.2 or later
* mysql 
* pear::auth
* pear::db
* php cURL library

Checkout from svn:
	svn checkout http://svn.wikimedia.org/svnroot/mediawiki/trunk/extensions/Wikidata/util/voctrain

Create a new database for trainer, set it up using
	mysql (your settings here) < trainer.sql

(Ensure your database supports utf-8.)

Create settings
	cp settings.php.example settings.php    

And edit for your local situation (mysql info needs to be provided twice for now... sorry).
Typically only the mysql info needs to be changed anyway.

Point users to trainer.php to use.

== Special extra parameters ==

Martin asked if we could link people to a different default dataset.
So I added that in.

for instance
trainer.php?defaultCollection=376322

Will currently switch the default question-set to Destinazione Italia on startup.
To get a list of valid id's you can provide at any one moment in time, read the following, which should be fairly parsable:

	http://www.omegawiki.org/api.php?action=wikidata&wdtype=listCollections

(too lazy to write a stylesheet)

<collection id="145263">
	<name dmid="6448">Swadesh list</name>
	<count>325</count>
</collection>

Says the collection id for the swadesh list is 145263, (and incidentally also
mentions that there are 325 items, and you can get the name translated into other languages 
using the dmid 6448...more on that some other time)

right now all we want to know is that we can link people to
	trainer.php?defaultCollection=1452638

Remember to make that a proper URL :-P . For instance, to try this out on the omegawiki.org server, you do:

	http://www.omegawiki.org/extensions/Wikidata/util/voctrain/trainer.php?defaultCollection=1452638


Vocabulary viewer: 

trainer.php?action=vocview&dmid=3834&questionLanguages=eng,nld&answerLangauges=deu,jpn&language_code=nl

action=vocview		select vocabulary viewer mode
dmid			view word under this defined meaning id. (see omegawiki I documentation for more details)
questionLanguages	comma separated list of languages to translate from (iso 639-3)
answerLanguages		comma separated list of languages to translate to (iso 639-3)
language_code		ui language, (modded iso 639-1 !!!)

Note that the ui language uses mediawiki language codes, rather than iso 639-3! This
is because the translation project that translates our UI uses those, and they're
not set up to support the newer standard yet. :-(


== Code reading ==


- Not proper MVC pattern IMO, but still organised back-end, control, and output into separate files.
trainer.php is entry point, sets things up, then calls Controller->execute();

- Most of the time is spent in Controller->run_exercise().

- Expensive xml requests from the wikidata api are executed lazily on
an as-needed basis, and the resulting data is cached locally. This
is done on a per-exercise basis. (If you start a new exercise,
the data is fetched again). This is a reasonable compromise. 
You can still benefit from improvements to the database over time,
but at the same time there is some speedup gain, and the
exercise remains stable until it's finished. (if someone
changes an entry after a particular question has been asked
or shown, this doesn't count towards the current exercise)

- functions.php contains a lot of legacy code, should clean that
up sometime.

== Terminology ==

Variable names and comments might refer to things
specific to omegawiki.

dm: Defined Meaning: The basic concept around which Omegawiki is built.
	A defined meaning is a concept that is understood by some
	human being somewhere. A defined meaning is expressed using
	an expression (of one or more words) in at least one language.
	A defined meaning could be specific to a particular language
	, but so far, all defined meanings I've
	seen have been expressible in multiple (in fact all) languages.
	I'm just coding this thing, don't bother me with linguistic
	theory today! :-P
dmid: Defined Meaning ID: Each defined meaning in omegawiki 1 is assigned
	a unique number. (in omegawiki II this will be a Unique Universal ID
	string, but that's future). 

	For instance, the word "duty" in english, in the meaning of 
	"That which one is morally or legally obligated to do." , has a
	defined meaning id of 7534. We can use this to look up translations
	in Afrikaans, Castillian, Catalan, Danish, Dutch, etc ...
	( http://www.omegawiki.org/index.php?title=DefinedMeaning:duty%20(7534)&dataset=uw )

== quick notes: ==

At next major db change, also take along changing questionlanguage and answerlanguage to
questionlanguge_s_ and answerlanguage_s_ (or just add this info into the exercise xml instead)