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


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