Re: WSA SOAP Binding minor editorial issues

On Mar 10, 2005, at 6:18 AM, Jonathan Marsh wrote:

>
> 1) See my Core comment which applies here too.
>> The Short Table of Contents does not provide significant value over
>> the complete version since the complete version fits easily on a
>> single screen with room to spare.  I assume this is automatically
>> generated by the build process.  Can we drop the Short Version?
>
Easily done via a stylesheet parameter

> 2) Section 2.3 is titled "State Machine" but there's no further mention
> of states or machines.  Can the title be changed to something more
> meaningful?
>
I was copying the section naming from the SOAP 1.2 specified features, 
I changed it to "Properties" and move the final paragraph to the 
previous subsection "Description"

> 3) Section 2.4 has an error in the SOAP Action URI - should be
> "http://www.w3.org/2003/05/soap/features/action/".
>
The URI is the name of the property, not the feature. I think its 
correct.

> 4) The title of the SOAP 1.2 Addressing 1.0 Feature is not consistent
> throughout the document.  There are occurrences of SOAP 1.2 Addressing
> Feature and Web Services Addressing 1.0 Feature elsewhere in the
> document.  Personally, I'd drop the 1.0, it is just too awkward.  
> Future
> features could be called SOAP 1.2 Addressing Feature 2.0 or something
> like that.
>
We had an issue about including 1.0 in the document title, I propagated 
that (inconsistently it would seem) to the feature name. I'm OK going 
either way but would prefer the WG to decide.

> 5) Example 3-2 implies (subtly) that wsa:Action is not required.  It
> would be better to show the message with a wsa:Action header.  Or note
> in the text that other wsa:* headers will/may also appear.
>
You're just being paranoid ;-). I added a dummy wsa:Action header.

> 6) Section 4.2 Second sentence appears to have a "," instead of a ";" 
> or
> other stronger punctuation.
>
I split the sentence.

> 7) Section 5 says: "The [action] property below designates 
> WS-Addressing
> fault messages: http://www.w3.org/@@@@/@@/addressing/fault".  But as
> we're (unfortunately) not defining that URI we should illustrate a
> different [action] value.
>
We can define an action URI for the messages we define (the SOAP fault 
ones), I think this is OK as is but we might want to define individual 
actions for each fault we define rather than using a single action for 
all of them - a new issue ?

> 8) Section 5.2 lists as required (in certain circumstances) headers of
> To, MessageID, and Action.  These should be MessageID, RelatesTo, and
> Action, I think.
>
Why do you think RelatesTo is required but MessageID is not ? Only To 
and Action are mandatory according to core... For now I've eliminated 
the list since certain properties are required in certain circumstances 
but not all.

> 9) Section 5 mixes property notation such as [message id] and element
> names such as MessageID.  Please consistently use property notation.
>
Since you asked so politely ;-). Note that I couldn't do anything about 
the RetryAfter since we don't define an abstract property for that and 
doing so seems like overkill.

> 10) Section 5.5 ed note - second sentence grammar needs tweaking.
>
Done.

> 11) See my Core comment which applies here too:
>> 6) Many sections and subsections don't have explicit ids (e.g.
>> Security Considerations).  It's nice to have readable IDs for linking
>> to the spec with fragments.
>
OK, will fix the auto-generated ones to be more meaningful.

Marc.

---
Marc Hadley <marc.hadley at sun.com>
Web Technologies and Standards, Sun Microsystems.

Received on Thursday, 10 March 2005 02:02:57 UTC