cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Berin Loritsch" <blorit...@apache.org>
Subject FW: Simplifying Error Reporting (FW: doc generation woes)
Date Wed, 17 Jul 2002 15:13:30 GMT


> -----Original Message-----
> From: Berin Loritsch [mailto:bloritsch@apache.org] 
> Sent: Wednesday, July 17, 2002 11:05 AM
> To: Avalon Developer's List
> Subject: Simplifying Error Reporting (FW: doc generation woes)
> 
> 
> 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:mcconnell@osm.net]
> > 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:mcconnell@osm.net
> http://www.osm.net
> 
> 
> 
> --
> To unsubscribe, e-mail: 
> <mailto:avalon-dev-> unsubscribe@jakarta.apache.org>
> For 
> additional commands, 
> e-mail: <mailto:avalon-dev-help@jakarta.apache.org>
> 
> 
> --
> To unsubscribe, e-mail:   
> <mailto:avalon-dev-> unsubscribe@jakarta.apache.org>
> For 
> additional commands, 
> e-mail: <mailto:avalon-dev-help@jakarta.apache.org>
> 


---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org


Mime
View raw message