Re: [ws-rx-editors] Non-trivial editorial comments

[Doug Davis <dug@us.ibm.com>]

In general I agree with the direction
you guys are headed.  I think it would be best if you could group
these into two categories:
1 - easy ones - lump all of the ones
that you think are no-brainers into one new issue and propose it to the
TC
2 - thought required ones - open new,
individual issues, for each one so people can deep-think about each one.
 These might actually go pretty quickly and could actually allow us
to resolve more than one or two issues per phone call.  :-)
I'd actually like the trivial editorial
changes you made lumped into a single no-brainer proposal - or perhaps
nothing as formal as that - just some kind of marked-up document that the
TC members could scan to make sure they're all ok with.  No negative
comments back within say a week implies we use that doc as the new base
spec.
thanks
-Doug

Anish Karmarkar <Anish.Karmarkar@oracle.com>

09/12/2005 02:29 AM

To	Marc Goodner <mgoodner@microsoft.com>
cc	ws-rx-editors@lists.oasis-open.org
Subject	Re: [ws-rx-editors] Non-trivial editorial comments

I have not heard any other response (from the other
editors) on the 
non-trivial changes. Any other comments?

Marc: my responses below within <ask></ask>. Thanks for reviewing
the 
changes and sending comments.

I have gotten one response on the trivial changes (from Doug saying that
it looked ok to him). If I don't hear anything about the trivial 
changes, I'll forward it to the TC before this week's call.

-Anish
--


Marc Goodner wrote:
> Wow, that's a lot of changes. I have detailed comments below <mg>.
I
> think some of these are fine, some I think you should raise editorial
> issues. I also promised to look into some of your proposed changes
that
> I can't answer, I'll try to respond by tomorrow.
> 
> I think when the next round of pending issues gets incorporated here
a
> WD and redline should be produced with a similar note style to what
you
> have here. Instead of commenting on what editorial changes you want
to
> make it should explain the redline editorial changes. I would advise
to
> play it safe and raise an editorial issue if you ever think a change
is
> substantive or sensitive.
> 
> Regards,
> Marc g
> 
> 
> -----Original Message-----
> From: Anish Karmarkar [mailto:Anish.Karmarkar@oracle.com] 
> Sent: Tuesday, August 16, 2005 6:29 PM
> To: ws-rx-editors@lists.oasis-open.org
> Subject: [ws-rx-editors] Non-trivial editorial comments
> 
> All,
> 
> Attached are the .sxw and .pdf files that include the non-trivial
> editorial comments (in the form of OO Notes) that I mentioned in 
> my previous email.
> 
> The attached .sxw file contains OO Notes (equivalent of 
> WS-Word/Acrobat Comments). But the OO Notes are hard to read and 
> list (not very helpful compared to Word/Acrobat). They can only 
> be listed when printing.
> 
> While converting to PDF, OO provides an option to list the Notes 
> at the end of every page (on which they occur). The attached PDF 
> file contains such listing.
> 
> There are only three ways to look at the Notes: (1) look at the 
> PDF, (2) move your cursor over the tiny yellow rectangle (where 
> the comment appears) in .sxw file, (3) print the doc and specify 
> in the options that you want the Notes.
> 
> To make it easier, I have listed all the Notes at the end of 
> this email.
> 
> I have turned the change bars off to remove the clutter from 
> the previous edit. Please note that I have made two new inlined
>  changes:
> 
> Line 268:
> <previous>
> children and/or attributes MAY be added at the indicated extension
> points
> </previous>
> <new>
> children elements and/or attributes MAY be added at the indicated
> extension points
> </new>
> 
> <mg>Seems OK
> 

<ask>
I'll include this as part of the trivial changes.
</ask>

> Lines 346-347:
> <previous>
> <wsrm:SequenceAcknowledgement> header block at any point.  The
timing of
> acknowledgements can be advertised
> <previous>
> <new>
> <wsrm:SequenceAcknowledgement> header block at any point during
which
> the sequence is valid.  The timing of acknowledgements can be
advertised
> </new>
> 
> <mg>Seems OK
> 

