More requests for Cocoon > -----Original Message----- > From: Stephen McConnell [mailto:[EMAIL PROTECTED]] > Sent: Wednesday, July 17, 2002 11:33 AM > To: [EMAIL PROTECTED] > Subject: Re: Simplifying Error Reporting (FW: doc generation woes) > > > > Berin: > > Beyond sensible error management - a couple of other > "end-user" requests: > > 1. A document DTD and a book DTD that I can reference in a source > and load inside IE. > 2. Real support for javadoc - if I look at the javadoc > for Cocoon - > there is NO package > documentation! I was shocked! I had imagined that things like > package documetation > could have been generated by cocoon and would have leveraged > automatic recognition > of javadoc links - this was a major pain area for me > because my > javadoc stuff is really > comprehensive - I would have loved to see a better solution. > > Cheers, Steve. > > > Berin Loritsch wrote: > > >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: [EMAIL PROTECTED] For additional commands, email: [EMAIL PROTECTED]
