[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]