Re: [sca-bindings] WS Binding CD02 rev1

I'm happy with Simon's proposed rewording,
and I think it can be treated as editorial without opening a new issue.

Simon Nash <> wrote on 11/06/2009
22:43:45:

> Anish,

> See comments inline below.

> 

>    Simon

> 

> Anish Karmarkar wrote:

> > Simon Nash wrote:

> >> Anish,

> >> Here are my comments on the latest draft.

> >>

> >> 1. The colon following [BWS40005] in section 4.2.2 is not
correct and

> >>    should be changed to a period.  Also, [BWS40006]
and [BRS40007]

> >>    should not be a bulleted list.

> >>

> >>    The default transport binding rules are defined
in the previous

> >>    bulleted list at the start of section 4.2.2.
 This non-normative

> >>    definition is followed by three normative statements
BWS40005,

> >>    BWS40006 and BWS40007 that refer back to the
previous definition.

> >>    These three normative statements are independent
of each other and

> >>    should not be linked together, either by a colon
or by bulleted

> >>    indentation.

> >>

> > 

> > Fixed in CD02-rev3 (which isn't posted yet, but will be later).

> > 

> >> 2. The text for BWS20018 refers to the "semantics of
this

> >>    attribute".  When reading the standalone
conformance statement in

> >>    Appendix B, it isn't clear which attribute is
intended.  This text

> >>    should read "semantics of the @wsdli:wsdlLocation
attribute".

> >>

> > 

> > BWS20018 says:

> > "The semantics of this attribute are specified in Section
7.1 of WSDL 

> > 2.0 [WSDL20]. The value of the @wsdli:wsdlLocation attribute
MUST 

> > identify an existing WSDL 1.1 document."

> > 

> > Going by our conventions, I don't think the 1st sentence should
be part 

> > of BWS20018. I would like to suggest the following:

> > Leave the 1st statement as is, but remove it from BWS20018. BWS20018

> > would now read --

> > "The value of the @wsdli:wsdlLocation attribute MUST identify
an 

> > existing WSDL 1.1 document."

> > 

> > I'll make this change in CD02-rev3, please let me know if you
disagree.

> > 

> This is a step in the right direction, but I think it leads to the

> need for further changes in the definition of @wsdli:wsdlLocation.

> 

> The change that you are suggesting would produce the following (using

> paragraph boundaries to clearly separate normative and non-normative

> statements):

> 

>   The @wsdli:wsdlLocation attribute MAY be specified by the binding
in

>   the event that the <WSDL-namespace-URI> in the ‘endpoint’
attribute

>   is not dereferencable, or when the intended WSDL document is
to be

>   found at a different location than the one pointed to by the

>   <WSDL-namespace-URI>. [BWS20016]

> 

>   If the @wsdli:wsdlLocation attribute is used the @wsdlElement
attribute

>   MUST also be specified. [BWS20017]

> 

>   The semantics of this attribute are specified in Section 7.1
of

>   WSDL 2.0 [WSDL20].

> 

>   The value of the @wsdli:wsdlLocation attribute MUST identify
an

>   existing WSDL 1.1 document. [BWS20018]

> 

> The ordering of these four statements is ambiguous at best and confusing

> at worst.  (Does "this attribute" mean wsdlLocation
or wsdlElement?)

> A better approach would be to define the meaning of wsdli:wsdlLocation

> first, followed by additional rules about its usage in <binding.ws>.

> This immplies moving the non-normative sentence earlier, so that it

> precedes BWS20017 instead of being sandwiched between BWS20017 and

> BWS20018.  The result would be as follows:

> 

>   The @wsdli:wsdlLocation attribute MAY be specified by the binding
in

>   the event that the <WSDL-namespace-URI> in the ‘endpoint’
attribute

>   is not dereferencable, or when the intended WSDL document is
to be

>   found at a different location than the one pointed to by the

>   <WSDL-namespace-URI>. [BWS20016]

> 

>   The semantics of this attribute are specified in Section 7.1
of

>   WSDL 2.0 [WSDL20].

> 

>   If the @wsdli:wsdlLocation attribute is used the @wsdlElement
attribute

>   MUST also be specified. [BWS20017]

> 

>   The value of the @wsdli:wsdlLocation attribute MUST identify
an

>   existing WSDL 1.1 document. [BWS20018]

> 

> This is an improvement, but BWS20016 has the problem that it uses
MAY

> in the way that we decided was incorrect when resolving ASSEMBLY-122

> (i.e., to specify a choice for user code rather than an optional

> feature for implementations).  So I'd suggest taking the further
step

> of making the BWS20016 text non-normative, which produces the following:

> 

>   The @wsdli:wsdlLocation attribute can be used in the event
that

>   the <WSDL-namespace-URI> is not dereferenceable, or when
the intended

>   WSDL document is found at a different location than the one
pointed to

>   by the <WSDL-namespace-URI>.  The semantics of this
attribute are

>   specified in Section 7.1 of WSDL 2.0 [WSDL20].

> 

>   If the @wsdli:wsdlLocation attribute is used, the @wsdlElement

>   attribute MUST also be specified. [BWS20017]

> 

>   The value of the @wsdli:wsdlLocation attribute MUST identify
an

>   existing WSDL 1.1 document. [BWS20018]

> 

>   ***Note that I have made some minor wording and spelling updates
to

>   the above, including removing the incorrect reference to the

>   ‘endpoint’ attribute***

> 

> Do you think we could make the above changes editorially, or do we
need

> an issue?

> 

>    Simon

> 

> > -Anish

> > -- 

> > 

> >>   Simon

> >>

> >> Anish Karmarkar wrote:

> >>> Created CD02-rev2 by making the ed changes pointed out
by SimonN as 

> >>> well as reversed the way the 2119 keyword stmt bookmarks/crossrefs

> >>> worked to match that of assembly (was a major PITA to
change it). I 

> >>> also did some formating/ed changes and fixed a few refs/crossrefs.

> >>> More detailed comments inlined below.

> >>>

> >>> CD02-rev2 (Word & PDF):

> >>> http://www.oasis-open.org/apps/org/workgroup/sca-

> bindings/download.php/32884/sca-binding-ws-1.1-spec-cd02-rev2.doc

> >>>

> >>> http://www.oasis-open.org/apps/org/workgroup/sca-

> bindings/download.php/32885/sca-binding-ws-1.1-spec-cd02-rev2.pdf

> >>>

> >>>

> >>> Diff between CD02-rev1 and CD02-rev2:

> >>> http://www.oasis-open.org/apps/org/workgroup/sca-

> bindings/download.php/32886/sca-binding-ws-1.1-spec-cd02-rev1-rev2-diff.pdf

> >>>

> >>>

> >>> Diff between CD02 and CD02-rev2:

> >>> http://www.oasis-open.org/apps/org/workgroup/sca-

> bindings/download.php/32887/sca-binding-ws-1.1-spec-cd02-rev2-diff.pdf

> >>>

> >>>

> >>> -Anish

> >>> -- 

> >>>

> >>> Simon Nash wrote:

> >>>> Anish,

> >>>> Thanks for your work on this.  Here are my comments.

> >>>>

> >>>> Major issue:

> >>>>

> >>>>  All cross-references for conformance statements
and tags are wrong.

> >>>>

> >>>>  The bookmark R_BWSxxxxx should be the [BWSxxxxx]
tag in the main

> >>>>  chapter text, with a cross-reference in the
"Conformance ID" column

> >>>>  of Appendix B.  Instead this bookmark
is the main chapter text

> >>>>  describing BWSxxxxx, with a cross-reference
in the "Description"

> >>>>  column of Appendix B.

> >>>>

> >>>>  The bookmark BWSxxxxx should be the text describing
BWSxxxxx in the

> >>>>  "Description" column of Appendix
B, with a cross-reference 

> >>>> preceding the

> >>>>  [BWSxxxxx] tag in the main chapter text.  Instead
this bookmark is the

> >>>>  [BWSxxxxx] tag in the "Conformance ID"
column of Appendix B, with a

> >>>>  cross-reference following the main chapter
text describing BWSxxxxx.

> >>>>

> >>>> Editorial comments:

> >>>>

> >>>>  1. In front matter "Related Work",
change "supercedes" to 

> >>>> "supersedes".

> >>>>

> >>>

> >>> Done.

> >>>

> >>>>  2. In front matter "Abstract", fix
typo "of an SCA composites".

> >>>>

> >>>

> >>> Done.

> >>>

> >>>>  3. In front matter "Notices" last
paragraph, fix typo "names OASIS 

> >>>> is".

> >>>>

> >>>

> >>> Done.

> >>>

> >>>>  4. In section 1.1, change [[RCF2119]] to [RFC2119].

> >>>>

> >>>

> >>> Done.

> >>>

> >>>>  5. In section 1.4, use Word cross-reference
for [SCA-Assembly].

> >>>>

> >>>

> >>> Done.

> >>>

> >>>>  6. In section 2 bulleted list, there are 3
cross-references to

> >>>>     [SCA-Assembly] under /binding.ws/wsdlElement
which should be

> >>>>     Word cross-references.

> >>>>

> >>>

> >>> Done.

> >>>

> >>>>  7. In section 2 bulleted list, /binding.ws/wireFormat
and

> >>>>     /binding.ws/operationSelector should
be in bold italic font.

> >>>>

> >>>

> >>> Done.

> >>>

> >>>>  8. In section 2 bulleted list, cross-references
to [SCA-Assembly]

> >>>>     in /binding.ws/wireFormat and /binding.ws/operationSelector

> >>>>     should be Word cross-references.

> >>>>

> >>>

> >>> Done.

> >>>

> >>>>  9. In section 2.3, the Word cross-reference
to [SCA-JCAA] points

> >>>>     to [SCA-Policy].

> >>>>

> >>>

> >>> Done.

> >>>

> >>>> 10. In section 4.1, the cross-reference (R2705) should
use square

> >>>>     brackets instead of parentheses.  Also,
it should point to a

> >>>>     reference in section 1.2 instead of
directly to a section of

> >>>>     http://www.ws-i.org/Profiles/BasicProfile-1.2.html
(which is

> >>>>     not one of the documents listed in
section 1.2).

> >>>>

> >>>

> >>> Fixed to point to the reference in section 1.2.

> >>>

> >>>

> >>>> 11. In section 4.2.1, conformance statement [BWS40004],
fix

> >>>>     typo "from the that interface".

> >>>>

> >>>

> >>> Done.

> >>>

> >>>> 12. In section 4.2.2, delete the colon after [BWS40005].

> >>>>

> >>>

> >>> Colon is necessary (per the issue resolution).

> >>>

> >>>> 13. In section 4.2.2, the paragraphs containing conformance
statments

> >>>>     [BWS40006] and [BWS40007] should not
be indented.

> >>>>

> >>>

> >>> They have to be indented. It is supposed to be a list.
Fixed.

> >>>

> >>>> 14. In section 4.2.2, conformance statement [BWS40007],
fix

> >>>>     typo "structureal".

> >>>>

> >>>

> >>> Done.

> >>>

> >>>> 15. In section 5.1 first paragraph, add a Word cross-reference
for

> >>>>     [SCA-Assembly].

> >>>>

> >>>

> >>> Done.

> >>>

> >>>> 16. In section 5.1 second paragraph, change [SCA-ASSEMBLY]
to

> >>>>     [SCA-Assembly} and add a Word cross-reference.

> >>>>

> >>>

> >>> Done.

> >>>

> >>>> 17. In section 5.2, change Appendix XXX to Appendix
B.

> >>>>

> >>>

> >>> Done.

> >>>

> >>>> 18. In section 5.2, add Word cross-references for
[SCA-Assembly] and

> >>>>     [SCA-Policy].

> >>>>

> >>>

> >>> Done.

> >>>

> >>>> 19. In conformance statement BWS20005, fix double
blank in

> >>>>     "runtime MUST".

> >>>>

> >>>

> >>> Done.

> >>>

> >>>> 20. In conformance statement BWS20019, fix wrong
font (Verdana

> >>>>     instead of Arial) and spurious indentation
in opening paragraph

> >>>>     and first two bullets.

> >>>>

> >>>

> >>> Not sure why this was showing up.

> >>> Encountered some strange word bug (or lack of word skills).
BWS20019 

> >>> now does not have any bullets.

> >>>

> >>>> 21. In conformance statement BWS20019, third bulleted
item does

> >>>>     not have a bullet and is wrongly indented.

> >>>>

> >>>

> >>> See above.

> >>>

> >>>> 22. In conformance statements BWS20021/22/23/24,
fix wrong font

> >>>>     (Verdana instead of Arial).

> >>>>

> >>>

> >>> Fixed.

> >>>

> >>>> 23. In conformance statement BWS20032, fix wrong
font (Verdana

> >>>>     instead of Arial) and spurious indentation.

> >>>>

> >>>

> >>> Fixed.

> >>>

> >>>> 24. In Appendix D, add the list of contributors.

> >>>>

> >>>

> >>> SimonH: can you provide me a list. This needs to go in
all the 

> >>> binding specs.

> >>>

> >>>>   Simon

> >>>>

> >>>> Anish Karmarkar wrote:

> >>>>> Available at:

> >>>>> http://www.oasis-open.org/committees/download.php/32787/sca-

> binding-ws-1.1-spec-cd02-rev1.doc 

> >>>>>

> >>>>> http://www.oasis-open.org/committees/download.php/32788/sca-

> binding-ws-1.1-spec-cd02-rev1.pdf 

> >>>>>

> >>>>>

> >>>>> I used SimonH's issue 61 rev3 document as the
starting point. CD02 

> >>>>> rev1 includes resolutions of all the resolved
issues + all the 

> >>>>> action items against the ws binding editors.
Appendix F contains 

> >>>>> the revision history.

> >>>>>

> >>>>> The front page/footer isn't quite right (links,
date, title etc) 

> >>>>> wrt what we need for CD03/PRD and will be changed
before publication.

> >>>>>

> >>>>> I have also attached the diff version (PDF).

> >>>>>

> >>>>> -Anish

> >>>>> -- 

> >>>>>

> >>>>>

> >>>>> 

> ------------------------------------------------------------------------

> >>>>>

> >>>>>

> >>>>> ---------------------------------------------------------------------

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

> >>>>

> >>>>

> >>>

> >>>

> >>

> >>

> >>

> >> ---------------------------------------------------------------------

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

> > 

> > 

> 

> 

> 

> ---------------------------------------------------------------------

> 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

> 

Simon Holdsworth

STSM, SCA Bindings Architect; Master Inventor; OASIS SCA Bindings TC Chair

MP 211, IBM UK Labs, Hursley Park, Winchester SO21 2JN, UK

Tel +44-1962-815059 (Internal 245059) Fax +44-1962-816898

Internet - 

Unless stated otherwise above:

IBM United Kingdom Limited - Registered in England and Wales with number
741598. 

Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6
3AU