[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: JCA & JMS specs
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.
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...
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)