Re: [sca-bindings] WS Binding CD02 rev1

[Simon Holdsworth <simon_holdsworth@uk.ibm.com>]

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

Simon Nash <oasis@cjnash.com> 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 - Simon_Holdsworth@uk.ibm.com

---

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