[kde-edu]: kvtml

[Frederik Gladhorn]

Hi all!
Hi especially Jeremy :)

As we all seem to agree about kvtml being somewhat awkward, it's time to redo 
it. Since Jeremy offered his help and interest, I'll try to sum up some 
concerns and also attach an example doc, the latest version of kvtml which 
Peter Hedlund and I pretty much worked out. XML experts, join us ;) also a 
real dtd would be great.

Since many of the features are not yet supported by libkdeedu, that has to be 
changed significantly. It's no small task.
I already played around with it, but I do not have the time nor the knowledge 
to rewrite it quickly. (E.g. I did not know about the d-pointer concept to 
keep ABI compatiblity etc...)

I'll still be glad to work on it, but not alone, form now on. *big grin*

So this is a summary of problems and concerns that came up before.
Some of the stuff only concerns KVocTrain, but all apps using the lib will 
gain something from cleaner lib code.

Quote Peter (different e-mails):
> One major issue with the current kvtml format (IMHO) is that it's bad xml.
> It relies very heavily on attributes where child elements would be better
> for parsing and readability
> (http://www.w3schools.com/xml/xml_attributes.asp). Elements and attributes
> should also have proper tag names, not just a single letter. All elements
> should probably also have unique tags regardless of parent element for more
> efficient parsing (Now e.g. <e> is used with several different parents and
> different meanings.
>
> For future expansion I would also like to add the tags <image> and <sound>
> to vocabulary entries. They should both take an URL for an image or sound
> file.


> I would like to add a <sizehint> tag  as a child to <entry> for storing row
> heights. I know KVocTrain has always used fixed row heights, but I would
> like more flexibility at least for KWordQuiz. See
> http://bugs.kde.org/show_bug.cgi?id=82460.

> > So we simply call it kvtml2 ? Other suggestions? I guess we might as
> > well. That is easier than I thought. I don't care for writing the old
> > docs. It is enough work supporting reading, but not that bad either.
>
> I think we can keep the file extension. I was talking about the source
> files in svn. I think the code should send a kvtml file to the new reader
> first. If the version="2" attribute is not found, the new reader returns an
> appropriate error and the file gets sent to the old reader.

Quoting myself:
> The concept of original language + x translations is not really great for
> apps that actually can have more than two languages. So far it is never
> possible to practice language 2 with language 3.
> This is intersting for people learing eg. Chinese or Japanese, to have some
> sort of signs and maybe traditional and simplified and be able to practice
> them in respect to each other.
> See bug #93446 (https://bugs.kde.org/show_bug.cgi?id=93446).
>
> Another thing is that this concept blows up the code unnecessarily and in a
> ugly way. Because everywhere there is special treatment for original, than
> an iteration over all translations.
> KVocTrain and also the lib we have about thousand places like (rather small
> example of duplicate code directly next to each other):
>
> (from keduvocdocument.cpp)
> if (sort_column == 0)
>         return e1.original().toLower() < e2.original().toLower();
>       else
>         return e1.translation(sort_column).toLower() <
> e2.translation(sort_column).toLower();
>
> This will become:
> return e1.translation(sort_column).toLower() <
> e2.translation(sort_column).toLower();

> The concept of original language + x translations is not really great for
> apps that actually can have more than two languages. So far it is never
> possible to practice language 2 with language 3.
> This is intersting for people learing eg. Chinese or Japanese, to have some
> sort of signs and maybe traditional and simplified and be able to practice
> them in respect to each other.
> See bug #93446 (https://bugs.kde.org/show_bug.cgi?id=93446).
>
> Another thing is that this concept blows up the code unnecessarily and in a
> ugly way. Because everywhere there is special treatment for original, than
> an iteration over all translations.
> KVocTrain and also the lib we have about thousand places like (rather small
> example of duplicate code directly next to each other):
>
> (from keduvocdocument.cpp)
> if (sort_column == 0)
>         return e1.original().toLower() < e2.original().toLower();
>       else
>         return e1.translation(sort_column).toLower() <
> e2.translation(sort_column).toLower();
>
> This will become:
> return e1.translation(sort_column).toLower() <
> e2.translation(sort_column).toLower();

The other big change is the use of lessons. To make KEduVocDocument a little 
cleaner I would like to remove all references to lessons and vocabulary 
entries, exept having it contain a single lesson.

Lessons would actually contain their vocabulary and can contain sublessons.
This makes organization much nicer and removes many special case treatment as 
well.

Types should actually be a real class to fix bug #138488, that it was 
impossible to query for nouns and have noun:male/femal/nutral included.

The multiple choice class was a really weird container for five QString. I'd 
replace it with a QStringList which is more flexible and smaller. This also 
get's rid of the fixed maximum of multiple choice answers.

Also I'd like to drop built in usages/types/tenses.
So far there are constants defining these in a rather ugly way and they cannot 
be deleted. My suggestion is to create them like normal user defined 
usages/types/tenses at the time the document is created and from there on let 
the user do with them what he wants.


Internally:
-get rid of everything original() and the like - this is pure code 
duplication! Also see bug #93446 
(https://bugs.kde.org/show_bug.cgi?id=93446).
-move all lesson stuff into the lesson class
-move all entry/expression stuff into the lesson class
-create a class translation inside the entry class, containing everything that 
is language specific (conjugation, article, the expression in the respective 
language)
-create a grading class inside the translation class to hold all grades (to 
the respective language, with a remark from which other language, to enable 
statistics)
-make many classes nicer (conjugation, article, ...)
After all this is done, redoing the actual reader/writer classes will be easy. 
There are also many places to optimize, but changing the internal classes 
should come first and can be done gradually.

I forgot probably a thousand issues, but they'll pop up, I'm sure of it.

Have a great day!
Frederik


PS: is there any reason for the name kdeeducore of the lib folder? I'd rather 
rename it to libkvtml/libvocabulary/... or something meaningfull.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: kvtml_empty_sample.kvtml
Type: text/x-objcsrc
Size: 5128 bytes
Desc: not available
Url : http://mail.kde.org/pipermail/kde-edu/attachments/20070606/2b421f33/attachment.bin 
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
Url : http://mail.kde.org/pipermail/kde-edu/attachments/20070606/2b421f33/attachment.pgp