This last term at University has been pretty busy. That's to be expected I guess since it's now my final year but I've been busy with my final year masters project (a particle physics project in collaboration with BaBar) and a course in high performance computing where I've learned everything from SWIG to OpenMP and MPI. My interest was so piqued by the HPC stuff that I've decided that I am going to focus my PhD on that area, now I just need to find somewhere that will take me :)

Anyway, that's the reason I've been somewhat absent from KDE recently. However, now it's the Christmas break and while I do have some Uni work to do, I've got some time for KDE stuff, particularly for KSquares which has unfortunately been almost unchanged since KDE 4.0.0. I'm just about to start work on a full AI system for it. Up until now, the AI had two modes, one which just moves randomly (hardly fun to play against) and another which only takes moves which are immediately the 'least damaging'. Neither of these modes have any sort of forward planning and so I am planning on implementing a simple decision-tree type design to allow the AI to be perfect (this is possible in squares since it is a very closed game).

In related news, I've started using KDevelop 4 (I have been building it for a while now but had been experiencing crashes - these now have mostly stopped). I remember using KDevelop 3 previously and while it was a very good IDE, I couldn't seem to use it for anything more than automating tasks (configuring, building, searching). KDevelop 4, however is a different story. If any of you have been following David Nolden's blog you'll have seen sime of the nice new features it brings. It's more than just auto-completion, it really does allow you to browse your code like a semantically sensible web-site. Your mouse never has to leave the text-area.

On an unrelated note and for those who care, I've also been doing a small bit of work (mostly minor optimisations, documentation and the CMake buildsystem) on my brother's recent project. It's basically a framework to allow the use of Qt and OGRE in the same application (so that a game could, e.g. use Qt to display the GUI, menus etc.). It's called QtOgre and is now available as an OGRE Addon. It was designed to be used in his game project/voxel rendering system Thermite 3D.

Despite the headline, this is a topic which may well be very boring to many people, but if you have no fear then read on (especially if you like elephants)...

You probably all remember how with the release of Qt4, Trolltech changed the way they recommended people to #include their classes. Previously one would include the header file describing QDir with #include <qdir.h> but with Qt4 it was changed such that one could do #include <QDir>. That is, if you wanted to include the header for a class you could simply put the classname between the pointy brackets (well actually I think it's recommended to put modulename/classname in there which means you have to look up which module the class is in, but let's ignore that for now). This makes it very easy to know how to include the stuff you need.

