[kde-edu]: kvtml

[Jeremy Whiting]

Hello all, mostly kdeeducore library users (Peter, this means you ;)

Here's an update of what's going on in the library recently, and some proposed 
changes for any that don't watch the commit-filter :) .  This feels like a 
blog post, but if I just blog this, nobody will read it probably.

With Fredrik's guidance since kvoctrain is the app that uses all the features 
of kvtml file format, we have discussed some changes to kvtml xml structure, 
and have come to decide a couple things:

Firstly, we threw out the entries under lessons.  Partly because kanagram, and 
khangman don't care about lessons, but also so the library can support 
putting entries in multiple lessons.

Second, we renamed the conjugations in identifiers to what they really have 
been, personalpronouns.

Third, conjugations under entries are under translations and have a tense 
associated with them, as well as a type (irregular, regular).

Fourth, the library will support types and sub-types, so you can have nouns, 
verbs, adjectives, etc. but also have noun::male and noun::female, 
verb::regular, verb::irregular, etc.  This way applications can choose to 
quiz you on all verbs (including regular and irregular) or just irregular 
ones if that makes sense for the application.

The sample file from Frederik's e-mail can be seen with the above 
modifications in svn at kdeedu/libkdeedu/kdeeducore/kvtml_empty_sample.kvtml

I have most of the reader implemented, and hope to have it completed by the 
end of this weekend.  KEduVocDocument also is set to use kvtml2reader 
currently, and the reader itself has a fall-back mechanism to read old kvtml 
files using kvtmlreader.

I'll start a kvtml2 writer this week also and hope to be able to have enough 
support for the types of files kanagram and khangman use to write a test-app 
to read kvtml files and write them back out as kvtml2.  This will be able to 
be used to convert existing kvtml files that are in svn if desired (though 
the library can still read old kvtml files).

Anyway, enough status report.  The real reason for this e-mail is to ask about 
Frederik's idea of renaming kdeeducore to something more descriptive.  Maybe 
keduvocdocument since thats the main class apps actually use directly.  Let 
us know what you think.  Other suggestions are welcome.


Thanks,

Jeremy Whiting (jpwhiting)
  
On Wednesday 06 June 2007 07:45:53 am Frederik Gladhorn wrote:
> 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.