[OASIS Issue Tracker] Created: (AMQP-22) Transport: Incoporate feedback from Steve Huston's review

[OASIS Issues Tracker <workgroup_mailer@lists.oasis-open.org>]

Transport: Incoporate feedback from Steve Huston's review
---------------------------------------------------------

                 Key: AMQP-22
                 URL: http://tools.oasis-open.org/issues/browse/AMQP-22
             Project: OASIS Advanced Message Queuing Protocol (AMQP) TC
          Issue Type: Improvement
            Reporter: Rob Godfrey
            Assignee: Rob Godfrey


Incorporate feedback from Steve Huston's review Transport part of the document.

This JIRA covers small changes and minor corrections, typos, grammar and punctuation errors within the Transport part... in particular it is aimed at addressing the following points from Steve's mail(s):

Part 2, section 1, 5th para, 1st sentence: "Specification" should not be
capitalized.

Part 2, section 2, 3rd para, 1st sentence: insert "actively" before
"opened"; replace "TCP Session" with "TCP connection."

Part 2, section 3.1, DOFF description, 3rd sentence: insert "an" between
"data offset is" and "unsigned". Insert comma after "unsigned". 4th
sentence, insert hyphen between "8" and "byte" to make "mandatory 8-byte
frame header"

Part 2, section 3.1, TYPE description, 5th sentence: Remove parentheses;

Part 2, section 3.2, 2nd paragraph: Replace "time-out" with "timeout".

Replace "See 4.5 Idle Time-out of a Connection." with "(see section 4.5)"
immediately after preceding "interval" inside the closing period.

Part 2, section 4, 3rd para, 2nd sentence: remove quotes from "same".

Part 2, section 4.2, 1st para, 3rd sentence: "a priori" should be in
italics.

Part 2, section 4.5, heading: replace Time Out with Timeout
throughout text in that section: replace time-out with timeout

Part 2, section 4.5, 8th para, 1st sentence: Replace time-out's with
timeout.

Part 2, section 4.5, 4th para, 1st sentence: Replace "is any" with "is in"
addition...

Part 2, section 4.5, 5th para, 1st sentence: Add comma after "i.e."

Replace "up to channel-max"
with "up to the maximum negotiated channel number" (haven't seen
channel-max yet).

Part 2, section 4.5, 8th para, 1st sentence: Add comma after "e.g."


Part 2, section 4.6, don't speak in 2nd person:
HDR_RCVD: In this state the connection header has been received from the
peer but a connection header has not been sent.
HDR_SENT: In this state the connection header has been sent to the peer
but no connection header has been received.
OPEN_PIPE: In this state both the connection header and the open frame
have been sent but nothing has been received.
OC_PIPE: In this state, the connection header, open frame, any pipelined
connection traffic, and the close frame have been sent but nothing has
been received.
OPEN_RCVD: In this state connection headers have been exchanged. An open
frame has been received from the peer but an open frame has not been sent.
OPEN_SENT: In this state connection headers have been exchanged. An open
frame has been sent to the peer but not open frame has yet been received.
CLOSE_PIPE: In this state connection headers have been exchanged. An open
frame, any pipelined connection traffic, and the close frame have been
sent but no open frame has yet been received from the peer.
OPENED:    just transpose "both" and "been"
CLOSE_RCVD: In this state a close frame has been received indicating that
the peer has initiated an AMQP close. There should be no further frames
arriving on the connection; however, frames can still be sent. If desired,
an implementation MAY do a TCP half-close at this point to shut down the
read side of the connection.
CLOSE_SENT: In this state a close frame has been sent to the peer. (next
sentence unchanged). If desired, an implementation MAY do a TCP half-close
to shut down the write side of the connection.
DISCARDING: (no change)
END: (no change)

Part 2, section 5.4, 1st para, 2nd sentence: Replace "hearing" with
"receiving"

Part 2, section 5.5, last sentence: replace "when" with "after"; replace
"is in" with "transitions to"; period after "state". Remove remainder of
sentence. A thing that is nonexistent does not have a state; also, there's
no mention of a nonexistent state.


Part 2, section 5.6, next-incoming-id: replace "implicit" with "expected".

Part 2, section 5.6, next-outgoing-id: Replace 1st sentence with "The
next-outgoing-id is the transfer-id to assign to the next transfer frame."

Part 2, section 5.6, remote-outgoing-window, 2nd sentence, "fo" should be
"of"

Part 2, section 5.6, receiving a flow: change "as well as copy" to "and it
MUST update"


Part 2, section 6, 2nd para, 2nd sentence: change to "Therefore, there are
two types of endpoint: senders and receivers."

Part 2, section 6.1, 2nd para: Replace "e.g." with "i.e.," (note comma)

Part 2, section 6.1, 3rd para, 2nd sentence: add comma after "i.e."

Part 2, section 6.1: there should not be a paragraph break between the
current 2nd and 3rd paragraphs.

Part 2, section 6.3, 6th para, last sentence: "acceptable, or if not,
detach." should be "acceptable, or, if not, detach the link."

Part 2, section 6.3, 7th para, 2nd sentence: "pre-empt" should be
"preempt"