<ask>
I'll include this as part of the trivial changes.
</ask>

> 
> Comments?
> 
> -Anish
> --
> 
> 
> Summary of Notes:
> --------------------
> Page : 2 Line : 22 Author : AK 08/16/2005
> This seems out of place. I would like to suggest that we add a new
> subsection under
> introduction called 'Relation to other specification'. We can include
> this para as well as
> stuff about conformance to WS-Addressing in it.
> 
> <mg>I'm not as convinced it needs to be moved, I'm open to the
> suggestion though.
> 

<ask>
That section just looks out of place. The usual order is: abstract, 
followed by Introduction. A lot of spec (eg soap 1.2 etc) include a 
'relation to other specs' where they talk about related specs, 
restrictions if any, etc etc. I also think that the spec needs a clear
statement about conformance to WS-Addressing . WS-Addr is one WS spec 
that is absolutely required (where as SOAP/WSDL are not). All of this 
logically seems to belong to a section such as 'Relation to other spec'.
Also see the comment about line 120. But I'm open to other suggestions
too.

[.1] http://www.w3.org/TR/2003/REC-soap12-part1-20030624/#reltoxml

</ask>

> Page : 5 Line : 92 Author : AK 08/16/2005
> It would be nice to use language similar or same as the
> WS-Addressing/WSDL 2.0 spec
> which use the same notation (modulo copyright concerns). This is of
> course not critical,
> just consistency across ws-* specs. Regardless, we do need to add
> statements about what
> {any} and @{any} mean
> 
> <mg>Agreed on the anys
> 
> Page : 6 Line : 109 Author : AK 08/16/2005
> This is ambigious. How about replacing this stmt by something like:
> "Elements defined by this specification below to the following
namespace
> ..."
> 
> <mg>I don't really agree that it is ambiguous. Let me look at
some other
> examples and respond.
> 

<ask>
Ok. Will wait for your response.
The ambiguity is in -- what does it mean to implement a namespace? What
we really want to say is that the elements defined in this particular 
spec below to the http://schemas.xmlsoap.org/ws/2005/02/rm namespace URI.
</ask>

> Page : 6 Line : 118 Author : AK 08/16/2005
> Add the following:
> Namespace names of the general form "http://example.org/..."
and
> "http://example.com/..." represent application or context-dependent
URIs
> (see RFC 2396
> [RFC 2396]).
> 
> <mg> Sure
> 
> Page : 6 Line : 120 Author : AK 08/16/2005
> This para shouldn't be under the 'namespace' subsection. How about
> moving this to the
> 'relationship with other spec' subsection?
> 
> <mg> Hmmm, I suppose
> 
> Page : 9 Line : 172 Author : AK 08/16/2005
> This is the same definition as ws-addressing. I would like to suggest
> that we just point to
> the ws-addr spec for this.
> 
> <mg>I usually agree with points like that but I'm not so sure
we want to
> remove the definition of Endpoint. Maybe a subsection of terms used
> throughout this spec that are defined elsewhere? Still ugly.
> 

<ask>
Yes, that is ugly.
But why would we not want to point to the WS-Addressing spec, since the
meaning is exactly the same and there is a normative dependency on 
WS-Addr spec anyway. WSRM talks about endpoints in the same way as 
ws-addr does and uses EPRs to identify them which are defined in 
WS-Addressing. Having a definition which is different from WS-Addressing
but using EPRs to identify the endpoints would be very weird.
</ask>

> Page : 13 Line : 239 Author : AK 08/16/2005
> This paragraph is applicable to section 3 as well as section 4. Suggest
> that we move this
> to section 1.
> 
> <mg>Makes sense.
> 
> Page : 13 Line : 267 Author : AK 08/16/2005
> Change it to say : "... mustUnderstand attribute with a value
of 1/true
> ...'
> 
> <mg>Sure
> 
> Page : 13 Line : 270 Author : AK 08/16/2005
> there are several reference to RFC2396. 2396 is obsoluted by 3986.
> Or like ws-addressing we could move to IRIs (RFC 3987)
> 
> <mg>We might want to flag this one at a higher level than just
an
> editorial issue.
> 

