RE: Comments on Primer Sections 1 - 3

Kevin,

OK, I'll make the edits.

Arthur Ryman,
Rational Desktop Tools Development

phone: +1-905-413-3077, TL 969-3077
assistant: +1-905-413-2411, TL 969-2411
fax: +1-905-413-4920, TL 969-4920
mobile: +1-416-939-5063, text: 4169395063@fido.ca
intranet: http://labweb.torolab.ibm.com/DRY6/



"Liu, Kevin" <kevin.liu@sap.com> 
Sent by: www-ws-desc-request@w3.org
06/14/2005 07:08 PM

To
Arthur Ryman/Toronto/IBM@IBMCA, <www-ws-desc@w3.org>
cc

Subject
RE: Comments on Primer Sections 1 - 3






Oops, hit the send button too soon.
 
More comments below.
 
Again, thank a lot for the detailed comments. It's very helpful.
Best Regards,
Kevin
  
 

From: Liu, Kevin 
Sent: Tuesday, Jun 14, 2005 3:54 PM
To: 'Arthur Ryman'; www-ws-desc@w3.org
Subject: RE: Comments on Primer Sections 1 - 3

Hi Arthurs,
 
Thanks for the comments. Please see my response below.
 
Overall I agree with most of your suggestions. If you would like, you have 
my permission to check in directly to CVS. 
Best Regards,
Kevin
  
 

From: www-ws-desc-request@w3.org [mailto:www-ws-desc-request@w3.org] On 
Behalf Of Arthur Ryman
Sent: Monday, Jun 13, 2005 11:50 AM
To: www-ws-desc@w3.org
Subject: Comments on Primer Sections 1 - 3


1. Section 1.3. I strongly recommend that the primer should not use RFC 
2110 keywords. This is too formal. The primer should be informal. There is 
no point in repeating formal definitions that appear in Part 1 or 2. The 
language should be informal and seay to read. Everyone agrees that the XML 
Schema primer [1] is a good example. It does not use RFC 2110. 

[Kevin] we have fixed all the uppercase keywords such as MUST, SHOULD, etc 
in the content of the primer. 
 
We should aslo remove the first paragraph in [Kevin] section 1.3? 

2. Section 2.2.1. The statement: 

xmlns="http://www.w3.org/2005/05/wsdl" 
This is the XML namespace for WSDL 2.0 itself. Because we have not defined 
a prefix for it, any unprefixed elements or attributes are expected to be 
WSDL 2.0 elements or attributes (such as the description element). 


is a little misleading since WSDL 2.0 attributes are unprefixed. Perhaps 
restrict this statement to just elements, and mention that attributes are 
unprefixed. 

[Kevin] sounds good
 
3. Throughout. Sometimes we say WSDL, sometimes WSDL 2.0. Check that all 
instances use WSDL 2.0 where appropriate. 

[Kevin] sounds good
 
4. Figure 3-1 Infoset diagram. 

-the cardinality of <types> is 0..1, not 0..* 

[Kevin] good catch, I will update the digram
> has extends, not Extends 

[Kevin] ditto
 
- the cardinality of <endpoint> is 1..*, not 0..* 

[Kevin] ditto
 
- in the Note, <description> may not include <feature> or <property> 

[Kevin] ditto
 
5. Section 3.2, the text: 

In other words, the children elements of the description element should be 
ordered as follows: 
An optional documentation comes first, if present. 
then comes zero or more elements from among the following, in any order: 
Zero or more include 
Zero or more import 
Zero or more extensions 
An optional types follows 
Zero or more elements from among the following, in any order: 
interface elements 
binding elements 
service elements 
Zero or more extensions.

should be (redunant "Zero or more" eliminated) : 

In other words, the children elements of the description element should be 
ordered as follows: 
An optional documentation comes first, if present. 
then comes zero or more elements from among the following, in any order: 
include 
import 
extensions 
An optional types follows 
Zero or more elements from among the following, in any order: 
interface elements 
binding elements 
service elements 
extensions.

[Kevin] Though this can be considered as wrting style differences, I like 
your text better
 
6. Section 3.3. The text: 

The WSDL 2.0 component model is particularly helpful in defining the 
meaning of import and include. WSDL 2.0 include allows components from 
another WSDL 2.0 document having the same targetNamespace to be merged in 
with the components of the current WSDL 2.0 document, and is transitive 
(i.e., if the included document also includes a WSDL 2.0 document, then 
those components will also be merged, and so on). WSDL 2.0 import allows 
components from another WSDL 2.0 document having a different 
targetNamespace to be merged in with comonents of the current WSDL 2.0 
document, and is not transitive. 

is not accurate. The behaviour of import and include should not be 
described in terms of transitive merging of components. The component 
model contains all the components that get referenced, directly or 
indirectly from the root WSDL 2.0 document. import is used to declare that 
a WSDL document refers to components from another namespace. 
[Kevin] If I remember it right, the text was based on F2F discussion in 
Mountain view. Can you propose a better text to replace the above 
paragraph? 

[1] http://www.w3.org/TR/xmlschema-0/ 

Arthur Ryman,
Rational Desktop Tools Development

phone: +1-905-413-3077, TL 969-3077
assistant: +1-905-413-2411, TL 969-2411
fax: +1-905-413-4920, TL 969-4920
mobile: +1-416-939-5063, text: 4169395063@fido.ca
intranet: http://labweb.torolab.ibm.com/DRY6/