WSDL 2.0 primer CR comments

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|

WSDL 2.0 primer CR comments

Daniel Barclay


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


* Section 2.1.1 says:

     ... a floating point number in USD$ ...

   "USD$" should be "USD" (or some other valid option).

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


* Section 2.2 says:

     A language specification must therefore define the set sentences
     in that language ...

   That should be "... set of sentences ..."


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


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

* Section 2.2.3 says:

     (Whew!).

   The period (full stop) is extraneous.  (The exclamation point already
   ends the statement.)

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

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

* Section 4.2.3 still says:

     <min 3, max 7> <!-- check schema for syntax -->

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


* Section 5.2 says:

     ... a wide ranging debate ...

   That should be:

     ... a wide-ranging debate ...




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.





Daniel Barclay
















Reply | Threaded
Open this post in threaded view
|

Re: WSDL 2.0 primer CR comments

Daniel Barclay

I wrote:
>
> The WSDL 2.0 Primer CR contains a number of editorial errors:
> ...

Also:

* Section 5.5.1 says:

     All relationships in WSDL 2.0 (like an Operation belonging to an
     Interface ...) are ...

That should be:

     All relationships in WSDL 2.0 (like an Operation's belonging to an
     Interface ...) are ...

(It's not the Operation itself but its belonging (again, note the
possessive word before the word "belonging") that is the relationship.)



Daniel







Reply | Threaded
Open this post in threaded view
|

RE: WSDL 2.0 primer CR comments

Jonathan Marsh-2
In reply to this post by Daniel Barclay

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: [hidden email] [mailto:public-ws-desc-
> [hidden email]] On Behalf Of Daniel Barclay
> Sent: Monday, June 12, 2006 3:10 PM
> To: [hidden email]
> 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
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>



Reply | Threaded
Open this post in threaded view
|

RE: WSDL 2.0 primer CR comments

Jonathan Marsh-2
In reply to this post by Daniel Barclay

Thanks for your comment.  The WS Description Working Group tracked this
issue as a CR065 [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/#CR065
[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: [hidden email] [mailto:public-ws-desc-
> [hidden email]] On Behalf Of Daniel Barclay
> Sent: Tuesday, June 13, 2006 6:58 AM
> To: [hidden email]
> Subject: Re: WSDL 2.0 primer CR comments
>
>
> I wrote:
> >
> > The WSDL 2.0 Primer CR contains a number of editorial errors:
> > ...
>
> Also:
>
> * Section 5.5.1 says:
>
>      All relationships in WSDL 2.0 (like an Operation belonging to an
>      Interface ...) are ...
>
> That should be:
>
>      All relationships in WSDL 2.0 (like an Operation's belonging to an
>      Interface ...) are ...
>
> (It's not the Operation itself but its belonging (again, note the
> possessive word before the word "belonging") that is the relationship.)
>

fixed

> Daniel
>
>
>
>
>
>