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 ) 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:
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
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)
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.
Yesterday we held our student day in #kdegames. It was a chance for all the students who applied for GSoC projects related to KDE Games to come meet our community, to give us a chance to meet them and to let them ask any questions they had about GSoC or KDE Games in general.
It was a great success, we had at least 10 students in total (out of about 20 applications) come along at varying points throughout the day most of whom really took part, asking questions and just chatting away with the other students and the regulars. We even had one student ask it he was allowed to do his project even if he wasn’t chosen. “Of course!” we said.
In previous years we haven’t had any KDE Games projects at all but this year with so many excellent applications, we’d really like to see some of them chosen. So, any mentors reading: be sure to take a look at the games related proposals.
I’d like to thanks Josef Spillner for being my co-coordinator on the day and Eugene Trounev for coming up with the idea and planning it all. Thanks guys!
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.
Finally, Qt (in 4.4) has got a new documentation viewer and library. While playing around with it and reading the documentation to try to get the Qt apidocs working, I realised that it wouldn’t be too hard to get the kdelibs (and other modules’) documentation loading in it. After a bit of playing around with KDE’s doxygen scripts, I got something looking a bit like this:
Now, I know it’s not the prettiest layout but it’s early days yet. To try it out yourself, download the patch from http://milliams.com/uploads/qhelpkdelibs.diff.tar.bz2 and apply it to your base kdelibs directory. Then execute the following commands (of course, you need a Qt 4.4 snapshot):
cd doc/api
./doxygen-qhelp.sh ../../
cd kdelibs-apidocs
qcollectiongenerator kdelibs.qhcp -o kdelibs.qhc
Both the doxygen-qhelp.sh and qcollectiongenerator commands will take quite a while to do their stuff, so be patient. You’ll probably also get a load of warnings from qcollectiongenerator since the file list was generated from an oldish checkout. Once the kdelibs.qch file has been created (it will be about 90 MB), open the assistant from Qt 4.4, go to “Edit → Preferences… → Documentation” then “Add → From local file system…” and select the kdelibs.qch file from the doc/api/kdelibs-apidocs directory. You may have to close and open assistant to get the collection to show up in the left-hand menu. But once it is, searching and the rest should mostly work.
Now, the file list was generated by a script but all the rest was hand-written. Ideally, all these files should be fully automated, perhaps by extracting some of the information from the .tag files. Once the system is made better and more automated, perhaps this sort of thing should be available for download from api.kde.org to replace (or augument) the current, static HTML download. I’ll look to getting the rest of the modules working (should be quite easy now) and then I’ll try to get some application handbook docbook files loading in.
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
This is a more or less rambling post based on thoughts which have been sitting around at the back of my mind ever since I started writing my KSquares documentation. During a brief discussion about KHelpCenter on IRC an hour ago it all came spectacularly bursting to the surface so I thought I’d write it all down before anything else bursts.
Program documentation, the stuff you get from “Help -> Foo Handbook…” is an invaluable source of information for users. Despite our best efforts, none of our KDE programs are entirely self explanatory for everyone. I, for example, almost always need to take a look at the docs for most of the games in kdegames when I first play them simply to discover the rules. Also random numbers in the statusbar are another big reason for me going to the documentation simply to find out if a “5″ is a good or bad thing.
Unfortunately, despite all the excellent work that’s been going on in most of KDE to revitalise and improve for 4.0, there are parts which have been left by the wayside, often because they are kdelibs hackers’ side projects. User documentation seems to be one of these sections. Now I don’t mean to demean the work of the people who have been working for the last two years to keep the documentation system working as much as it is, but in its current state it’s far from release ready.
I could see the dangerous thing happening and I was slightly worried that it was going to be the case that the documentation system was simply going to be given a ’shot of adrenalin’ to get it up and running for the KDE 4.0 release. I feel that doing that would be a waste of this perfect chance we have here with the new KDE release series to make a fresh start and change the paradigms we’re using for all our favourite desktop environment (that’s KDE by the way ).
Looking at KHC (KHelpCenter) 3 it’s always seemed to have a bit of an ‘evolved purpose’ where new ideas and features have been added to it without any real statement of purpose to the application.
Looking at it now it seems to offer the following:
KDE Application docs
Portal for info:/ and/or man:/ KIO slaves
General KDE help
Documentation for 3rd party libraries (doxygen, Qt etc.) (Maybe this is a SuSE addition?)
Searching (via htdig i believe)
Now that’s great and it’s a good place to go for documentation but I personally think it needs a little bit of a rethink. Both from a user interface presentation point of view and from a ‘purpose’ point of view.
First, the KDE specific information: Now I’m not going to suggest that we shouldn’t have the application manuals available (that would be crazy) so of course, we’d still need those sorted as they currently are (in the same way as they are in the KMenu. It makes sense). But what else would a user want from a ‘help centre’? An introduction to KDE, yes. A general pointer to further reading on websites, yes. But the way I see it is that people only go looking for help when they have a problem. And what problems do people have? Well, sit in #kde for a few hours and you’ll get an idea. They aren’t generally problems that can be solved with just one application, or alternatively they have no idea which application would solve the problem. Maybe they want to change their cursor theme or maybe they want to make the default application for text files to be KWord. Each of these are ‘tasks’ which require a number of steps to complete but once you’ve done it once, it sticks in you mind. Or so you would hope anyway . It is for this reason that I think we need a sort of ‘tutorial’ section. A set of walkthroughs for common tasks such as these which the user can easily find via the “Help” icon on their desktop.
That’s it.
That’s all the user should be presented with when they click the “Help” icon. Application manuals and how to perform certain tasks. They don’t care about ‘doxygen’ or ‘iptables’ so why give them a list of 20 different items to scan through? I’ve no problem with KDE having a universal documentation viewer for browsing and searching info or man documentation but that shouldn’t be KHC by default.
Hmm, that all came across as a bit ‘complainy’ but I really do think we need to simplify rather that keep on expanding. Now I know we can’t stop distros messing with our software but we’ve got to do out part too.
Okay, so that was my ‘design philosophy’ brain burstage, but before I go I had one more thought. When the user does click on “Help -> Foo Handbook” do they really need or want to see the whole of KDE’s documentation? I think maybe a lightweight wrapper around help:/ which just opens that application’s documentation would be nice. KHC is often slow to start and people who want help often want it NOW.
Well I’m about to have a little meeting with a few people who agree that the documentation for KDE 4.0 needs to be fixed/changed (some more or less radical) so hopefully soon we’ll see some results.
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.
The four exams I had at the beginning of this term didn’t go too badly. Maths I was much easier than I had feared which is just as well since that meant that I had more time to try the Maths II exam. Maths II was just a baaad exam. I mean everyone found it difficult but it was just nasty. Fortunately Geophysics and Physics of Power Generation went spiffingly.
In all round good news all the lectures for this year are now finished so now I’ve about three weeks until my next set of exams start. In even better news, Lab for this year is over which is just as well since the Lab I just finished was an ‘Astronomy’ lab which involved looking through a telescope, through a mirror on the other side of the room, at a light box above my head with a slide with a picture of Saturn in it. It was probably the most tedious and least worthwhile lab ever.
Now it’s simply a case of winning the upcoming exams to remain on the MPhys course.
Woo, well that’s another university term over. It’s been a pretty mental one with more work than was really fair.
However, I can’t really complain since in about 6 hours I’m leaving to go on a skiing holiday in France. I’m going to Les Gets near the Swiss border and looking at the weather, it’s going to be pretty cold! I haven’t skied in about three years so hopefully I can still remember how to do it.
KSquares 0.1
) 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:
