Improving Forrest Error Reporting

[Stephen Schaub <ss...@bju.edu>]

I discovered Forrest this summer and used it to create a website for an
open-source project. I love a lot of things about it. But...

I would love to see better error reporting. Can we get a line number in the
error messages when forrest encounters an error in a source file in the
xdocs folder?

I know that many people probably use validating editors and create source
documents using the document-vxx format, and thus avoid forrest errors
entirely. But if you like to use the wiki format (wonderful for simple
documents), and you happen to violate one of the (rather picky) rules (ex. a
blank line that happens to have a space in it), you get a cryptic error
message with no line number. That makes writing wiki documents for forrest a
"cross your fingers and hope" proposition, and if you mess up, you're
reduced to deleting sections of the document until it works, then adding
pieces back in until it fails, etc. I would like to see the chaperon parser
made a little more forgiving, but if not, at least tell me where in the
source file the problem occurred!

Imagine a compiler that didn't provide line numbers in its error messages...

Stephen Schaub

P.S. Who administers the mailing list archives on
issues.apache.org/eyebrowse? The search function does not include 2004
messages in its results.

Re: Improving Forrest Error Reporting

[David Crossley <cr...@apache.org>]

Stephen Schaub wrote:
> >Stephen Schaub wrote:
> >>
> >> I would love to see better error reporting. Can we get a line number in
> the
> >> error messages when forrest encounters an error in a source file in the
> >> xdocs folder?
> >
> [snip]
> 
> Dave Brondsema wrote:
> >Since the wiki files are parsed with the Chaperon parser, this is an
> >issue you should discuss on one of their mailing lists.  Unless of
> >course chaperon does provide better error messages but forrest hides it.
> 
> But this is _not_ just a wiki issue. Forrest doesn't provide line numbers
> for errors in .xml files either.

I do 'forrest run' in one window and use 'forrest validate'
in another window. Actually i often use 'xmllint' to validate
just the xdoc that i am working on.

> Perhaps that is Cocoon's fault. I've had
> some exposure to Cocoon in the past, and seem to remember no line numbers
> there, either. That really surprised me, because Cocoon is a highly regarded
> product, but its error reporting (at least, in the version I was using) was
> abysmal.

Cocoon has always said that it expects you to feed it
proper xml files. It is not Cocoon's job to validate the
xml for you.

> Good error reporting is vital. Developers put up with poor error reporting
> from development tools because we've come to expect it. But at least those
> cryptic compiler error messages typically provide a line number to help us
> locate the problem.  A product like Forrest that is designed for non
> programmers should have at least an equivalent, if not a higher, standard
> for its error reporting.

Have you also looked at the logfiles in build/webapp/WEB-INF/logs/

> I'll try to dig into the wiki side of things to see if Chaperon is at fault
> here. But I don't feel this discussion should be dismissed on the basis of
> "the problem is in someone else's code."

The Wiki files are where the issue is. If someone knows
about a separate Wiki validator, then we could plug that
into our build system so that the wiki files are included
in 'forrest validate'.

-- 
David Crossley

Re: Improving Forrest Error Reporting

[Stephen Schaub <ss...@bju.edu>]

>Stephen Schaub wrote:
>>
>> I would love to see better error reporting. Can we get a line number in
the
>> error messages when forrest encounters an error in a source file in the
>> xdocs folder?
>
[snip]

Dave Brondsema wrote:
>Since the wiki files are parsed with the Chaperon parser, this is an
>issue you should discuss on one of their mailing lists.  Unless of
>course chaperon does provide better error messages but forrest hides it.

But this is _not_ just a wiki issue. Forrest doesn't provide line numbers
for errors in .xml files either. Perhaps that is Cocoon's fault. I've had
some exposure to Cocoon in the past, and seem to remember no line numbers
there, either. That really surprised me, because Cocoon is a highly regarded
product, but its error reporting (at least, in the version I was using) was
abysmal.

Good error reporting is vital. Developers put up with poor error reporting
from development tools because we've come to expect it. But at least those
cryptic compiler error messages typically provide a line number to help us
locate the problem.  A product like Forrest that is designed for non
programmers should have at least an equivalent, if not a higher, standard
for its error reporting.

I'll try to dig into the wiki side of things to see if Chaperon is at fault
here. But I don't feel this discussion should be dismissed on the basis of
"the problem is in someone else's code."

Stephen

P.S. I've reported the search problems to the address you provided. Thanks!

Re: Improving Forrest Error Reporting

[Dave Brondsema <da...@brondsema.net>]

Stephen Schaub wrote:
> I discovered Forrest this summer and used it to create a website for an
> open-source project. I love a lot of things about it. But...
> 
> I would love to see better error reporting. Can we get a line number in the
> error messages when forrest encounters an error in a source file in the
> xdocs folder?
> 
> I know that many people probably use validating editors and create source
> documents using the document-vxx format, and thus avoid forrest errors
> entirely. But if you like to use the wiki format (wonderful for simple
> documents), and you happen to violate one of the (rather picky) rules (ex. a
> blank line that happens to have a space in it), you get a cryptic error
> message with no line number. That makes writing wiki documents for forrest a
> "cross your fingers and hope" proposition, and if you mess up, you're
> reduced to deleting sections of the document until it works, then adding
> pieces back in until it fails, etc. I would like to see the chaperon parser
> made a little more forgiving, but if not, at least tell me where in the
> source file the problem occurred!
> 
> Imagine a compiler that didn't provide line numbers in its error messages...
> 

Since the wiki files are parsed with the Chaperon parser, this is an 
issue you should discuss on one of their mailing lists.  Unless of 
course chaperon does provide better error messages but forrest hides it.

> Stephen Schaub
> 
> P.S. Who administers the mailing list archives on
> issues.apache.org/eyebrowse? The search function does not include 2004
> messages in its results.
> 
infrastructure@ap..org

-- 
Dave Brondsema : dave@brondsema.net
http://www.splike.com : programming
http://csx.calvin.edu : student org
http://www.brondsema.net : personal