This sample code shows one way to do a migration from a fairly simple Anakia
site (the Apache Harmony website sources snapshotted at 30 December 2005) to
a setup usin XDok.

For this site, the main advantages of using XDok over Anakia:

  * speed. XDok takes about a second on my machine to render the entire site,
    Anakia takes about 3 seconds. On reruns (when all content is already
    there), the difference is something like .2ms vs a second and a bit (like,
    so, who cares)

  * validation. XDok helps with rendering valid XHTML (the harmony site isn't
    completely valid, for example it uses <meta name="" value="" /> where
    value="" really ought to be content=""). (would easily be fixed manually).

  * no need for java. This is at most a highly dubious advantage, since python
    is still required. Since harmony is all about java, chances are more of its 
    developers will have java than will have python.
    
    So in the harmony case this is probably a *disadvantage*.

  * somewhat cleaner output. Consider
  
    Transforming auth_cont_quest.html          ...building...ok
    Copying auth_cont_quest.txt                ...ok
    Transforming bulk_contribution_checklist.html...building...ok
    Copying bulk_contribution_checklist.txt    ...ok
    Transforming code_scan_tools.html          ...building...ok
    ...
    Transforming svn.html                      ...building...ok
    Copying images/apache-incubator-logo.png   ...ok
    Copying images/asf_logo.jpg                ...ok
    Copying images/geronimo-logo.png           ...ok
    Copying images/harmony-logo.png            ...ok
    
          - vs -

Buildfile: build-export.xml

export-site:
     [echo] 
     [echo]        #######################################################
     [echo]        #
     [echo]        #  Now using Anakia to transform our XML documentation
     [echo]        #  to HTML.
     [echo]        #
     [echo]        #######################################################
     [echo]       
   [anakia] Transforming into: /data/dev/asf/infrastructure/site-tools-trunk/xdok/harmony-sample/standard/site/docs-temp
   [anakia] Input:  auth_cont_quest.xml
   [anakia] Output: /data/dev/asf/infrastructure/site-tools-trunk/xdok/harmony-sample/standard/site/docs-temp/auth_cont_quest.html
   ...
   [anakia] Input:  svn.xml
   [anakia] Output: /data/dev/asf/infrastructure/site-tools-trunk/xdok/harmony-sample/standard/site/docs-temp/svn.html
   ...
     [copy] Copying 4 files to /data/dev/asf/infrastructure/site-tools-trunk/xdok/harmony-sample/standard/site/docs-export/images
     [copy] Copying 2 files to /data/dev/asf/infrastructure/site-tools-trunk/xdok/harmony-sample/standard/site/docs-export
   [delete] Deleting directory /data/dev/asf/infrastructure/site-tools-trunk/xdok/harmony-sample/standard/site/docs-temp

BUILD SUCCESSFUL
Total time: 3 seconds

    (not exactly a mind-blowing difference either, is it?)

  * more standards-based XHTML. This could be implemented for Anakia using
    Velocity's DVSL, but that's not in widespread deployment right now.
    
  * hackable. Writing a custom Kid template provides a lot more "freedom" than
    writing a custom velocity template. This is also a disadvantage, since its
    easily abused and leads to really ugly stuff (eg big Kid templates no-one
    understands). Its doubtful that Harmony really needs this kind of
    hackability.

Some of the disadvantages are:

  * no project.xml-style menu. While this is obviously easy enough to code up,
    it doesn't exist for XDok at the moment.

  * no relative URL resolution. I'm not exactly sure how much URI munging
    Anakia does to keep URLs working when files are across multiple dirs, but
    it has some of that and XDok does not. This meant adding a <base/> tag to
    the template, which makes the content rather unsuitable for offline use.

  * less mature. Anakia's been around for a while.
  
  * less used. Anakia's in widespread use, XDok is not.
  
  * NIH. While both XDok and Anakia have reasonable documentation, Anakia is
    pretty much "homegrown" at the ASF, whereas XDok uses many more external
    bits, most importantly Kid.

Conclusion

  While the tools seem pretty interchangeable and porting from Anakia to XDok is
  a rather straightforward exercise, Anakia is probably still the preferable
  tool for this kind of situation. Based on this example the only real reason to
  use XDok over Anakia would be when you want something that hasn't got a
  dependency on java (or Apache Ant).
  
  It is probably a good idea to try and add some of the improvements from XDok
  (standardized XHTML-based content format, strong data validation) to Anakia.