Tuesday, January 13, 2004

Converting HTML documentation into wiki notation using groovy instead of XSLT We started out writing the documentation for groovy in HTML. After starting to use wiki notation for the documentation I got convinced of its use - I think I'll now use wiki markup for developer documentation on all future projects. The great thing about using wiki markup is that its so quick & easy & concise to edit and mixing documentation, code & XML examples is very simple. No hassle encoding special HTML symbols like > or <. Another nice advantage is that all the Java /  groovy code we include in the documentation gets nicely pretty-printed by the wiki engine (radeox thats used inside SnipSnap). We've gone one step further and written a little wiki renderer that will extract the groovy code in the documentation and turn them into JUnit test cases so that we can unit test all of the example code in the documentation (we've found loads of bugs in it so far :) So yesterday on the train from Leeds to London I had an hour or so to turn all the old HTML into wiki markup. I thought I'd try use Groovy for this instead of XSLT (which always takes me a long time to pick up again after not using it for a while as it requires such a different mindset plus lots to remember). I was surprised how simple it was to do. Here's the script. By all means go ahead and use it if you need to do something similar. You'll just need nekohtml on your classpath along with groovy (which just depends on JDK 1.4 and asm). I think I agree with Martin on this; use a scripting language, its way simpler to get things done than using XSLT. 8:16:42 AM    comment []