> -----Original Message-----
> From: Berin Loritsch [mailto:[EMAIL PROTECTED]]
> 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:[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:avalon-dev-> [EMAIL PROTECTED]>
> For
> additional commands,
> e-mail: <mailto:[EMAIL PROTECTED]>
>
>
> --
> To unsubscribe, e-mail:
> <mailto:avalon-dev-> [EMAIL PROTECTED]>
> For
> additional commands,
> e-mail: <mailto:[EMAIL PROTECTED]>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, email: [EMAIL PROTECTED]