So, in the run-up to KDE4 there was much discussion about whether KDE should do the same. Some people were against it but it was decided that it doesn't hurt to allow these 'forwarding includes' since the normal includes are still there (the forwarding includes only #include the real headers themselves). Now, it was while working on a new highscore management system for kdegames (I'll probably blog about that later, you're not getting away that easily :D) that I noticed that in our apidox at http://api.kde.org we're still telling people to use the old include style. So, I looked at the doxygen manual and found that it has a feature to specify what the include file for any class should look like (you can see it here and there's also one for namespaces/structs and the like here). Armed with this knowledge I set about updating the kdelibs documentation to use it. It's a simple case of adding, for example:

\class KScoreManager kscoremanager.h <KScoreManager>

to the documentation block for the class. This makes the difference between this include and this one (see that #include line in the grey box near the top). The problem is, there's loads of classes to do this to and for each class (unfortunately there's sometimes more than one class in a header file) you've got to check whether there's a forwarding include for it (I guess internal classes don't need forwarding includes). In fact, if you download the tarball of the documentation for kdelibs from http://api.kde.org and make the following command from the root directory

find . -regex ".*\.html" -not \( -regex ".*source\.html" \) -not \( -regex ".*_8h\.html" \) -not \( -regex ".*_8cpp\.html" \) -exec grep -l --regexp=".*#include &amp;lt;<.*\..*\..*&lt;/a&gt;&amp;gt;&lt;/code&gt;.*" '{}' \; | wc -l

you'll find that there are about one and a half thousand classes this needs to be done to. That's a lot to do manually and given the nature of the changes to be made, difficult to do programatically. The good news is that if you call this command (which is sorta the opposite of the other one but without the wc -l)

find . -regex ".*\.html" -not \( -regex ".*source\.html" \) -not \( -regex ".*_8h\.html" \) -not \( -regex ".*_8cpp\.html" \) -exec grep -l --regexp=".*#include &amp;lt;<.*\..*[^.].&lt;/a&gt;&amp;gt;&lt;/code&gt;.*" '{}' \;

you'll see that there's already some classes doing it properly (Nepomuk, DNSSD and KFadeWidgetEffect).

Now, unless someone can think of a way of converting all the documentation automatically then all I can ask is that the next time you're doing some work on a library class, firstly make sure you're installing forwarding headers (preferably 1 per class even if both forwarding headers forward to the same real header) and secondly just add the \class ... line to the class documentation block and make the world a more attractive looking place.

P.S. I'd like to dedicate this post to Jesper K. Pedersen, the author of KRegExpEditor without which this post would not have been possible.

P.P.S. Okay, so I lied about the elephants but if you do a search and replace with "class"→"elephant" this post is a lot more exciting.

After my post a few days ago I recieved an email from Thomas Strehl at Trolltech who kindly explained a few points about the new assistant to me. It seems it's already more powerful than I thought. Instead of having to manually load the 'help collection' into assistant, one can pass a command line argument and load a specific help collection, you can then specify in that help collection the window icon, window title etc. and this way it would be very easy to create a "KDE API browser". It's as simple as doing

assistant -collectionfile kdelibs.qhc

from the directory where kdelibs.qhc is located. Given the currently lacking documentation, I'm not sure how to set the icon etc. but it WILL be possible.

Thomas also hinted that Trolltech are working on a generator to create QHelp binaries directly from Doxygen output, making pretty much everyone's life easier. I guess the next step is to try to get docbook files loading :)

If we can get all that working nicely, it might be worthwhile looking into porting/rewriting KHelpCenter to use the QHelp library. Does anyone know the current status of KHelpCenter? The last I remember, after my post a while back PhilRod and co. were working on it. Does it need a breath of fresh air?

The other benefit of using QHelp would be that once docbook files are loaded in, it would be possible to query the database from within applications and display help in 'WhatsThis' hints, which, as I remember was one of the big points that we mentioned at the doc meeting a few months back. Another use-case would be KDevelop displaying apidocs for functions more easily.

I think that QHelp will provide us with an excellent opportunity to revamp our documentation system thanks to Trolltech once again thinking about what their users want and doing the dirty work in writing the library.

Yesterday in the #kde-edu IRC channel, I witnessed the following conversation:

<piacentini> Another guy was consterned when I told you about KEduca not being in 4.0
<piacentini> He says he used it already for test with more than 45,000 students
<annma> oh
<annma> really?
<piacentini> And he changed his lecture when I told you this
<annma> :(
<piacentini> Gonna tell people that they need to colaborate, participate, or products can die
<annma> yes
<annma> whenever we looked at KEduca it did not work
<piacentini> I hinted (he works on a government) that he could even sponsor someone to work on it
<annma> but if we had use cases we would have fix it
<piacentini> Yes, I asked him for a list of things he likes, things he does not like, what he uses
<piacentini> And we talked a bit about it
<piacentini> He says (really) that he estimates that the state has saved R$ 15.000 in printing when he switched to KEduca tests
<piacentini> That is about U$10.000
<piacentini> per quarter
<piacentini> Notice that these are tests applied on free courses to a poor community, where they train people in free software and also in other stuff like mechanics, cooking, etc
<piacentini> So for this sort of feedback events like this are good imo, hopefully he will get back to me, and we can use this story to motivate someone to port KEduca to KDE4, and address its shortcomings. I got moved, but my plate is more than full for now :)

And well, I can say that this story did motivate me and I immediately started work on porting KEduca to KDE4. Now somehow, it had managed to evade any sort of porting effort thusfar so my work was more than cut out for me.

However, a day later and I've got the main application compiling and here's the proof:

As you can see, the menubars are a bit screwed (in fact the Settings and File menus don't even do anything) but that's all just a matter of time I'm sure.

Now of course, it's too late for KDE 4.0 but I'll try to get it in shape for 4.1 and make some people in poor communities happy :D

Recently I've been working on some library classes for the KDE4 Games module. Firstly a high score table system and more recently extending Mauricio Piacentini's KThemeSelector to use KNewStuff2 and make it usable by any game in the module.

This is the first time I've worked on any sort public API so it was interesting to see the way I do it compared to the rest of KDE/Qt.

Now I've never actually used Ruby. All I've done is read a few articles on it and look at a tutorial or two. I can't remember anything substantial about the language but the one thing that has stuck in my mind about it is it's design philosophy that is most often talked about. That is the way that it caters for the majority of uses by default. By that I mean most classes that are ever written will, for 90% of the time, only be used in one specific way. With maybe a few lines of code that are the same every time the class is used. It is only 10% of the time that the class is used in a way that is out of the ordinary. Because of this rule, API should be tailored towards making it really easy for the 90% of people who only want to do basic things.

Now this sounds like very good philosophy to have when writing an API which is providing an easy way to implement a highscore table or a theme loader. Most tasks should be possible in three lines of code and only the unusual tasks (like custom score fields or loading themes from a different directory) should require more. I think I achieved that with KScoreDialog.

Incidentally, hello PlanetKDE.org! I'm Matt Williams (milliams on IRC/SVN). I've been actively hacking KDE for about 6 months (though I've been helping out with various other bits for a while before that) now and I'm currently working on kdegames and doing a little bit of work on Plasma.