Re: [sca-bindings] JCA & JMS specs

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

One comment in-lined below.

-Anish
--

Eric Johnson wrote:
> PDF for JMS does not hyperlink normative statements, references, nor 
> does it have a table of contents.  (Weirdness - Okular the KDE 4.X PDF 
> view, does not link the URLs at the beginning of the document, but Adobe 
> Reader does)
> 
> The specifications overall are inconsistent about typographical 
> conventions for referring to elements and attributes.  The WS Binding 
> spec doesn't do anything special, but the JMS spec appears to use 
> */bold/italic/* when referring to an element or attribute.  For 
> comparison, I checked with the Assembly spec, and it seems inconsistent, 
> sometimes it uses /*bold/italic*/, however sometimes the Assembly spec 
> refers to "/*foo element*/", and sometimes it refers to "/*foo*/ 
> element".  I also note places in Assembly where bold and italic are not 
> applied.
> 
> Some clarity on what we should do might be useful.
> 
> Also, we might want to define a standard for references - do we want to 
> include the title of the reference with the first reference to it, or 
> not.  The WS Binding spec generally cuts to the chase, and I have a 
> personal preference for that.  That is, do we do "SCA Assembly 
> Specification [SCA-Assembly]", or just "[SCA-Assembly]"?
> 
> JMS spec: 
> http://www.oasis-open.org/committees/download.php/32790/sca-binding-jms-1.1-spec-cd02-rev2.pdf 
> 
> 
> line 134: "... the generic JMS binding type. The type..."  Technically, 
> it is an element.  --> "... the generic JMS binding element.  The 
> element...".
> 
> line 137, 158, 159, 160, 333-334: " as defined in the SCA Assembly 
> Specification [SCA-Assembly]" --> " as defined in [SCA-Assembly]"
> 
> line 145: the proposed IETF JMS scheme doesn't follow this pattern.  
> Instead it follows "jms:jndi:<jms-dest>?..."
> 
> /Shame-faced confession:/ If you go and look for the IETF proposal, at 
> the moment, you will not find it.  We were going to update it a few 
> weeks back (before the previous draft expired), when we discovered that 
> IETF changed their legal disclosure requirements.  That sent a bunch of 
> us scrambling to talk to lawyers to make sure we do the right thing.  I 
> should be posting a new version by some time next week - of course, 
> since the old one expired, I might find some new hurdle to overcome that 
> will delay this slightly.
> 

I don't think we should point normatively to a spec with a URL that we 
know will result in 404. IETF drafts do expire after 6 months.
I would like to suggest that we use the same link used by SOAP over JMS 
spec (http://www.w3.org/TR/2009/CR-soapjms-20090604/):
http://tools.ietf.org/id/draft-merrick-jms-uri-05.txt

This URL points to an expired document, but the reader will at least be 
able to retrieve it.


> Note that issue 20 <http://www.osoa.org/jira/browse/BINDINGS-20>, we 
> resolved to follow the IETF here.  Do we need another issue to update 
> this again?  Of course, it is probably hard to follow the IETF proposal, 
> when it isn't even available...
> 
> lines 524 - 529: In other places, rather than have such a large 
> normative statement, we've created a definition of a notion, and then 
> had a normative statement referring to that notion.
> 
> line 731: I thought we had agreed that normative statements in the 
> conformance section don't get numbered.  Hmmm, maybe that's an open issue?
> 
> JCA spec: 
> http://www.oasis-open.org/committees/download.php/32791/sca-binding-jca-1.1-spec-cd02-rev2.pdf
> 
> Table of contents shows "Error: Bookmark not defined"
> 
> (Looks like I've run out of time for today, and won't get to the rest of 
> JCA before tomorrow's meeting)
> 
> 
> --------------------------------------------------------------------- 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