I’ve written a HTML::WikiConverter dialect for Google Code. The module, HTML::WikiConverter::GoogleCode, is now available on CPAN at http://search.cpan.org/~martykube/.
I wrote the module to support an open source project I’m working on. The module allows me to write my documentation in a good editor (OpenOffice in this case), save the document as HTML, convert it to Google Code wiki markup, and then post the file to my project wiki via svn. The main advantage is that I can also include the HTML documentation in the release file and thereby have one version of a document that is posted on the wiki and included as part of a release.
That’s the short story, read on for the long story…
I recently started an open source project (shameless plug… the project is jBati, a JavaScript ORM library) hosted at Google Code. One nice feature of Google’s project hosting is that each project has wiki. The project’s wiki is a nice place to post information as potential consumers can see the project documentation without having to download a release.
However, there are a couple of drawbacks to the wiki. The wiki editor is a plain HTML text box. This is serviceable enough for short documents but doesn’t work well for larger documents. Also, for someone like me who depends heavily on a spell checker, unless my browser does the checking, there is no spell checking.
The other drawback is that some documents, such as a User’s Guide, need to be posted on the wiki and also distributed with releases. There seemed to be one of two ways to accomplish this, either convert from the wiki to documents for release (which need to be in a text or HTML format), or, convert from the release documents to the wiki format.
I figured I wasn’t the first one with this idea and looked around. I found a wiki to HTML tool, an on-line wiki to HTML converter (http://jtidy.de/), and a really hard to read blog which reported that the Perl module HTML::WikiConverter did a decent job of converting HTML to Google Code wiki syntax.
I’m a Perl guy, so the HTML::WikiConverter module sounded like a winner. The HTML::WikiConverter comes with a set of plug-ins to support various wiki dialects. The recommend wiki dialect that gets closest to the Google Code wiki dialect is MoinMoin. The results were decent, yet some hand editing was needed to get perfect results. IMHO, once you choose a generation route like this (HTML → wiki), the tool chain has to work without intervention, otherwise you loose much of the advantage due to things getting out of sync.
So, I decided to fix this one for good and wrote a Google Code wiki dialect. I’m currently writing my project documentation with OpenOffice and saving the files as HTML. I use HTML::WikiConverter to generate wiki markup and then post the wiki files to the Google Code via svn.