Re: [sca-bindings] Review of sca-binding-ws-spec-cd02-rev3.pdf

[Anish Karmarkar <Anish.Karmarkar@oracle.com>]

Eric Johnson wrote:
> As I'm trying to read through these documents, I find the highlighting 
> of the normative statements is actually quite annoying.  It makes it 
> much harder to read the document.  In addition, I had to force my PDF 
> viewer to no color, because the default "highlight" color with my 
> windowing theme exactly matches the highlight color chosen for the 
> document, and searching for a result in a normative statement would then 
> not show where the search result was found.  My suggestion would be to 
> change the color of the normative text itself to a gray just shy of 
> black, rather than changing the background color of the text.
> 

+1
In addition to the problems that you describe, when viewing a doc with 
change marks, it poses a similar problem. The change mark colors 
sometimes are the same as the 2119 highlighting.
Another suggestion would be to use a different font/italics or both 
greying of the background and font/italics.

> Also seems to me that the normative numbering declarations could be 
> superscripted, so that it is easier to read the text and let my eyes 
> skip over the reference numbering.

+1

> 
> Those are just my personal preferences, though.
> 
> Line 101-103 - sentence is repeated.
> 

Operator error, fixed it in rev4.

> Line 207: "WSDL 1.1 message parts can point to an XML Schema element 
> declaration or an XML Schema type."  Mismatched parallelism.  Ought to 
> be "... can point /either /to an XML Schema element declaration or /to 
> /an XML Schema type/ declaration/."
> 

Fixed in rev4.

> Line 219: "Port" --> "port"
> 

Fixed in rev4.

> Line 265 - 266: "SCA runtime implementations MAY provide additional 
> metadata that is associated with a web service binding."  Unfortunately, 
> this sentence seems so out of context to me, that it is difficult to 
> figure out what it was actually referring to.  Are we talking here about 
> providing additional metadata in the generated WSDL document?  That 
> would push section 2.5 to be section 2.4.1.  However, I think what we 
> really mean here is that we really mean that an SCA binding.ws element 
> might contain additional metadata to help configure non-SCA aspects of a 
> web-services binding.  However, that's not a normative constraint on the 
> runtime, so then I don't get the normative statement.
> 

I agree that it is the latter.
I think the target of the 2119 statement is incorrect. Plus, I don't 
think it should contain a 'MAY'. This is no different than an optional 
element and we should just change this to "An SCA WS Binding XML 
document can provide addtional ..." and remove [BWS20031].

Since this is not an ed. change, I've not made it in rev4.

> I think I need to raise an issue for the above.  Am I missing something?
> 

+1 to raising an issue.

> Line 306: "... web service binding is configured with a policy intent(s) 
> ..." --> "... web service binding is configured with /any /policy 
> /intent /...
> 

I'm not so sure of this.
What if there are two intents that on their own do not conflict with the 
config, but when taken together do conflict with the config. I don't 
have an example of such a scenario, but want to make sure that something 
like this cannot happen.

> Should we swap sections 3 & 4, especially since section 3 makes 
> reference to details specified by section 4?
> 

Seems fine to me. But will wait for TC decision to make any changes.

> Line 443-444: Parallelism again: "MUST follow either the rpc-literal or 
> document-literal pattern." --> "MUST follow either the rpc-literal 
> /pattern/ or /the/ document-literal pattern."
> 

Fixed in rev4.

> Line 461: "of “Simple Object Access Protocol (SOAP) 1.1” [SOAP11] " --> 
> This is an inconsistent reference.  So far as I've discovered, we don't 
> inline the titles of the target of the reference elsewhere, so this 
> should change to just "of [SOAP11]".
> 

Fixed in rev4.

> Thankfully, all but one of the above are editorial...
> 
> -Eric.
> 
> --------------------------------------------------------------------- To 
> unsubscribe from this mail list, you must leave the OASIS TC that 
> generates this mail. Follow this link to all your TCs in OASIS at: 
> https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php