db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jeff Levitt <de...@mylevita.com>
Subject Re: [jira] Commented: (DERBY-296) Document error messages in the Derby Reference Manual
Date Mon, 13 Jun 2005 17:09:58 GMT

--- Myrna van Lunteren <m.v.lunteren@gmail.com> wrote:

> On 6/10/05, David Van Couvering (JIRA)
> <derby-dev@db.apache.org> wrote: 
> > 
> > [
> > ]
> > 
> > David Van Couvering commented on DERBY-296:
> > -------------------------------------------
> > 
> > Well, I'm looking at the patch, and while I'm I
> spend time verifying they 
> > are all correct, I want to ask a couple of meta
> questions: 
> > [..snip..]
> > - I know there is an ErrorMessage VTI that prints
> out all the error 
> > messages and SQLSTATEs. Would it make more sense
> just to document to a user 
> > how they could use ij to print out these messages
> from the VTI? This way you 
> > wouldn't have to continue to maintain this list
> and try and make sure it's 
> > consistent with reality, which seems like a task
> meant more for Sisyphus 
> > than anyone else :) 
> > [..snip..]
>  My 2c...: It's in the engine javadoc...But I admit
> it was harder to find 
> than I thought. In old Cloudscape manuals this was
> documented...I couldn't 
> find an obvious spot in the current manuals...(sorry
> if I was particularly 
> blind & it's there).
> I am wondering whether users are so used to browsing
> error message manuals 
> for other databases that they have a hard time using
> the ErrorMessage VTI? 
> Plus, you'd need ij...(or issue a separate sql
> command at least).
> Maybe we can add more value to this document over
> the VTI by adding 
> debugging tips and hints where it seems appropriate
> at some point...?
> Myrna

Yes, my thoughts were similar to Myrna's.  At a later
date, it might be nice to include more information
here for many of the problem messages.  A more
detailed explanation as well as a suggested user
response to the error are good ways to help the user
in ways they wouldn't get if they just had the error
message itself.  For this release, my idea was to just
get the messages doc'd, so we'd have a baseline for
future releases.  For now, the only thing these doc'd
message offer that the actual message strings lack is
a value name for the parameters.  This can help users
who may not have named databases, tables, views, etc
very clearly, or don't understand what the values are
that the message is returning.  So instead of seeing a
{0} in the message text, the doc replaces it with
<tableName> for example.  As we work on documenting
these messages better, we can replace some of the more
generic values with more descriptive substitutions.

The above two reasons provide better information to
the user than just telling them to output it from the
VTI, but also make it hard to run some sort of script
to create DITA from the VTI output.  While I think
that would be very helpful indeed (and much faster),
we would still have to go back each time and add the
message details and user responses, as well as the
substituted parameter values.

However, if there is indeed a way to print out the
messages from the VTI, I think if a user just wants to
do that instead of looking at the docs, and the
command is available to them, then there should be
instructions on how to do that in the docs.  If
someone wants to open a JIRA issue to do that, I'd be
happy to take on that task.  I'd appreciate it if you
could provide the command to do it, as well as a
suggestion of which book and which part of that book
to place it, as that will make creating the pacth much
easier, and more likely to make it in 10.1.

View raw message