You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cocoon.apache.org by Berin Loritsch <bl...@apache.org> on 2002/07/17 17:13:30 UTC
FW: Simplifying Error Reporting (FW: doc generation woes)
> -----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: <ma...@jakarta.apache.org>
>
>
> --
> To unsubscribe, e-mail:
> <mailto:avalon-dev-> unsubscribe@jakarta.apache.org>
> For
> additional commands,
> e-mail: <ma...@jakarta.apache.org>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: FW: Simplifying Error Reporting (FW: doc generation woes)
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Berin Loritsch wrote:
>
>>-----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
Yes.
>>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.
This has been discussed very recently, and in fact I thought I had
already removed the stacktrace from RNF errors except in DEBUG mode...
>>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.
I think that the best thing is to put hands in Main and such, ie the
commandline stuff.
Lokking it now...
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org