RE: WSDL 2.0 primer CR comments

Thanks for your comment.  The WS Description Working Group tracked this
issue as a CR064 [1].

Changes as detailed below are reflected in the latest draft [2].

Unless you let us know otherwise by the end of October, we will assume you
agree with the resolution of this issue.

[1] http://www.w3.org/2002/ws/desc/5/cr-issues/#CR064
[2]
http://dev.w3.org/cvsweb/~checkout~/2002/ws/desc/wsdl20/wsdl20-primer.html

Jonathan Marsh - http://www.wso2.com - http://auburnmarshes.spaces.live.com
 

> -----Original Message-----
> From: public-ws-desc-comments-request@w3.org [mailto:public-ws-desc-
> comments-request@w3.org] On Behalf Of Daniel Barclay
> Sent: Monday, June 12, 2006 3:10 PM
> To: public-ws-desc-comments@w3.org
> Subject: WSDL 2.0 primer CR comments
> 
> 
> 
> The WSDL 2.0 Primer CR contains a number of editorial errors:
> 
> * Sections 1.3's heading says "Use of URI and IRI."  Since the section
> talks
>    about URIs and IRIs, and not about the words "URI" and "IRI," the
> section
>    title should probably say "Use of URIs and IRIs."

fixed

> * Section 2.1.1 says:
> 
>      ... a floating point number in USD$ ...
> 
>    "USD$" should be "USD" (or some other valid option).

fixed

>    (Also, is "floating point number" valid outside the realm of fixed-size
>    storage with an exponent field?)

Either way the text seems clear enough as is.

> 
> * Section 2.2 says:
> 
>      A language specification must therefore define the set sentences
>      in that language ...
> 
>    That should be "... set of sentences ..."

fixed

> * Section 2.2.2.1 says:
> 
>      ... how the children elements of the description element ...
> 
>    That should say "child elements" instead of "children elements"
> (because
>    that use of a noun as an adjective requires the singular form).

fixed

> * Section 2.2.2.1 also says:
> 
>      Thus, the order of the WSDL 2.0 elements matters, in spite of
>      what the WSDL 2.0 schema says.
> 
>    The wording "in spite of ..." implies that there is a contradiction,
>    namely, that the schema implies that the order does not matter, and
>    that what the schema implies is to be ignored.
> 
>    Perhaps saying something like "... the order ... matters, even though
>    the schema doesn't specify that it does" would avoid implying something
>    false to the reader.

Fixed: "... even though the WSDL 2.0 schema does not capture this
constraint."

> * Section 2.2.3 says:
> 
>      (Whew!).
> 
>    The period (full stop) is extraneous.  (The exclamation point already
>    ends the statement.)

fixed

> * Section 2.3.3 says:
> 
>      So far we have briefly covered both WSDL import/include and schema
>      import/include.
> 
>    Since slash means (or usually means) "or" (recall, for example, that
>    "and/or," which means "and or or"), that should be written out as "...
>    WSDL import and include and schema import and include" (also because
>    text should probably be readable without having to figure out to
>    which word a punctuation character was intended to map).

fixed

> * Section 4.4.1 says:
> 
>      ... is signaled by attribute wsdl:required="false" ...
> 
>    That wording isn't quite right.  The construct "attribute xyz" only
>    works when "xyz" is the name of the attribute.
> 
>    The text should say something like:
> 
>       ... is signaled by setting attribute wsdl:required to "false" ...
> 
>    or:
> 
>      ... is signaled by setting wsdl:required="false" ...
> 
>    or:
> 
>      ... is signaled by wsdl:required="false" ...
> 
>    (The next paragraph has another instance of the same problem.)

Fixed (the final suggestion seemed most readable to me.)

> * Section 4.2.3 still says:
> 
>      <min 3, max 7> <!-- check schema for syntax -->

Fixed
    <minInclusive value="3"/>
    <maxInclusive value="7"/>

> * Section 5.1 repeatedly refers to "uniquely identify[ing] a message"
>    when it really means uniquely identifying a message _type_.  For
>    example, the first sentence says:
> 
>      It is desirable for a message recipient to have the capability
>      to uniquely identify a message in order to handle it correctly.
> 
>    That makes it sound like it's about to talk about per-message IDs
>    (per-instance IDs).
> 
>    The wording should be reworked appropriately.

Fixed throughout section 5.1

> * Section 5.2 says:
> 
>      ... a wide ranging debate ...
> 
>    That should be:
> 
>      ... a wide-ranging debate ...
> 

fixed

> 
> Additionally:
> 
> * Section 5.6.2 refers to RFC 2396, which has been obsolete for
>    over a year.  The section should probably refer to RFC 3986.

Fixed.

> 
> 
> Daniel Barclay
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
>

Received on Friday, 20 October 2006 21:49:24 UTC