Part 2, section 6.7, 1st para, 3rd sentence: Remove "when" (either that or
complete the phrase).

Also, it would be good to state what delivery-count _is_ - it's never
stated,  but must be inferred from the way it is handled.

Part 2, section 6.7, link-credit, 4th para, add comma after "i.e." (2
times)

Part 2, section 6.7, 1st para after the states list: add comma after
"i.e."

Part 2, section 6.7, 1st para after the states list: "... it is illegal to
send more messages." should be "...a sender MUST NOT send more messages."


Part 2, section 6.10, 2nd sentence: "in-flight" should be "in flight"

Part 2, section 6.12, 3rd para, last sentence: add '.' between "etc" and
","

Part 2, section 6.12, 5th para, 3rd sentence: Add comma after "e.g."

Part 2, section 6.12, 6th para, 2nd sentence: "disposition" should be
courier, bold.

Part 2, section 6.12, 6th para: insert "of" after "update its view"

Part 2, section 6.12, 9th para, 1st sentence: add comma after "e.g."

Part 2, section 6.12, 10th para, 1st sentence: add comma after "i.e."

Part 2, section 6.12, 14th para, 1st sentence: (don't speak in 1st person)
"Similarly, if we modify the basic scenario" change to "Similarly, if the
basic scenario is modified". Also, "we get an at-least-once guarantee."
should be "that yields an at-least-once guarantee."

Part 2, section 6.12, 15th para, 2nd sentence: "... sender settles before
his initial transmission." should be "sender settles before the initial
transmission."

Part 2, section 6.12, 16th para, 1st sentence: "pre-configured" should be
"preconfigured"

Part 2, section 6.12, 13th para, 1st sentence: Change "...achieve
different guarantees, for example if the sending..." to "...achieve
different guarantees. For example, if the sending..."

Part 2, section 7.1, hostname: Remove "dns" from first sentence? It's not
going to be used to do a lookup, and use of a proxy may make it useful to
specify some name other than one registered in DNS.


Part 2, section 7.1, hostname, 2nd para, last sentence: "... what a
different value to those already..." should be "... what a different value
from that already..." and "specific" should be "specified" (but I think
I've seen the "specified" change reported already).

Part 2, section 7.1, max-frame-size, last sentence: Remove "large" at the
end.

Part 2, section 7.1, idle-time-out: "time-out" should be "timeout". "eg,"
should be "e.g.,".  Near "close the connection with an error ..."

Part 2, section 7.1, incoming-locales, 3rd sentence: "The receiving
partner will chose..." should be "The receiving partner will choose..."

Part 2, section 7.1, offered-capabilities: Remove "the" from description
"the extension capabilities" - "the" isn't used on most of the
descriptions, so remove it to be consistent.

Part 2, section 7.1, desired-capabilities: Remove "the" from description
"the extension capabilities" - "the" isn't used on most of the
descriptions, so remove it to be consistent.

Also, 1st sentence: add comma after "i.e."
Part 2, section 7.3, name: Add comma after "e.g." 

Part 2, section 7.3, handle: Recommend adding a descriptive phrase (others
have one in italics) and a descriptive sentence about what the handle is
before restricting it. Suggest basing this on the first two sentences in
section 6.2.

Part 2, section 7.3, role: Recommend adding a descriptive sentence for
role, esp  noting that it's a sender/receiver distinction.


Part 2, section 7.3, unsettled, 2nd para, 1st sentence: capitalize MAY.
Also, "(see amqp-error)" should be "(see section 8.15)"

Part 2, section 7.3, initial-delivery-count: Add a short descriptive
phrase (others have one in italics) and a descriptive sentence about what
the initial-delivery-count is before restricting it.


Part 2, section 7.4, next-incoming-id, 2nd sentence: should be "This value
MUST be set unless the sender has not yet received the begin frame for the
session."

Part 2, section 7.4, echo, 2nd para, 1st sentence: "...state to be echoed,
however the receiver MAY fulfil this..." should be "...state to be echoed;
however, the receiver MAY fulfill this..."
Also, "...flow performative carrying link specific state" should be
"...flow performative carrying link-specific state"

Part 2, section 7.5, delivery-tag, 2nd sentence: "multi transfer" should
be "multi-transfer"

Part 2, section 7.5, settled: Does "first" and "subsequent" transfers
refer to multi-transfer messages, or to resuming? Also, 2nd para, 1st
sentence: add comma after "i.e."

Part 2, section 7.5, more: "That is a receiver..." add comma after "is".

Part 2, section 7.5, state, 2nd sentence: "deliveries are resumed after a
resuming a link." delete first "a"
Also, 2nd sentence, add comma after "i.e."

Part 2, section 7.6, 2nd para after XML, 1st sentence: add comma after
"i.e."

Part 2, section 7.7, 1st para after XML, 2nd sentence: "un-maps" should be
"unmaps"


Part 2, section 8.10, 2nd sentence: Remove comma after "arithmetic"

Part 2, section 8.16, hostname, 2nd sentence "suring" should be "during"


-- 
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://tools.oasis-open.org/issues/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira