Enclosed below is a message we received from Stephen McConnel regarding the Avalon doc generation. The problem isn't so much that Cocoon couldn't get working but that he had to sift through mountains of stacktraces.
To that end, I suggest we look at a smarter way of dealing with errors. There are certain types of errors that are common enough to really be simplified. Also, there are a number of exceptions in the log files that seem to have no real affect on Cocoon's ability to output the proper result. My suggestion is this: 1. Identify common potential errors, following is a short list: * Bad markup (XML document malformed) * Resource not available 2. Provide a really simple message WITHOUT a stacktrace for these types of errors. It is more helpful to know that "index.xml" is not well formed than it is to know exactly which line of code the error occurred. Same with the fact that "index.xml" might not exist. 3. Stop using exceptions to control program flow. We need another mechanism for that. Stack traces in the log files and printed to the screen should document real exceptions. They should represent things that Cocoon *really* did not expect, or cannot handle gracefully. > -----Original Message----- > From: Stephen McConnell [mailto:[EMAIL PROTECTED]] > Sent: Wednesday, July 17, 2002 10:46 AM > To: Avalon Developers List > Subject: doc generation woes > > > > 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]> -- To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]> For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
