db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Rick Hillegas <Richard.Hille...@Sun.COM>
Subject Re: DERBY-1566: "SQL error messages and exceptions" doc
Date Thu, 31 Aug 2006 00:04:54 GMT
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
>
>  
>


Mime
View raw message