Re: [sca-bindings] JCA & JMS specs

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

Eric, thanks for the comments, responses
inline; I've uploaded JMS binding cd02-rev3 with editorial changes as identified.

Here's the diff between rev3 and original
cd02:



Eric Johnson <eric@tibco.com> wrote on 17/06/2009
20:07:49:

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

OK, this seems to be an issue with my using Word 2003
and cute PDF to generate the PDF documents :(  Unfortunately I don't
have any other means of doing so.
 
> 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.

I agree, although I think that's something we can defer until after after
the public review draft.  I did note some formatting concerns a few
months ago, about fonts and default para formats being inconsistent across
the specs.  i've tried to be consistent in the JMS binding spec with
bold/italic for all element/attribute names.
 
> 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]"?

I agree with Mike Edwards's comment that it would
be best to have the name of the link and then the token in all cases. I've
done that in a couple of places in the updated JMS binding revision.
 
> 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...".

Applied.
 
> line 137, 158, 159, 160, 333-334: " as defined in the SCA Assembly
> Specification [SCA-Assembly]" --> " as defined in [SCA-Assembly]"

As per the above, I've ensured it appears as SCA Assembly
Specification [SCA-Assembly] everywhere
 
> line 145: the proposed IETF JMS scheme doesn't follow this pattern. 
> Instead it follows "jms:jndi:<jms-dest>?..."

OK, I've made the example consistent at least with
the 05 revision of the URI syntax
 
> Shame-faced confession: If you go and look for the IETF proposal,
at
> the moment, you will not find it. 

Google on draft-merrick-jms-uri-05.txt  ;)

> 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.
> 
> Note that issue 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...

For the moment I don't think we can do any better
than is in the footnote

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

OK, I've split out the definition of the callback
destination outside the normative statement.
 
> 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?

Yes, this is issue 74, latest email: http://lists.oasis-open.org/archives/sca-bindings/200906/msg00036.html

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

I think this is probably the same issue with Word
2003 and CutePDF...
 
> (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


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

sca-binding-jms-1.1-spec-cd02-rev3-diff.pdf