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:33:31 GMT
More requests for Cocoon

> -----Original Message-----
> From: Stephen McConnell [mailto:mcconnell@osm.net] 
> Sent: Wednesday, July 17, 2002 11:33 AM
> To: bloritsch@apache.org
> 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: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: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org


Mime
View raw message