Mailing-List: contact derby-dev-help@db.apache.org; run by ezmlm
Precedence: bulk
Reply-To: <derby-dev@db.apache.org>
Received-SPF: pass (asf.osuosl.org: local policy)
Date: Wed, 30 Aug 2006 17:04:54 -0700
From: Rick Hillegas <Richard.Hillegas@Sun.COM>
Subject: Re: DERBY-1566: "SQL error messages and exceptions" doc
In-reply-to: <44F61E89.2000409@bristowhill.com>
Sender: Richard.Hillegas@Sun.COM
To: derby-dev@db.apache.org
Message-id: <44F627A6.9010103@sun.com>
MIME-version: 1.0
Content-type: text/plain; format=flowed; charset=ISO-8859-1
Content-transfer-encoding: 7BIT
References: <44F61E89.2000409@bristowhill.com>
User-Agent: Mozilla Thunderbird 1.0.6 (Windows/20050716)

Hi Jean and David,

Thanks for all this great, painstaking work! Here's where I hope we can 
end up:

A) David's tool is checked into the codeline.

B) Just before building the docs, the release manager can run the tool 
in order to generate the latest and greatest version.

So I have a question and a comment.

The question is this: Has (A) happened?

The comment follows your second question below.

Thanks,
-Rick

Jean T. Anderson wrote:

>A lot changed between 10.1.3 and 10.2.1.1. Six sqlstates dropped out,
>170 were added, and the current doc file for the Reference Guide isn't
>up to date.
>
>Adding all the sqlstates in manually would be an effort for which I
>don't believe we have time and it would be error prone. This is where
>David's app comes into play that generates a new doc based on info
>retrieved with the org.apache.derby.diag.ErrorMessages() vti.
>
>Here's the current 10.1 doc:
>http://db.apache.org/derby/docs/10.1/ref/rrefexcept71493.html
>
>Here's the 10.2 draft (uploaded to DERBY-1566):
>https://issues.apache.org/jira/secure/attachment/12339910/rrefexcept-2.html
>
>I believe the 10.2 draft is a good candidate that accurately reflects
>reality -- 849 entries made it into the new dita file, which matches the
>number of rows returned by the vti query ... always a good sign. :-)
>
>But I'll point out two differences between the 10.1 and 10.2 docs:
>
>1) 10.2 severity column. I bet there's a story why that column didn't
>make it into 10.1, but I sure don't remember. Anyone should feel free to
>provide that info. If people don't like it for whatever reason, I can
>easily remove it.
>
>2) The 10.1 doc replaces the variable markers, such as {0}, with human
>readable tags, such as <constraintName>.
>I don't intend to replace those {n} tags with human readable names. If
>anyone would like to offer to do so, feel free.
>  
>
I think that those substitutions make for better documentation but I 
don't see how we can teach David's tool to perform those 
substitutions--certainly not in the short run. In my opinion, more value 
is added by David's automated process for generating an accurate, 
up-to-date list of SQLStates. So I am happy with your solution: don't 
substitute the variable markers.

>Feedback? Opinions? Preferences?
>
>thanks,
>
> -jean
>
>  
>