NEW ISSUE: consistency of references, acronyms

Description:

The existing draft (2009-10-26) of the specification inconsistently uses
references and acronyms.  For example, even though "Java Messaging
Service" is noted at the beginning of the document as "(JMS)", the JMS
abbreviation is not used throughout.


Proposal:
The abstract should be treated somewhat as a separate entity -
references here should be repeated in the body of the text.

When acronyms are introduced, they should be used consistently.

A textual reference should link to the references section upon first
use.  Subsequent uses should not be linked.

Detailed changes:

Section 1.1:
replace: "How SOAP over JMS uses the URI specification for JMS endpoints
[URI Scheme for JMS]"

with:
"How SOAP over JMS uses the URI specification for JMS endpoints
(JMS-URI)[URI Scheme for JMS]

Section 1.3:
Replace: "Java Message Service (JMS) [Java Message Service]" with "JMS"

Section 1.4.1:
Replace: "SOAP over Java Message Service" with "SOAP/JMS"

Section 1.6:
Replace: "Java Message Service (JMS) 1.1 [Java Message Service]" with "JMS"

Replace: "[URI Scheme for JMS]" with "the JMS-URI".

Section 2.2.4:
Strike the sentence: "To conform to the latest enhancements to support
internationalization, this specification references the [URI Scheme for
JMS]."

Section 2.4:
Replace: "Based on the sending node's use of SOAP 1.1 [SOAP 1.1], SOAP
1.2 [SOAP 1.2 Messaging Framework], SOAP Messages with Attachments [SOAP
Messages with Attachments], and MTOM [SOAP 1.1 Binding for MTOM 1.0]
[SOAP MTOM]"

with
"Based on the sending node's use of SOAP 1.1, SOAP 1.2, SOAP Messages
with Attachments, and MTOM"

Section 2.5:
Replace: "defined in section 6.2, Request-Response Message Exchange
Pattern, [SOAP 1.2 Part 2: Adjuncts])" with "defined in Request-Response
Message Exchange Pattern" (link should persist)

Section 2.6:
Replace: "The http://www.w3.org/2003/05/soap/mep/request-response/
message pattern is described in section 6.2, Request-Response Message
Exchange Pattern, [SOAP 1.2 Part 2: Adjuncts].

For binding instances conforming to this specification:"

with
"For binding instances using the
http://www.w3.org/2003/05/soap/mep/request-response/ message pattern:"

(Note the use of "may" in the two bullets has been raised in issue 15:
http://www.w3.org/2002/ws/soapjms/tracker/issues/15

Section 2.6.1:

Remove paragraph altogether.

Section 2.6.2:

Remove the paragraph altogether.

Section 2.7:
replace: "The SOAP One-way MEP [SOAP 1.2 Part 3: One-Way MEP] defines
..." with "The SOAP One-way MEP defines ..."

Section 3.1:
Replace: "Java Message Service" with "JMS"

Replace: "For information about accepted SOAP 1.2 bindings, see WSDL 1.1
for SOAP 1.2." with "For information about accepted SOAP 1.2 bindings,
see [WSDL 1.1 for SOAP 1.2]." (Brackets added)

Section 3.4.1:
Replace: "The [WSDL 1.1] specification" with "The WSDL 1.1
specification" (remove link)

Section 3.4.5:
Replace: "the URI [URI Scheme for JMS]" with "the JMS-URI".

-----------------------------

-Eric.

Received on Monday, 26 October 2009 21:07:39 UTC