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 16:04:30 GMT


> -----Original Message-----
> From: Leo Simons [mailto:leosimons@apache.org] 
> Sent: Wednesday, July 17, 2002 12:02 PM
> To: Berin Loritsch
> Subject: Re: Simplifying Error Reporting (FW: doc generation woes)
> 
> 
> I think what you should do is provide separate logs for different log
> levels.
> 
> Messages sent to the console should be like
> 
> [INFO] Cocoon is starting up
> [INFO] successfully parsed URL bladi/bla.html
> [INFO] successfully parsed URL bladi/bla2.html
> [INFO] successfully parsed URL bladi/bla3.html
> [ERROR] URL bladi/bla4.html, line 29, column 3: the attribute <bla>
> should end with </bla>
> [INFO] Cocoon is done. Time taken: 20 seconds
> [INFO] there was 1 error. See the logfile 
> cocoon-error-TIMESTAMP.log for
> more information
> 
> with messages in the logfile like
> 
> [INFO] Cocoon is starting up
> [DEBUG] version is bla
> [DEBUG] using DTDs at bladi/dtds
> [DEBUG] could not find property file ~/cocoon.properties
> [DEBUG] could not find property file ../cocoon.properties
> [DEBUG] loading property file ~/cocoon.properties
> [DEBUG] generating sitemap...
> [DEBUG] added URL bladi/bla.html to sitemap
> [DEBUG] added URL bladi/bla2.html to sitemap
> [DEBUG] added URL bladi/bla3.html to sitemap
> [DEBUG] added URL bladi/bla4.html to sitemap
> [DEBUG] done generating sitemap.
> [DEBUG] generating output...
> [DEBUG] parsing URL bladi/bla.html, source file is bladi/bla.xml
> destination file is ../build/docs/bladi/bla.html
> [INFO] successfully parsed URL bladi/bla.html
> [DEBUG] parsing URL bladi/bla2.html, source file is bladi/bla2.xml
> destination file is ../build/docs/bladi/bla2.html
> [INFO] successfully parsed URL bladi/bla2.html
> [DEBUG] parsing URL bladi/bla3.html, source file is bladi/bla3.xml
> destination file is ../build/docs/bladi/bla3.html
> [INFO] successfully parsed URL bladi/bla3.html
> [DEBUG] parsing URL bladi/bla4.html, source file is bladi/bla4.xml
> destination file is ../build/docs/bladi/bla4.html
> [ERROR] URL bladi/bla4.html, line 29, column 3: the attribute <bla>
> should end with </bla>
> [DEBUG] URL bladi/bla4.html, line 29, column 3: the attribute <bla>
> should end with </bla>. Stacktrace:
> 	<<complete stacktrace here>>
> [DEBUG] done generating output.
> [INFO] Cocoon is done. Time taken: 20 seconds
> [INFO] there was 1 error. See the logfile 
> cocoon-error-TIMESTAMP.log for
> more information
> 
> A setup like this (INFO to stdout, ERROR to stderr, DEBUG to 
> logfile) is
> quite common in a lot of software.
> 
> I do not think it is bad to print long stack traces. You just need to
> print them somewhere where they are not in the way of the information.
> 
> cheers,
> 
> - Leo
> 
> On Wed, 2002-07-17 at 17:04, 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:
> > <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