<ask>
Agreed. This is much more than editorial.
</ask>

> Page : 14 Line : 273 Author : AK 08/16/2005
> The phrase 'based on schemas' (or 'based on schema to be passed')
is
> used anywhere
> extensibility is defined. I don't understand this phrase. If the
> intention is to say that the
> extensibility attributes/elements must not be from the WSRM schema
> ("##other") then
> we should say exactly that.
> 
> <mg>I'd like to double check that one, I'll try to get an answer
> tomorrow. Please bug me if I forget. (I've only got two hours
> unaccounted for...)
> 

<ask>
considered yourself bugged. :-)
</ask>

> Page : 14 Line : 294 Author : AK 08/16/2005
> not quite accurate. I would like to suggest that we use the XPATH
> notation used above.
> I.e. /wsrm:Sequence/wsrm:LastMessage
> 
> <mg>Makes sense
> 
> Page : 15 Line : 313 Author : AK 08/16/2005
> A better way to say 'return messages' is to say:
> '... included in a response message, in the case of a request-response
> pattern'.
> 
> <mg>Sure, but a SequenceAcknowledgement does not necessarily
come back
> on a response of a request-response mep which is probably why the
> current wording is the way it is. I can certainly read over it easily
> enough to get that would be a resp in a req/resp mep. I think its
fine
> as is.
> 

<ask>
Thinking more about this, I think this is perhaps a non-editorial issue.
It is not just a return or a response message that it can be included,
it can be included in any non-return message as well. I.e., consider a
bidirectional RM sequence (but over a one-way transport like an email 
binding or over two different protocols). The messages sent in the 
opposite direction may not be a response/return message and is sent as
an independent message. It should be perfectly ok (my 
interpretation/opinion) to have a wsrm:SequenceAcknowledge header blocks
on such unrelated messages.
</ask>

> Page : 15 Line : 338 Author : AK 08/16/2005
> should 'optional' and 'required' words in the spec be converted to
RFC
> 2119 OPTIONAL
> and REQUIRED. The occurrances seem to indicate the same meaning as
the
> RFC
> 
> <mg>For lines 332 and 338 I think you are right. I can run that
around
> here as well. I think this is a case by case and not a global search
> replace though.
> 

<ask>
I should have better qualified my comment. I meant that this be replaced
only in section 3.
</ask>

> Page : 15 Line : 341 Author : AK 08/16/2005
> Given that there can be multiple SeqAck headers in a message, an
> accurate way of saying
> this is:
> "... MUST NOT be present if a sibling <wsrm:Nack> element
is also
> present ..."
> 
> <mg>I think you are right.
> 
> Page : 21 Line : 534 Author : AK 08/16/2005
> too vague. A wsrm:Offer element can be in the extensibility point.
A
> better way would be
> to use the xpath like syntax that is already being used.
> 
> <mg>I don't think that is vague. Maybe hard to understand but
not vague.
> ;-) Anyway what would your proposed text be? I can't quite work out
what
> xpath statement + wording would make that easier to grok.
> 

<ask>
It is not accurate for the following reason:
Consider the case where there is an element -- 
/wsrm:CreateSequence/myns:Foobar/wsrm:Offer

In this case, the <wsrm:CreateSeqence> message does *contain* wsrm:Offer
element, but that is not what we are concerned with.

I would suggest replacing:
"This element MUST be present if the corresponding <wsrm:CreateSequence>
message contained an <wsrm:Offer> element."

with:
"This element MUST be present if the corresponding <wsrm:CreateSequence>
message contained an /wsrm:CreateSequence/wsrm:Offer element."

</ask>

> Page : 24 Line : 597 Author : AK 08/16/2005
> The default fault action URI is defined only for the SOAP binding
and it
> is meant only for
> ws-addressing related faults. This para should be deleted OR specific
> action(s) should be
> defined for WSRM faults.
> 
> <mg>I think you should raise an editorial issue on this one.
> 

