[XML-DEV Mailing List Archive Home] [By Thread] [By Date] [Recent Entries] [Reply To This Message]

Re: Relax NG and Web Services (formerly Joining the church)

• To: "James Clark" <jjc@j...>,"Dave Pawson" <dpawson@n...>
• Subject: Re: Relax NG and Web Services (formerly Joining the church)
• From: "Bob Foster" <bob@o...>
• Date: Sun, 13 Jul 2003 11:30:45 -0500
• Cc: "Tim Bray" <tbray@t...>,<xml-dev@l...>
• References: <16141.50377.892328.973970@m...> <15725CF6AFE2F34DB8A5B4770B7334EE022DC53F@h...> <16141.50377.892328.973970@m...> <5.2.0.9.2.20030711170227.02730f98@p...> <3F0FD98F.1090004@j...>

From: "James Clark" <jjc@j...>
> Unfortunately, your scratching your head is not an effective way to
> communicate to me that you would like me to change an error message.

Jing's error messages seem much better than they used to be! Thanks for
continuing to work on them.

> The way to get me to change something is to send me a bug report
> including as many as possible as:
>
> - the error message you got

In the compact syntax, "Syntax error."
In the XML syntax, "Element incomplete." (From memory; the actual message is
very close to that.)

> - a brief explanation of why the error message made you scratch your head

The messages don't pinpoint the problem or suggest how to fix it.

> - an alternative error message that would not have made you scratch your
> head

A good template to fall back on is to say what prompted the error message
and what was expected, instead. E.g., "Syntax error: found '|' expecting
'=', '|=' or '&='." Or, "Element incomplete: found '</foo>' expecting one of
elements 'bar', 'baz', etc."

This type of message becomes unhelpful if the list of expected items is very
large, but it is ok to truncate the list, as shown above. Of course, the
expected symbols come from the First set or equivalent of the grammar just
before the error was detected.

> - the schema
> - the instance
> - the version of Jing you're using

20030619

> At the very least, I need the first two. If I tried to guess what you
> found confusing, I would probably get it wrong.

As a rule, messages that do not already contain a quoted symbol might be
improved by following the template above.

> If the problem is just the wording, then you can change it yourself.
> Extract com/thaiopensource/relaxng/impl/resources/Messages.properties
> from jing.jar (e.g. with unzip), edit to taste (and send me the diffs),
> and add back to jing.jar.  If it's the formatting you don't like, you
> can change com/thaiopensource/xml/sax/resources/Messages.properties.

The problem is lack of information, which can't be added by translation or
reformatting.

> One of the problems with trying to improve error messages is that almost
> nobody ever feels it's worthwhile to report a confusing/unhelpful error
> message as a bug.

Mea culpa.

Bob

> James

• References:
  • RE: Relax NG and Web Services (formerly Joining the church)
    • From: David Megginson <david@m...>
  • RE: Relax NG and Web Services (formerly Joining the church)
    • From: "Bullard, Claude L (Len)" <clbullar@i...>
  • Re: Relax NG and Web Services (formerly Joining the church)
    • From: Dave Pawson <dpawson@n...>
  • Re: Relax NG and Web Services (formerly Joining the church)
    • From: James Clark <jjc@j...>

• Prev by Date: RE: Joining the church
• Next by Date: [OT] Tim Bray on Slashdot
• Previous by thread: Re: Relax NG and Web Services (formerly Joining the church)
• Next by thread: RE: Relax NG and Web Services (formerly Joining the church)
• Index(es):
  • Date
  • Thread