A couple of days ago Leo suggested I put in place some site documentation for the Merlin 2 package and gave me some hints on how to put it together using the Tweety package as an example of a Coocoon based structure. After spening much time I ended up committing an Anakia based solution.
I though it would be a good idea to mention some of the problems I came across and the reason why I used Anakia in preference to Cocoon. Initial attempts at building a doc site using Cocoon approach resulted in lots of errors - which I finally figured out as being linked to the fact that I had not updated the Avalon CVS for a couple of days. After updating my Avalon CVS things started to go a little smoother but still bumpy. Main problems were strange exception that Cocoon is spitting out about documents not found that are internal documents generated by Cocoon in the build directory (and in some cases permission related exceptions) - even ignorning these (which take up over a hundred or so lines), its very difficult to get meaninful errors from Cocoon generation process - lots of errors appear not to effect the build - but sometimes the build fails and attempting to locate the cause amongst all of the non-failure stack traces is very painful. Things got worse when I attempted to include links to javadoc content in the .xml sources and even more errors when attempting to include illustrations. So I figured I was doing something seriously wrong and checked around for examples on the other avalon projects. That ledme to review the documentation sources in Phoenix and discovery that Phoenix documentation is based on Anakia. So I tried to do the same thing with Anakia just to see if I could validate things using an alternative approach. I quickly discovered that Cocoon and Anakia are using differnent defintions of the document tag - I also discovered that IE6 does not like the Cocoon DTD, and that Anakia doesn't even have a DTD. Anyway, pressing on, I manged to get a site in place using Anakia reasonably rapidly and without build errors - although I found some inconsistency in Anakia content generation (generate the site from a clean build and its ok - regenerate and you get odd stuff appearing in the generated sources). After getting a reasonalby complete site together using Anakia, I took the sources - did the Anakia to Coocoon document migration - and re-tried to get something working with Cocoon but without success. The end result being that I have committed a bunch of Anakia based doc sources and commented out the Cocoon related build targets in the Merlin 2 build file. Conclusion: Anikia is *much* easier to use but less consistent than Cocoon. Cocoon appears to have a strong document model and overall presents as a more powerful platform but has seriouse problems in error management resulting in making it unusable in the time I had available. Anyway, a first cut at a Merlin 2 site is up: http:/home.osm.net/doc/docs/index.html Cheers, Steve. -- Stephen J. McConnell OSM SARL digital products for a global economy mailto:[EMAIL PROTECTED] http://www.osm.net -- To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]> For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