<ask>
Ok. Will do.
</ask>

> Page : 24 Line : 598 Author : AK 08/16/2005
> this means any version of ws-addressing that is used in the message.
> If that is not the intend (which I don't think it is), we need to
tie it
> down to a specific
> version of WS-Addressing (W3C one)
> 
> <mg>I say make this part of the issue above. Note that an issue
needs to
> be raised to add the W3C version of Addressing as well. I agree the
> investigation should be done now but we should point to both the
> contribution and the final Rec. I believe that the Rec will get out
> before we're done.
> 

<ask>
Ok. Will do.
I think WS-addr will be a REC before WSRM is done, as well.
</ask>

> Page : 26 Line : 678 Author : AK 08/16/2005
> I assume this is intended to say fault [subcode]. Is that correct?
> 
> <mg>Don't know, I'll add it to my investigate list.
> 

<ask>
Any input on this?
</ask>

> Page : 32 Line : 813 Author : AK 08/16/2005
> The reference style is inconsistent. Sometimes the author name is
listed
> first, sometimes it
> is title first.
> 
> <mg>Fix it.
> 

<ask>
will do.
</ask>

> Page : 32 Line : 818 Author : AK 08/16/2005
> need a soap 1.2 ref too
> 
> <mg>Yeah, seems like an oversight to not have it in the namespaces
at
> the beginning as well.
> 

<ask>
I'll go ahead and add it.
</ask>

> Page : 32 Line : 820 Author : AK 08/16/2005
> never used. need to include this (or IRI) ref where ever 2396 is used
> 
> <mg>Good catch.
> 
> Page : 32 Line : 825 Author : AK 08/16/2005
> never used. this could be reference where we talk about schema
> 
> <mg>Good catch.
> 
> Page : 32 Line : 827 Author : AK 08/16/2005
> never used. could be used where we talk about schema types
> 
> <mg>Good catch.
> 
> Page : 32 Line : 833 Author : AK 08/16/2005
> this isn't used either. Why is this a normative reference?
> 
> <mg>The reference is not used but it should be where Secure
Conversation
> is discussed in the Security Considerations section.
> 

<ask>
The question is, why is it normative?
But this isn't an ed. question. I'll raise this as a separate issue.
And you are right that it needs to be referenced from the Security 
consideration section.
</ask>

> Page : 32 Line : 836 Author : AK 08/16/2005
> should be removed, never used
> 
> <mg>I thought there was reference to this somewhere. I'd like
to double
> check this.
> 

<ask>
I searched for it, it is not there.
</ask>

> Page : 33 Line : 842 Author : AK 08/16/2005
> none of these references are used
> 
> <mg>I suppose so.
> 
> 
> <mg>OK it's late I can't check the rest of that tonight. My
initials may
> be mg, I may work for Microsoft, but I am NOT a human schema processor.
> 
> Page : 34 Line : 860 Author : AK 08/16/2005
> why is this import needed?
> 
> Page : 34 Line : 880 Author : AK 08/16/2005
> all other types are non-anon types. Why is this an exception? for
> consistency I would
> suggest making this a non-anon type
> 
> Page : 35 Line : 887 Author : AK 08/16/2005
> should we restrict the unsignedLongs to be > 0?
> 
> Page : 35 Line : 907 Author : AK 08/16/2005
> The spec uses wsrm:MessageNumber not wsrm:MaxMessageNumberUsed. The
spec
> also
> says that if there is a diff between the schema and the spec then
the
> spec wins. But I'm not
> sure if this is true in this case.
> 
> Page : 36 Line : 931 Author : AK 08/16/2005
> for consistency should we call this FaultCodeType
> Page : 36 Line : 943 Author : AK 08/16/2005
> should this be tns:FaultCodes instead of xs:QName?
> 
> Page : 36 Line : 963 Author : AK 08/16/2005
> Schema does not contain SecurityTokenReference but the spec does
> 
> Page : 48 Line : 1254 Author : AK 08/16/2005
> why is this imported? It is never used.
> 
> --------------------