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

["Marc Goodner" <mgoodner@microsoft.com>]

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

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


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.

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.

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.

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.

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...)

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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