After taking a break from XML for a couple of days I went back and reviewed the
XML documentation that was provided as part of DERBY-1655. Most of the changes
look good (thanks Laura!), but I did have some comments on the Reference Guide,
so I'm including them here.
NOTE: I'm sending this as an email to derby-dev for ease of tracking: once this
email hits the archives, I plan to add an entry to:
http://wiki.apache.org/db-derby/ReferenceManualTenTwo
with a link to this thread. I think this will be easier than adding a new row
to the table at the above wiki page for each of the comments below...
Note: All comments here are IN ADDITION to the changes discussed on the
following thread:
http://thread.gmane.org/gmane.comp.apache.db.derby.devel/28136/focus=28136
-----
-- 1--
Sub-section: Built-in functions -> CAST -> Conversions of XML values
URL: http://db.apache.org/derby/docs/dev/ref/rrefsqlj33562.html
The following sentence seems a bit odd:
An XML value cannot be converted to a non-XML type. To convert an XML
value to a string, you must use the SQL/XML serialization operator
XMLSERIALIZE.
It sounds like we're saying "You can't do <a>, but in order to do <a>, here's
what you do." Maybe reword to:
An XML value cannot be converted to any non-XML type using a CAST. You
can, however, retrieve an XML value as a string by using the SQL/XML
serialization operator XMLSERIALIZE.
Or something to that effect.
-- 2 --
Sub-section: Built-in functions -> XMLEXISTS:
URL: http://db.apache.org/derby/docs/dev/ref/rreffuncxmlexists.html
It's a bit of a technicality but Derby doesn't technically "return" an error
from these operators. Instead, it "throws" an error back to the user with an
indication as to why the operator failed to complete.
So the last part of the following sentence should be updated to reflect that
(under the "xquery-string-liter" heading):
If this argument is specified as a parameter, an expression that
is not a literal, or a literal that is not a string (for example
an integer), Derby returns an error.
A similar change should also be made to the last sentence under the
"xml-value-expression" heading:
If the argument is a sequence that is returned by the Derby
XMLQUERY operator, the argument is accepted if it is a sequence
of exactly one node that is a document node. Otherwise Derby
returns an error.
-- 3 --
Sub-section: Built-in functions -> XMLEXISTS:
URL: http://db.apache.org/derby/docs/dev/ref/rreffuncxmlexists.html
Under the "xquery-string-literal" heading, there's a slight typo in the last
sentence: the word "the" should be removed from "see the these Web sites":
For more on XPath and XQuery expressions, see the these Web sites.
-- 4 --
Sub-section: Built-in functions -> XMLEXISTS:
URL: http://db.apache.org/derby/docs/dev/ref/rreffuncxmlexists.html
Rewording for the first sentence under the "xml-value-expression" header:
Must be an XML data type and must constitute a valid SQL/XML document.
Change to:
Must be an XML data value and must constitute a well-formed SQL/XML
document.
-- 5 --
Sub-section: Built-in functions -> XMLEXISTS:
URL: http://db.apache.org/derby/docs/dev/ref/rreffuncxmlexists.html
In the following sentence:
Since the BY REF clause is also the default passing mechanism, ...
I'm not sure this is strictly correct since the "clause" is not a "passing
mechanism" per se. Rather, the passing mechanism is "BY REF", and the "clause"
is just the inclusion of those key words in the syntax. Again, maybe I'm just
being too darned picky, but I'd rather see this as:
Since BY REF is also the default passing mechanism, ...
-- 6 --
Sub-section: Built-in functions -> XMLEXISTS:
URL: http://db.apache.org/derby/docs/dev/ref/rreffuncxmlexists.html
The following sentence:
You can create the x_table table with a check constraint that
allows an XML value to be inserted into the xcol XML column.
This sentence says that it's possible to create a constraint that allows
insertion of an XML value--but the constraint isn't really what allows the
insertion. The insertion is allowed by default; the constraint adds conditions
which, when not met, will actually DIS-allow the insertion. So perhaps this
could be re-written as:
You can create the x_table table with a check constraint that
limits which XML values can be inserted into the xcol XML column.
In this example the constraint is that ...
-- 7 --
Sub-section: Built-in functions -> XMLQUERY:
URL: http://db.apache.org/derby/docs/dev/ref/rreffuncxmlquery.html
See comments 2 thru 5 and apply them all to the XMLQUERY section,
as well.
-- 8 --
Sub-section: Built-in functions -> XMLQUERY:
URL: http://db.apache.org/derby/docs/dev/ref/rreffuncxmlquery.html
With respect to this sentence:
Since the RETURNING SEQUENCE clause is also the default
return type, ...
Similar to comment 5 above: I'm not sure this is strictly correct since the
"clause" is not a "return type" per se. The return type is "SEQUENCE", and the
"clause" is the inclusion of "RETURNING SEQUENCE" key words in the syntax. So I
think we should reword this as:
Since SEQUENCE is also the default return type, ...
-- 9 --
Sub-section: Built-in functions -> XMLQUERY:
URL: http://db.apache.org/derby/docs/dev/ref/rreffuncxmlquery.html
Oops, the second example in this section is not actually allowed by SQL/XML
specification; see DERBY-1759. Sorry! So please rewrite the query text:
'//student[text() = "BC"]/@age'
to be
'string(//student[text() = "BC"]/@age)'
The rest of the example statement can remain as it is.
-- 10 --
Sub-section: Built-in functions -> XMLSERIALIZE:
URL: http://db.apache.org/derby/docs/dev/ref/rreffuncxmlserialize.html
Something about this sentence seems awkard to me:
Using the XMLSERIALIZE operator is the only way that you
can view serialized contents.
Can we reword it to something like the following (in the context of the page,
this suggestion seems more appropriate than it does right here):
There is no other way to view the contents of a Derby XML
value.
--------
Note: I'm going to be out of town for the rest of the day and will not be able
to comment further on this thread until early next week.
Army
