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
