Re: ACTION 186 - top to bottom review of current copy of spec

Here's my first response, dealing with editorial items.

Diff of the XML form:
http://dev.w3.org/cvsweb/2008/ws/soapjms/soapjms.xml.diff?r1=1.91&r2=1.92&f=h

... and the HTML form:
http://dev.w3.org/cvsweb/2008/ws/soapjms/soapjms.html.diff?r1=1.90&r2=1.91&f=h

Please review carefully to see if you have any complaints.

Astute readers will notice that this email skips a revision # relative
to my last change.  This was a minor typo I fixed in v1.91

http://dev.w3.org/cvsweb/2008/ws/soapjms/soapjms.xml.diff?r1=1.90&r2=1.91&f=h

-Eric.

On 07/12/2010 12:16 PM, Eric Johnson wrote:
> Editorial items:
> ================
> 
> Section 1.1: First paragraph: "It should also enable customers to
> implement their own Web services for part of their infrastructure..."
> --> "This will also enable customers...".  Also "It should enable them
> to write" --> "This will enable them to write..."

Applied.

> 
> Section 1.1, paragraph #2: "...it should be possible for a client
> running..." --> "...it ought to be possible for a client running..."

Applied.

> 
> Section 1.1, paragraph #3: "...details of how such gateways should be
> designed..." --> "...details of how such gateways can be designed..."

Upon reflection, changed "can" to "might".

> 
> Section 1.1: First bullet - use of the word "must" --> should be "have to"

Applied.

> 
> Section 1.1: 2nd bullet: "The WSDL binding that may be used to describe
> SOAP/JMS" --> "The WSDL binding that describes SOAP/JMS"

Applied.

> 
> Section 1.1: Third bullet, also section 1.6, #1, also section 3.3.5
> The spec is currently inconsistent: JMS-URI vs. JMS URI.  The majority
> of the uses are of the form "JMS URI", so I changed these three
> inconsistent references.

Applied.

> 
> Section 1.2: First bullet - "... but the customer must still use a
> single implementation of JMS..." --> "... but the customer still needs
> to use a single implementation of JMS..."

Applied.

> 
> Section 1.3: Paragraph #1: "This document specifies how SOAP should
> bind..." --> "This document specifies how SOAP binds..."

Applied.

> 
> Section 1.4: Reference to section "Faults" should be a link.
> 
> Also, "How these subcodes should be treated is dealt with in the section
> "Faults"." --> "The section Faults discusses the treatment of these
> subcodes."
> 
> Section 1.4.1: last paragraph: "However, should the specifications
> revert to Working Draft status..." --> "However, in the event that the
> specifications revert to Working Draft status"

Both applied.

> 
> Section 2.1: First paragraph:
> "... and implicitly the JMS calls that must be made" --> "... and
> implicitly the JMS calls that need to be made"

Applied.

> 
> paragraph #2: "...how JMS connections and destinations should be
> handled." --> "...how JMS connections and destinations are handled."
> Also, "such as priority, soapAction and targetService should be handled
> within the SOAP/JMS implementation." --> "such as priority, soapAction
> and targetService are handled within the SOAP/JMS implementation."

Applied.

> 
> Section 2.2.1: Definition of jndiURL - apparently missing a space
> between "InitialContext" and the word "constructor".

Applied.

> 
> Section 2.2.2: soapjms:priority definition - missing comma in "if
> specified MUST" --> "if specified, MUST"

Applied.

> 
> Section 2.2.2.1: "...an example of how a JMS Message Header property MAY
> be set" --> "...an example of how a JMS Message Header property can be set"

Applied.

> 
> Section 2.2.3.1: "... an example of how a JMS Message property MAY be
> set" --> "... an example of how a JMS Message property can be set".

Applied.

> 
> Section 2.3: " This specification does not mandate how an implementation
> should obtain these credentials" --> " This specification does not
> mandate how an implementation might obtain these credentials"

Applied.

> Also, "Implementers of this binding should consider how to most
> appropriately expose authentication functionality to their users in a
> way that meshes smoothly with the models exposed by their environments"
> --> "Implementers of this binding are encouraged consider the most
> appropriately way to expose authentication functionality to their users
> such that it meshes smoothly with the models exposed by their environments"

Noticed typos above.  Used this instead:
"Implementers of this binding are encouraged to consider the most
appropriate way to expose authentication functionality to their users
such that it meshes smoothly with the models exposed by their environments"

> 
> Section 2.4: "The formatting of the SOAP payload is determined by the
> sending SOAP node, and should follow the same pattern as for the
> SOAP/HTTP binding" -->
> "The sending SOAP noad follows the same pattern as for the SOAP/HTTP
> binding when determining the format of the SOAP payload."

Typo, and thought of even better wording:
"When determining the format of the SOAP payload, the sending SOAP node
follows the same pattern as for SOAP/HTTP binding"

> 
> Section 2.4.1: "The impact on network consumption should be measured for
> particular scenarios and JMS providers" --> "The impact on network
> consumption ought to be measured for particular scenarios and JMS providers"

Applied.

> 
> Section 2.6.1.2: "and that Destination is where implementations should
> be listening" --> "and that Destination is where implementations need to
> listen"

Applied.

> 
> 2.6.2.2, 2.7.2: Message Exchange Context should reference the relevant
> SOAP 1.2 section http://www.w3.org/TR/soap12-part2/#soapmec

Applied.

> 
> Section 2.7, first bullet:
> "A SOAP Node instantiated at the sending JMS interface may take on the
> role..." --> "A SOAP Node instantiated at the sending JMS interface
> takes on the role..."

Applied.

> 
> Section 3: paragraph #2 begins:
> 
> "The associated SOAP Underlying Transport Binding above contains..." -
> this is presumably a reference to section #2, but is not captured as a
> link.  Also, the name of the section is "SOAP Underlying Protocol Binding"

Upon reflection, changed this to "The section 2 The SOAP/JMS Underlying
Protocol Binding...

> 
> Section 3.3 (and all subsections), all the examples.
> 
> All the examples show a portion of a WSDL file.  For clarity, we should
> add a sentence to the second paragraph of section 3.3: "To aid in
> focusing on the relevant details, all of the WSDL examples in this
> section show only a portion of a WSDL file."

Thought of better wording:
"To focus on the salient details, all of the WSDL examples in this
section show only a portion of a WSDL file in question."

> 
> Section 3.3.4, paragraph #1:
> "For example, the jndiInitialContextFactory  may be indicated..." -->
> "For example, the jndiInitialContextFactory  can be indicated..."

Applied.

> 
> Appendix A:
> References not listed alphabetically (URI Scheme for JMS)
> 

Reordered based on reference key name, which was what we mostly seemed
to be doing already.

-Eric.

Received on Monday, 12 July 2010 22:03:05 UTC