OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

wsrm message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: Re: [wsrm] Editorial comments on WS-Reliability-0.52b


Tony,

Thanks for your comments.
It would be very helpful.
I will work through the spec with your comments.
Some updates may require TC discussion, which I
am not sure at this point, but editorial updates will be
incorporated into the spec directly for following TC
review. This email is just for letting you
I'm working for your comments.
Thanks,

Iwasa

----- Original Message ----- 
From: "Tony Graham" <Tony.Graham@Sun.COM>
To: "'wsrm-TC'" <wsrm@lists.oasis-open.org>
Sent: Tuesday, October 21, 2003 8:59 AM
Subject: [wsrm] Editorial comments on WS-Reliability-0.52b


> I did some proofreading of the current 052b version of the spec.
>
> The following is offered with the expectation that some of the points
> presented here will have already changed or been corrected in the
> editor's copy but also that some of what remains will be useful to the
> spec editor.
>
> Regards,
>
>
> Tony Graham
> ------------------------------------------------------------------------
> XML Technology Center - Dublin
> Sun Microsystems Ireland Ltd                       Phone: +353 1 8199708
> Hamilton House, East Point Business Park, Dublin 3            x(70)19708
>
>
> Line    Comment
>
> -       Spell-check the document.
>
> 4       Why is the date in the title block abbreviated when the full
>         date is in the footer?
>
> 17      Change "periodically on no particular schedule" to
>         "aperiodically".  If it's on "no particular schedule" then
>         it's
>         "aperiodic", not "periodic".
>
> 17, 19  These lines say to only send comments to the spec editor and
>         to only send comments to one of two OASIS TC lists.
>
>
> Table of Contents
>
> 30      Add space between section numbers and section titles in the
>         Table of Contents.
>
> 62      Show the Appendices in the Table of Contents.
>
>
> Section 1.1, Purpose of WS-Reliability
>
> 66      Add a reference to SOAP 1.2 after the reference to SOAP 1.1.
>
>
> Section 1.2, Scope and Definition of Reliable Messaging
>
> 87, 109 The draft should be consistent about whether or not to place
>         periods at the end of non-sentence bullet points.  For
>         example, line 87 is "Asynchronous messaging at the application
>         level" (i.e., without period), and line 109 is "A mechanism to
>         guarantee message delivery and its expression in SOAP
>         messages." (i.e., with period).
>
> 88, 89, 92-95
>         Why are these lines in italics?
>
> 92      Add a bullet at the beginning of the line.
>
>
> Section 1.3, Out of scope of this specification are:
>
> 97      Use capitalization that is consistent with other section
>         titles.  Do not end the section title with a colon.
>
>         It may be best to make the section title something like
>         "Limits of Scope" and make the current section title the first
>         paragraph of the section.
>
> 98-101  Remove the commas and last "and" in the second sentence so it
>         becomes:
>
>            Applications which intentionally use synchronous messaging
>            at the application level require knowledge of the error
>            status immediately rather than waiting for the messaging
>            layer to resend the message when an error returns are out
>            of scope of this specification.
>
>         This could possibly be rewritten as:
>
>            Synchronous messaging applications that require knowledge
>            of the error status immediately rather than waiting for the
>            messaging layer to resend the message when an error returns
>            are out of scope of this specification.
>
> 102, 104
>         Be consistent and use either "techniques" or "mechanisms" to
>         describe routing and security since using two terms makes a
>         distinction that isn't really significant for the purposes
>         of this specification.
>
> 102     Remove one of the two spaces before "with".
>
>
> Section 1.4, The Goal of this specification
>
> 107     Remove the "The" and use capitalization consistent with other
>         section titles.
>
>         The title could then become "Goal of This Specification".
>
>
> Section 1.6, Relation to Other Specifications
>
> 126     SOAP 1.2 became a W3C Recommendation in June 2003.
>
>
> Section 1.7, Examples of Messages compliant with WS-Reliability
>
> 138     Change "compliant" to "Compliant" for capitalization
>         consistent with other section titles.
>
>
> Section 1.8, Terminology
>
> 160     Remove the comma after "node".
>
> 170     Remove the " ." at the end of the line.
>
>
> Section 2, Messaging Model
>
> 174     Change "section" to "sections".
>
>
> Section 2.1, Overview of the Messaging Model ( Need to include
>              additional messaging model)
>
> 175     Remove the space after "(".
>
>
> Section 2.2, Overview of the Acknowledgment Message
>
> 185     Change "reliable message" to "Reliable Message".
>
> 185     Change "server" to "receiver".
>
> 186     Change "Acknowledge" to "Acknowledgment".
>
> 189     Change "delivery" to "Delivery" for capitalization consistent
>         with other figure titles.
>
> 195, 196
>         This is just a restatement of line 186.
>
>
> Section 2.3, Message Identifier
>
> 201     Change "Acknowledged" to "acknowledged" since "Acknowledged
>         message" is not part of the WS-R terminology.
>
> 202     Remove the space after "(".
>
> 203     Remove the space before ")".
>
>
> Section 2.5, Message Persistence
>
> 217     Change the font and/or style of "ExpiryTime" to match the rest
>         of the text.
>
> 218     Change "ordered delivery" to "guaranteed message order" (or
>         "guaranteed message ordering") to better match the term that
>         is more commonly used in the specification.
>
>
> Section 2.6, Duplicate Elimination
>
> 225     Remove "value" since the Message Identifier is not a single
>         element or attribute's value.
>
> Section 2.7, Guaranteeing Message Order
>
> 227     Change "Guaranteeing" to "Guaranteed" so the section title
>         matches the common usage of the term in the rest of the spec.
>
>         Note also that "message ordering" appears more times in the
>         WS-R issues list than does "message order", so perhaps the
>         common usage is "guaranteed message ordering".
>
> 231     Change "Message Order" to "message order" since "Message
>         Order" is neither defined in the terminology section nor a
>         section title in the specification.
>
> 233     It is odd that Figure 3 is explained in the section following
>         the section containing Figure 3 (and without stating that the
>         explanation is the explanation for Figure 3).
>
>
> Section 2.8, Sequence Number (Need updating)
>
> 235     Change "Need" to "Needs".
>
> 238     The "For example" raises the expectation that the example will
>         be an example of past usage of a sequence number mechanism.
>
>
> Section 3, Message Format
>
> -       Only some element definitions note what fault the elements can
>         cause.  For example, the defintion of "ExpiryTime" does, but
>         the definitions of "Timestamp" and "AckRequested" do not.
>
> -       All the element and attribute definitions could be clearer and
>         less wordy if they each had a table indicating their
>         optionality and allowed content, e.g.:
>
>            3.1.3  Timestamp Element
>
>            Required:   Yes
>            Value:      dateTime
>            Attributes: None
>            Fault:      InvalidTimestamp
>
>
>            3.2.1  AckRequested Element
>
>            Required:   No
>            Value:      Empty
>            Attributes: None
>            Fault:      InvalidAckRequested
>
>         Of course, the definitions would still need explanatory text
>         (and sometimes the entries in the table would have to be "See
>         text", or similar), but it could save a lot of words.
>
> 255, 256
>         Change "WS-Reliability" to "WS-Reliability elements" or
>         "WS-Reliability header blocks".
>
> 256     Correct the font of "ExpiryTime" and "ReplyPattern".
>
> 256     "RM:ReplyTo" is no longer an element.
>
> 256     Add "RM:MessageOrder" to "RM:Request".
>
> 256     Only three sides of "RM:RefToGroupId" show thick borders.
>
> 256     "RM:FaultCode" should have thick borders.
>
> 303     "RM" is a prefix, not a namespace.
>
> 304     Change "stand alone" to "standalone".
>
> 305     Remove the comma after "elements".
>
> 310     Add a comma after "way".
>
> 312     Remove the comma before the period at the end of the line.
>
>
> Section 3.1, MessageHeader Element
>
> 317     Change "sub-elements" to "child elements" for consistency with
>         lines 292 and 433.
>
> Section 3.1.1, GroupId Element
>
> 336     Add "the" or "a" before "GroupId".
>
>
> Section 3.1.2, SequenceNumber Element
>
> 343     Change "Guranteeing Ordered Delivery" to match the title of
>         Section 2.7.
>
> 344     Change "Guranteed Ordered Delivery" to match the title of
>         Section 2.7.
>
> 344     Add "be" after "MUST NOT".
>
> 345     Change "with a same" to "within the same".
>
> 347     Add "a" before "MessageOrder".
>
> 347     Change "this" to "the SequenceNumber".
>
>         The "this" is ambiguous as it could refer to either the
>         "MessageOrder" element or the "SequenceNumber" element.
>
> 348     Change "categorized" to "specified"
>
>         Line 328 says GroupId "is used to specify a group of
>         messages."
>
> 352     Remove the space characters at the start of the line.
>
> 352     Change "Guaranteed message delivery" and "Guaranteed message
>         delivery" to match the title of Section 2.7.
>
> 354     Add "an" before "AckRequested".
>
> 354     Add "a" before "DuplicateElimination".
>
> 355     Make a new paragraph for "This element includes the following
>         attribute:".
>
>         The sentence has nothing to do with the rest of the paragraph.
>
> 357     Change "a status attribute" to "status".
>
>         It is already clear that "status" is an attribute.
>
> 360     The sentence beginning "In other words" is unnecessary.
>
>         The sentence is a restatement of the restatement beginning on
>         line 349.
>
> 365     Remove "Example of" and capitalize "element" for consistency
>         with other example titles (and because "Example of" is
>         superfluous).
>
> 366     Change "was" to "is".
>
> 368     Change "distinct" to "independent".
>
> 369     Remove "independently".
>
> 370     The "SequenceNumber" element value for a new GroupId should be
>         0, not just "new".
>
> 372     Change the second sentence to:
>
>            For the initial message with a specific GroupId that is
>            sent to the receiver, the SequenceNumber value must be 0.
>
> 375     Remove the comma after "one".
>
> 385-387 Change each occurrence of "series" to either "group" or
>         "sequence".
>
>         It is better to use the terms used by WS-R.
>
> 393     What does "Because delivery between the reliable messaging
>         provider and the sequence is not specified" mean?
>
>         How can a piece of software deliver to a sequence of numbers?
>
> 393     Change "reliable messaging provider" to "Reliable Messaging
>         Processor".
>
>
> Section 3.1.3, Timestamp Element
>
> 398     Change "message header" to "MessageHeader".
>
>
> Section 3.1.4, ExpiryTime Element
>
> 402     Change "This element" to "The ExpiryTime element" for
>         consistency with other element definitions.
>
>
> Section 3.1.5, ReplyPattern element
>
> 409     Change "element" to "Element" for capitalization consistent
>         with other section titles.
>
> 411     "MANDATORY" is not a term defined by RFC 2119 and should
>         either be replaced by a RFC 2119 term or not be in uppercase
>         letters.
>
> 412     Change "Message" to "message".
>
> 412     Change "messages" to "message".
>
> 415-422 Fix the line spacing.
>
> 415     Change "Message" to "message".
>
> 416     Change "Reply" to "reply".
>
> 417     Remove the blank line.
>
> 418     Add a period at the end of the line.
>
> 419     Change "Message" to "message".
>
> 420     Change "element" to "attribute".
>
> 421     Change "Message" to "message".
>
> 421     Add a space before "(".
>
> 428     Change "Acknowledgment" to "reply".
>
>
> Section 3.2, Request Element
>
> 434     Remove "a".
>
> 437     The "MessageOrder" element is not defined.
>
> 438     Fix the font and/or style of the text.
>
> 438, 439
>         There is no "ReliableMessage" element.
>
> 438     Correct the font and/or style of "ReliableMessage" (or its
>         replacement).
>
> 439     Remove "Example of" and capitalize "element" for consistency
>         with other example titles (and because "Example of" is
>         superfluous).
>
> 440     Change "are" to "to be".
>
>
> Section 3.2.1, AckRequested Element
>
> 443     Change "is to be used for" to "is used by".
>
> 444     Change "RM-Fault" to "Fault".
>
> 445     Change "received" to "receives".
>
> 446     Change "whether or not it" to "even when the message".
>
> 447     Change "RM-Fault" to "Fault message".
>
> 448     Change "RMReplyPattern" to "ReplyPattern".
>
>
> Section 3.2.2, DuplicateElimination Element
>
> 451     Should "2.3" be "2.6"?
>
>         Should the section cross-reference be generated by the word
>         processor instead of being hardcoded?
>
>
> Section 3.3, Response Element
>
> 460     Change "sub-elements" to "child elements" for consistency with
>         line 292.
>
> 464     There is no "ReliableMessage" element.
>
> 465     Change "And it" to "It".
>
> 466     Change "receiver send" to "the receiver sending".
>
> 466     Add "an" before "Acknoledgment".
>
> 469     Add "the" before "Response".
>
> 471     Remove "Example of" and capitalize "element" for consistency
>         with other example titles (and because "Example of" is
>         superfluous).
>
> 472     Change "was" to "is".
>
> 475     Change "the Acknowledgment" to "an Acknowledgment".
>
> 476     Change "the Fault" to "a Fault".
>
>
> Section 3.3.2, RefToSequenceNo Element
>
> 478     Change "Acknowledgment message" to "an Acknowledgment".
>
> 479     Change "Guranteed Message Ordering" to match the title of
>         Section 2.7.
>
> 481     Change "the Acknowledgment" to "an Acknowledgment".
>
> 482     Change "the Fault Message" to "a Fault message".
>
>
> Section 4, SOAP Fault (Need updating)
>
> 483     Change "Need" to "Needs".
>
> 486     Change "SOAP1.1" to "SOAP 1.1".
>
>
> Section 4.1, SOAP Fault extension for Reliable Messaging
>
> 489     Change "extension" to "Extension" for capitalization
>         consistent with other section titles.
>
> 490     Change "RMFault" to "Fault".
>
> 491     Change "sub-element" to "child element".
>
>
> Section 4.1.1, Fault element
>
> 492     Change "element" to "Element" for capitalization consistent
>         with other section titles.
>
> 494     Change "sub-element" to "child element"
>
> 495     The format of the "FaultCode" line is different from the
>         format of the other bullet list items introducing other
>         elements.
>
>
> Section 4.1.2, FaultCode element
>
> 496     Change "element" to "Element" for capitalization consistent
>         with other section titles.
>
> 497     Change "This sub-element" to "The FaultCode element" for
>         consistency with other element definitions.
>
> 501     Change "values" to "Values" for capitalization consistent with
>         figure and example titles.
>
> 501     Unset the fixed table row height to remove the extra
>         whitespace in the first table row.
>
> 501     There is no "RefToMessageId" element.
>
> 501     Correct the font and/or style of "ExpiryTime".
>
> 501     There is no "ReliableMessage" element.
>
> 501     Change "Acknowledgment Message" to "an Acknowledgment
>         message".
>
> 501     There is no "synchronous" attribute.
>
>
> Section 4.2, Fault code description
>
> 507     Change "code description" to "Code Description" for
>         capitalization consistent with other section titles.
>
>         Consider changing the section title to "Fault Codes".
>
> 508     Change "5-1" to "1".
>
>         Make this a cross-reference that the word processor fills in
>         with the correct number.
>
> 508     This section does not always provide more detail than Chart 1:
>         for example, Chart 1 provides more information about
>         InvalidTimestamp than does Section 4.2.4.
>
>         It is unnecessarily redundant to have mostly the same
>         information in both Chart 1 and Section 4.2.
>
>
> Section 4.2.1, InvalidMessageHeader
>
> 511     There is no "type" attribute or "Service" element.
>
> 511     Change "Element" to "element" (if there is a replacement for
>         "Service").
>
> 513     There is no "From" or "To" element.
>
>
> Section 4.2.3, InvalidRefToMessageId
>
> 518, 520
>         There is no "RefToMessageId" element.
>
>
> Section 4.2.5, InvalidEpiryTime
>
> 524     Change "InvalidEpiryTime" to "InvalidExpiryTime".
>
> 525, 526
>         Correct the font and/or style of "ExpiryTime".
>
>
> Section 4.2.6, InvalidReliableMessage
>
> 529     There is no "ReliableMessage" element.
>
>
> Section 4.2.8, InvalidMessageOrder
>
> 536     Change "it's" to "its".
>
>
> Section 5, HTTP Binding ( Needs to be updated)
>
> 539     Remove the space after "(".
>
> 541     What is "The WS-Reliability"?
>
> 543     Change "server" to "receiver".
>
> 552     Change "Message Sequence" to "message sequence" for
>         capitalization consistent with other headings at this level.
>
> 560     Remove "The".
>
> 563     Change "it" to "these".
>
> 564     Change "Message Sequence" to "message sequence" for
>         capitalization consistent with other headings at this level.
>
> 571     Change "Message Sequence" to "message sequence" for
>         capitalization consistent with other headings at this level.
>
>
> Section 5.2, Reliable Messaging with Asynchronous Acknowledgment
>         Message
>
> 584     Change "Figure" to "Figures".
>
> 585     Change "Message Sequence" to "message sequence" for
>         capitalization consistent with other headings at this level.
>
> 598     Change "the other" to "another".
>
> 604     Change "figure" to "Figures".
>
> 607     Change "Message Sequence" to "message sequence" for
>         capitalization consistent with other headings at this level.
>
> 613     Change "Message Sequence" to "message sequence" for
>         capitalization consistent with other headings at this level.
>
> 623     Remove "Example of".
>
> 624     Remove the space after "(".
>
> 624     Change "was" to "is".
>
>
> Section 6.2, Non-normative References
>
> 675-678 Update to refer to the SOAP 1.2 Recommendation.
>
> To unsubscribe from this mailing list (and be removed from the roster of
the OASIS TC), go to
http://www.oasis-open.org/apps/org/workgroup/wsrm/members/leave_workgroup.php.
>



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]