Mailing-List: contact derby-dev-help@db.apache.org; run by ezmlm
Precedence: bulk
Reply-To: <derby-dev@db.apache.org>
Received-SPF: neutral (asf.osuosl.org: local policy)
Message-ID: <44F865BC.2010509@apache.org>
Date: Fri, 01 Sep 2006 09:54:20 -0700
From: Daniel John Debrunner <djd@apache.org>
User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US;
 rv:1.7.3) Gecko/20040910
MIME-Version: 1.0
To: derby-dev@db.apache.org
Subject: Re: Doc Review: Reference Guide.
References: <44F849DF.9040500@gmail.com>
In-Reply-To: <44F849DF.9040500@gmail.com>
Content-Type: text/plain; charset=us-ascii
Content-Transfer-Encoding: 7bit

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.