Bloggin’ it up

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.