Doc Review: Reference Guide.

[Army <qo...@gmail.com>]

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

Re: Doc Review: Reference Guide.

[Daniel John Debrunner <dj...@apache.org>]

Army wrote:


> -- 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.

To be correct XMLSERIALZE converts to a 'character type', not a
'string'. String is Java terminology, this is the SQL reference.
And similar to the comment below, XMLSERIALIZE does not 'retrieve'
anything, it's just a SQL operator.

Maybe something like

An XML value cannot be converted to any non-XML type using an explicit
or implicit CAST. The XMLSERIALIZE operator provides the ability to
represent (convert?) an XML type as (to?) a character type.

> -- 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.

The use of 'view' here is very strange and I think incorrect.
XMLSERIALIZE is an operator that converts a XML type to a character
type, it does not provide any viewing capabilities. The ability to view
such a value is provided by the application (e.g. ij or a web-browser).

Dan.