Monthly Archives: February 2008

Building PDFs of documentation

Still working on that coursework project, I'm now building PDFs of the three pieces of documentation the application itself requires: the API reference, the source code listings and the user manual.

Using gtk-doc to build the API reference makes it quite easy to add something in the Makefile to build a PDF from the DocBook:

docs/reference/Makefile.am

I've put this at the bottom of the Makefile.am, and it's all working nicely, apart from the fact that distcheck (legitimately) complains about me redefining all-local. I can't find any other way to make it build the PDF while also building the normal docs with make docs, so my question here is: how do I make this implementation cleaner?

If anybody wants to use it, they'll need to install dblatex.

The next piece of documentation is the source code listing. This is completely custom, using source-highlight to make LaTeX files for each source file, and then pdflatex to build them into a PDF.

docs/source/Makefile.am

I'm quite pleased with the way this works, although I'm sure there will be better solutions out there. source-highlight deposits many LaTeX files in the build directory, which are then included in the PDF build by dint of being automatically concatenated together and included by a surrounding LaTeX file, project-name-source.tex.

docs/source/two-hundred-club-source.tex

Finally, the user manual also needs building into a PDF. This again uses dblatex, although it's a little more complex, as a PDF has to be built for each language directory in the help directory.

docs/help/Makefile.am

Hopefully some of that will be helpful to somebody in a similar situation, and I'd welcome any hints or pointers as to how to improve the implementations, as my automake powers are about as strong as a damp tissue.

Revamp, GTK+ apps on Windows and more documentation

I've just finished converting the site to use WordPress instead of the custom software I'd previously been using. It'd been getting too time-consuming to keep everything maintained and up-to-date with the latest things going on on the Internet, and I'd been reduced to making posts via phpMyAdmin due to various things breaking. Hopefully, this should be better, and a lot less hassle to keep running. I apologise if the transition has messed up the feed for anyone, but I've tried my hardest to redirect all the old URLs, so things should keep working as before.

Recently, I had to compile my computing coursework for Windows, as the person for whom it's written only uses Windows. Much to my delight, once I'd figured out the terminology and basic principles, getting it to cross-compile for Windows using MinGW was quite easy! Since I couldn't find much documentation on the process while doing it, I've written up the steps I took, and perhaps someone else will find them useful.

Last month, I also managed to write up some API documentation for totem-pl-parser, which has been on the to-do list for a little while. It was quite easy to get the hang of gtk-doc, too, and once I'd got started, the documentation got done quite quickly. If anyone's implementing anything using totem-pl-parser, I'd appreciate any feedback on the usefulness of the documentation, as it can always be improved.