On Wed, 2002-07-17 at 16:45, Stephen McConnell wrote:
>
> 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.
:/ shame things didn't work the way they should have...
> 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.
ouch!
> 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.
definately. Cocoon displays quite a few errors to the end user that
could be basically be summarised as "there were some inconsistencies but
we can continue".
> 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.
cocoon has some stupid ideas about what it should do with links to html
files. If you link to a javadoc document in a subdirectory, it thinks
this is an xml file it has to process; that results in an error.
I believe what you can do is feed cocoon a list of files to transform
instead, {xxx.uris}, and have it no do anything else.
What happened with the images?
> So I figured
> I was doing something seriously wrong and checked around for examples on
> the other avalon projects.
Since we're mostly pretty smart people, if we all have problems, then
the tool is doing something wrong =)
> 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.
worse, different versions have differing assumptions about the xml you
put in. jakarta-site and site2 are not compatible, for example.
> Anyway, pressing on, I manged
> to get a site in place using Anakia reasonably rapidly and without build
> errors
you will find the build errors in a file called 'velocity.log'. Anakia
goes to the other extreme: it doesn't print out any errors to the
console except in the most dire circumstances.
> - 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.
hmm. Of course, cocoon's document model (the document-v10.dtd) is not
really cocoon's; cocoon can be made to work with any model through the
use of XSL (cocoon-based forrest has a document-v11.dtd).
Overall, valuable comments for the cocoon team, I guess =)
> Anyway, a first cut at a Merlin 2 site is up:
>
> http:/home.osm.net/doc/docs/index.html
neat...looking forward to more....
cheers,
- Leo
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
