Editorial comments for Part 1, section 1-3

Reading through the spec, I have found a few nits:

General Comments
----------------

* In some places we use "fully qualified name". I believe it should be
"XML qualified name" instead.

* In some of the new text we don't mark the phrases
"[attribute|element|...] information item" but in the old text, it shows
up as italic. We should either remove the markup or add it to the new
text as well.

Specific Comments
-----------------

* S1, P1: We use "such" in three places right after each other. Suggest
slight reformulation to avoid this

* S1, P3, numbered list: We need a bullet for the extensibility model.
Also, I suggest reordering to say

	1. SOAP processing model
	2. SOAP extensibility model
	3. SOAP protocol binding framework
	4. SOAP message construct

as this follows the ToC

* S1.3, P3: Change "defined by Parts 1 and 2" to "defined by Part 1 and
2"

* S1, last P: Add reference to part 2 appendix A (media type definition)

* S1.5, SOAP feature: Remove "optional"

* S1.5, SOAP header block: Change "fully qualified name" to "XML
qualified name"

* S2, P2: Change "with a feature" to "with a SOAP feature"

* S2, P2: Change "each such feature to define such combined" to "each
such SOAP feature to define any combined"

* S2, P3: Flip 1st and 2nd sentence to have them ordered according to
ToC

* S2.4, P1: Change "by the combination of [local name] and [namespace]"
to "by the XML qualified name"

* S2.4, P2: Change "SOAP header blocks MAY carry mustUnderstand
attribute information items" to "A SOAP header block MAY carry a
mustUnderstand attribute information item"

* S2.4, P2: Change "the SOAP block is said to be mandatory" with "the
SOAP header block is said to be mandatory"

* S2.6, P2 (after numbered list): Change "fully qualified name" to "XML
qualified name"


* (NOTE: this may not be seen as strictly editorial) S2.6, P3: This
applies to all faults and not just header fault: "Header-related faults
other than those related to understanding SOAP header blocks (see 2.4
Understanding SOAP Header Blocks) MUST conform to the specification for
the corresponding SOAP header block.".

I suggest saying:

"SOAP faults other than those related to understanding SOAP header
blocks (see 2.4 Understanding SOAP Header Blocks) MUST conform to the
specification for the corresponding SOAP header block or SOAP body."

S2.7, P1: Remove "and then expressed as SOAP modules or as part of the
underlying protocol binding" as the relationship between modules and
features is better described in section 3 and 4.

S2.7.1: This section is very hard to read in the current location
because the notion of an intermediary is not introduced before the next
section. Also, section 2.7.2 talks about "insert" and "reinsert" which
is also used but not described in section 2.7.1. I suggest the following
reorg:

A) Reorg the sections as follows:

	2.7.1 Forwarding Intermediaries
	2.7.2 Relaying SOAP header blocks
	2.7.3 SOAP Intermediaries and relayed infoset
	2.7.4 Active Intermediaries

The reason is that 2.7.1-2.7.3 talks about forwarding intermediaries
while active intermediaries are somewhat different.

B) (following new numbers) Move the three bullets in 2.7.1 into 2.7.2
and replace it with a reference instead.

C) Add a bullet to the three bullets (as bullet 0):

	0) Retain all header blocks not targeted at the forwarding node

S2.7.1, last P: Remove first "In addition"

S2.7.3, P2: Not clear whether this is a requirement or not but I would
expect it is and hence change "All Infoset properties of a message need
to be" to "All Infoset properties of a message MUST be"

S2.7.3: Add "" around URIs for c14n

S2.7.3: Update references (two) to section 2.7 to the proper
sub-section.

S2.8: P1: Change "the qualified name" to "the XML qualified name"

S3.1, last P: Change "hop-to-hop" with "hop-by-hop"

S3.3, bullet 3: Change "SOAP Processing model" to "SOAP processing
model"

Henrik Frystyk Nielsen
mailto:henrikn@microsoft.com

Received on Monday, 9 December 2002 13:52:48 UTC