[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [amqp] Review notes for the remainder of AMQP 1.0 spec working draft
Hi Andreas, We're working to get the grammar right so that we flow through the OASIS process smoothly. As part of that, we've asked Steve to go through the document as "fresh eyes". We're not going to be making any changes that would affect any of our code bases or which would result in any different interpretations of the standard. cheers...angus On Nov-29-11, at 9:23 PM, Andreas Mueller wrote: > Thanks for the effort but IMO this is too late. This review should have been done before releasing the AMQP 1.0 spec by the WG. We can't restart this process so only if there are errors in the current 1.0 documents this require a change. > > Andreas > > > > Am 30.11.2011 um 01:30 schrieb "Steve Huston" <shuston@riverace.com>: > >> The remainder of my notes from reviewing the AMQP 1.0 spec working draft >> are below. >> >> As before, there are two sections: "Easy" are mostly copyediting things. >> "Questionable" are more technical questions I had which I think should be >> answered/corrected/clarified/etc. >> >> -Steve >> >> -- >> Steve Huston, Riverace Corporation >> Total Lifecycle Support for Your Networked Applications >> http://www.riverace.com >> >> >> >> (These start at part 2, section 7 - the first part was sent to the TC on >> Nov 22 so the remainder is here) >> >> These are also marked in the PDF paper copy. Here they're also classified >> according to how easy it is to fix (usually copyediting things) and how >> important it is (protocol things). >> >> Page numbers used are from the PDF copy. >> >> "The Chicago Manual of Style" is the standard I used for copy editing. >> >> >> Easy: >> >> 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: It may be a good idea to supply some introductory text >> to explain what the XML fields mean (class="composite" source="list" >> provides="frame") >> >> 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 ..." should >> maybe cross reference section 4.3 to clarify the intention is to close the >> AMQP connection, not the TCP connection (at least immediately). >> >> 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, there's more vertical space between the name and descriptive >> paragraph than for the other items >> Also, 1st sentence: add comma after "i.e." >> Also, it may be good to specify (if I understand this correctly) that the >> sender MUST NOT use a capability it does not list in desired-capabilities. >> >> 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, 1st para, last sentence: "See 6.13 >> Resuming Deliveries" should be "See section 6.13". >> >> 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. Also, "See 6.7 Flow >> Control" should be "See section 6.7". >> >> 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, next-incoming-id, 3rd sentence: "See 5.6 Session Flow >> Control" should be "See section 5.6" >> >> Part 2, section 7.4, incoming-window, 2nd sentence: "See 5.6 Session Flow >> Control" should be "See section 5.6" >> >> Part 2, section 7.4, next-outgoing-id, 2nd sentence: "See 5.6 Session Flow >> Control" should be "See section 5.6" >> >> Part 2, section 7.4, outgoing-window, 2nd sentence: "See 5.6 Session Flow >> Control" should be "See section 5.6" >> >> Part 2, section 7.4, delivery-count, 4th para: "See 6.7 Flow Control" >> should be "See section 6.7" >> >> Part 2, section 7.4, link-credit, 1st para, 4th sentence: "See 6.7 Flow >> Control" should be "See section 6.7" >> >> Part 2, section 7.4, available, 1st para, 4th sentence: "See 6.7 Flow >> Control" should be "See section 6.7" >> >> Part 2, section 7.4, drain, 1st para, 4th sentence: "See 6.7 Flow Control" >> should be "See section 6.7" >> >> 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 7.7, closed: should be "See section 6.6." >> >> Part 2, section 8.10, 2nd sentence: Remove comma after "arithmetic" >> >> Part 2, section 8.16, hostname, 2nd sentence "suring" should be "during" >> >> Part 3, section 2, 2nd para: "annotated message" should not be italicized. >> >> Part 3, section 2, 3rd para: "bare message" should not be italicized. >> >> Part 3, section 2, 3rd para: insert "three" before "sections" and insert a >> colon after "sections" >> >> Part 3, section 2, message diagram should have a Figure label. >> >> Part 3, section 2, 4th para, 2nd sentence: insert comma after "That is" >> >> Part 3, section 2, 4th para, 3rd sentence: Change "may not" to "MUST NOT"? >> >> Part 3, section 2, 5th para bullets, "The body...": "either" should be >> "one of the following three choices" (either refers to two) >> >> Part 3, section 2.1, 1st para after XML, 2nd sentence: What are the >> default values to be assumed, or where are they described? >> >> Part 3, section 2.1, ttl: Quotes around "live" are both close quotes. >> First one should be an open quote. (`` in latex, I believe) >> Also, last sentence: insert comma after "i.e." >> >> Part 3, section 2.1, first-acquirer: Add reference to section 3.1? >> (acquiring has not been discussed before this point) >> >> Part 3, section 2.3, 1st para, 3rd sentence: Add comma after "e.g." >> >> Part 3, section 2.3, 2nd para, 1st sentence: change comma before "however" >> to a semi-colon; add comma after "however" >> Also, change "however it" to "however, in" >> >> Part 3, section 2.3, 2nd para, 2nd sentence: "some annotation" should be >> "some annotations" (add an s) >> Also, after "purpose" change hyphen to an em-dash and "may be being" to >> "could be" >> >> Part 3, section 2.4, 1st para after XML, 2nd sentence: change to "The >> properties section is part of the bare message; therefore, if >> retransmitted by an intermediary, it MUST remain unaltered." >> >> Part 3, section 2.4, content-encoding, throughout: "Content-Encoding" >> should not be capitalized, except when starting a sentence where it can be >> "Content-encoding". >> Also, 5th para, "Content-encoding MUST not be set..." should be >> "Content-encoding MUST NOT be set..." >> >> Part 3, section 2.4, group-id, group-sequence: No mention of groups before >> this point; add a reference to where groups are discussed. >> >> Part 3, section 2.5, 2nd para: insert comma after "that is" and remove >> parentheses. >> >> Part 3, section 3, 3.1: There's only one subsection so there shouldn't be >> a division. Should be section 3 "Distribution Node Message States" >> Also, 1st para, 1st sentence: "distribution node" is not defined - it >> should be. Without that knowledge the rest of the section is difficult to >> understand. >> Also, 1st para, 2nd sentence: change comma before "however" to a >> semi-colon and add a comma after "however" >> >> Part 3, section 3.1, 3rd para, 3rd sentence: add comma after "e.g." >> Also, "default-outcome" - this isn't defined - where does it come from? >> >> Part 3, section 4, 1st and 3rd para: "delivery-state" should be "delivery >> state" >> >> Part 3, section 4.4, 1st para, 2nd sentence: add comma after "i.e." >> Also, 4th sentence: change comma after "frames have been sent" to an >> em-dash >> Also, 5th sentence: "time bound" should be "time-bound" >> >> Part 3, section 4.5, 1st para, 4th sentence: change comma after "frames >> have been sent" to an em-dash >> Also, 5th sentence: "time bound" should be "time-bound" and add comma >> after "e.g." >> >> Part 3, section 4.6, 1st sentence: "In Part 2: 6.13 Resuming Deliveries" >> should be "Part 2 section 6.13 provides" and delete "was provided" at the >> end of the sentence. >> >> Part 3, section 4.6, all the diagrams should have Figure labels. >> >> Part 3, section 4.6, 3rd para, 2nd sentence (same in 6th para, 2nd >> sentence and 8th para, 2nd sentence): Quotes around "at least once" and >> "at most once" are both close quotes; change leading one to an open quote. >> Also, should "at most once" be "exactly once"? at-most-once can be 0, >> which could result in a lost message which need not be retransmitted. >> Also, change comma before "however" to semi-colon and add comma after. >> (3rd para and 8th para) >> >> Part 3, section 4.6, 8th para, 3rd sentence: should insert "have" between >> "not" and "enough"? >> Also, "MAY take some action..." what might that action be? >> >> Part 3, section 4.6, 14th para, 2nd sentence: change "since we know" to >> "since it is known" and "we have no need" to "there is no need". >> >> Part 3, section 4.6, 15th para, 1st sentence: change "we have to assume" >> to "it must be assumed". >> >> Part 3, section 4.6, 18th para: should "state Receivedsection-number=0" be >> "state Received, section number=0"? >> >> Part 3, section 5.1, 1st para, 2nd sentence: Refer to singular filter in >> the definition: "A filter can be thought of as a function which takes a >> message as input and returns a boolean value:" >> >> Part 3, section 5.1, 1st para, 2nd sentence: "filter" should not be >> italicized. >> Also, add comma after "e.g." >> >> Part 3, section 5.2: Refers to "Source" capitalized, whereas 5, 5.1 did >> not, and neither does 5.3. Suggest not capitalizing it in 5.2. >> >> Part 3, section 5.2, 3rd para, 1st sentence: add comma after "i.e." >> >> Part 3, section 5.2, 3rd para, 2nd sentence: "and thus anyway ineligible >> for transfer" - remove "anyway" >> >> Part 3, section 5.3, 1st para, 2nd sentence: first quote on "minimal" >> should be an open quote. >> >> Part 3, section 5.3, expiry-policy: Should be "See section 5.6." >> >> Part 3, section 5.3, dynamic-node-properties, 4th sentence: should be "See >> section 5.9." >> >> Part 3, section 5.3, filter, 1st sentence: Should be "See section 5.8." >> >> Part 3, section 5.3, default-outcome, last sentence: Add comma after >> "e.g." >> >> Part 3, section 5.3, outcomes, last sentence: Add comma after "e.g." and >> change first quote on "amqp:accepted:list" to an open quote. >> >> Part 3, section 5.4, 1st para, 2nd sentence: first quote on "minimal" >> should be an open quote. >> >> Part 3, section 5.4, durable: "or not state at all." should be "or no >> state at all." >> >> Part 3, section 5.4, expiry-policy: Should be "See section 5.6." >> >> Part 3, section 5.4, dynamic-node-properties, 4th sentence: should be "See >> section 5.9." >> >> Part 3, section 5.5, 2nd sentence: Remove " value" from the end. >> >> Part 3, section 5.8, 1st para, 2nd sentence: "ether" should be "either". >> >> Part 3, section 5.8, 1st para, 5th sentence: Add comma after "i.e." >> >> Part 3, section 5.9, 1st sentence: remove hyphen between "Node" and >> "used". >> >> Part 3, section 5.9, supported-dist-modes, 2nd para, 2nd sentence: Add >> comma after "That is". Remove "as" after "defined" >> >> Part 4, section 1, 2nd para, 2nd sentence; 3rd para, 1st and 2nd >> sentences; section 2, 1st para, 2nd sentence; section 2, 4th para, 3rd >> sentence; section 3, 2nd para, 3rd sentence: "transaction resource" and >> "transaction controller" should not be italicized (only at their first >> mention). >> >> Part 4, section 1, 3rd para, 2nd, 3rd, 5th sentences: "control link" >> should not be capitalized (only at first mention). >> >> Part 4, section 2: why is "coordinator" bold courier font? The first use >> in 1st para should be italicized; other uses should be normal body font. >> >> Part 4, section 2, 2nd para, 4th sentence: Should "outcome of the declare >> at the receiver." be "outcome of the declare from the receiver."? >> >> Part 4, section 2, 2nd para, last sentence: Is there a prescribed error >> for this condition? >> >> Part 4, section 4, 1st sentence: "Part 3: 3.1 Message States" should be >> "Part 3, section 3.1" >> >> Part 4, section 4, all 3 bullets in 1st para: Add comma after "i.e." >> >> Part 4, section 4, 3rd para, 2nd sentence: "Part 3: section 4 Delivery >> State of the messaging specification" - remove "Delivery State of the >> messaging specification" >> >> Part 4, section 4, 4th para, 1st sentence: Add comma after "i.e." >> Also, remove "both" >> >> Part 4, section 4.1, 2nd para: Remove parens from around "successfully" >> >> Part 4, section 4.1, 3rd para, 2nd sentence: Add comma after "That is" >> >> Part 4, section 4.2, 1st para, 3rd sentence: change "non discharged" to >> "non-discharged" and do not italicize. >> >> Part 4, section 4.2, 3rd para, 2nd sentence: Change "controller initiated" >> to "controller-initiated" and "resource initiated" to >> "resource-initiated". >> Also, change hyphen between "controller" and "i.e." to an em-dash and add >> a comma after "i.e.". >> >> Part 4, section 4.3: all the italicized words should not be. >> >> Part 4, section 4.3, 4th para, 1st sentence: add a comma after "i.e." and >> a comma after the closing paren. >> >> Part 4, section 4.3, 4th para, 2nd sentence: "complete the sending" should >> be "complete sending" ? >> >> Part 4, section 4.4, 2nd sentence: transpose "therefore" and "can" >> >> Part 4, section 4.4.2, 1st sentence: Change "Here we consider" to "This >> section considers" >> >> Part 4, section 4.4.2, 2nd sentence: Change "see Transactional >> Acquisition" to "see section 4.4.3" >> >> Part 4, section 5.1, capabilities, last sentence: Should be "See section >> 5.7." >> >> Part 4, section 5.2, global-id, 1st sentence: "MUST be associated work >> with" should be "MUST be associated with". >> 2nd sentence: "txn-id will associated work with" should be "txn-id will be >> associated with" >> 3rd sentence: Coordinator should not be capitalized. >> >> Part 5, section 1: "tunneled" should be "carried", or "over" should be >> "through" (one carries over and tunnels through). "carried over" is the >> more correct one here, in my opinion, as tunneling implies a change in >> protocol (tunnel ipv6 through ipv4, for example). >> >> Part 5, section 1, 2nd para, 3rd sentence: Should be "Therefore, section 3 >> defines the frames necessary for SASL to function." >> >> Part 5, section 1, 2nd para, last sentence: "Connection" should not be >> capitalized. >> >> Part 5, section 2, 1st sentence: "tunnel" should be "session". Also, add >> "before commencing with TLS negotiation" at end of sentence. >> >> Part 5, section 2, 2nd sentence: initial quote on "AMQP" should be an open >> quote. >> >> Part 5, section 2, 2nd para: Replace "TLS tunnel" with "TLS protocol" >> Also, remove "Version Negotiation" from reference to section 2. >> >> Part 5, section 2, 4th para, 2nd bullet, 2nd sentence: "differs to" should >> be "differs from" >> >> Part 5, section 2, 4th para, 4th bullet: Add comma after "i.e." >> Also, "write-half" should be "write half" >> >> Part 5, section 2.1, 1st sentence: "using tunnelling" should be "using the >> above procedure" >> >> Part 5, section 2.1, 2nd para, 1st sentence: "tunnel negotiation" should >> be "initial TLS-invoking" >> >> Part 5, section 2.1, 2nd para, 2nd sentence: Add comma after "e.g." >> >> Part 5, section 3, 1st sentence: "tunnel" should be "layer" >> >> Part 5, section 3, 2nd sentence: initial quote on "AMQP" should be an open >> quote. >> >> Part 5, section 3, 2nd para: "tunnel" should be "layer". Also, remove >> "Version Negotiation" from the section 2 reference. >> >> Part 5, section 3.1, 1st sentence: Remove "Framing" from section 3 >> reference. >> >> Part 5, section 3.1, 2nd para, 3rd sentence: initial quote on "sasl-frame" >> should be an open quote. >> Also, remove extra space before period. >> >> Part 5, section 3.2, 1st para: "Server" should not be capitalized. >> Also, 2nd para: "Client" should not be capitalized. >> >> Part 5, section 3.3.1, 1st sentence; sasl-server-mechanisms description; >> section 3.2.2, 1st and 2nd sentences; section 3.3.5, 1st sentence; section >> 3.3.5, code description; section 3.3.6, 1st sentence: "sasl" should be >> capitalized (SASL). >> >> Part 5, section 3.3.2, mechanism, 2nd sentence: "Connection" should not be >> capitalized. >> >> Part 5, section 3.3.2, hostname, 2nd para, 1st sentence: insert "either" >> after "field SHOULD" >> >> >> >> Questionable: >> >> Part 2, section 6.7 and section 7.4, delivery-count: It would be helpful >> to explicitly state what is included in this count. >> >> Part 2, section 7.3, para after XML, 2nd sentence: mentions "The opening >> flag" but there is no opening flag described. >> >> Part 2, section 7.3, snd-settle-mode, rcv-settle-mode: What is the effect >> of a Sender/Receiver not honoring the requested mode? Since there's only >> one attach sent in each direction, what's the intended use of this? Only >> one side can learn the other's preference before sending its own attach. >> >> Part 2, section 7.3, incomplete-unsettled: How does the incomplete map >> become completed? Otherwise no messages can be sent. >> >> Part 2, section 7.5, delivery-id: How would one know if a message with >> delivery-id(2) is a mis-id'd continuation of delivery-id(1) or a new >> message? By using the delivery-tag as well (if it's missing, it must be a >> continuation)? >> >> Part 2, section 7.5, settled: What is the desired/required behavior if the >> values in different transfers of a multi-transfer message are different? >> >> Part 2, section 7.5, state: It's unclear what values the state may have >> and what makes a state terminal. Refer to part 3 section 4. >> >> Part 3, section 2.10: Refers to allowed symbolic keys as starting with >> both "x=" and "x-opt-" - which is right? >> Also, quoted terms use close quotes at start and end; change the start to >> open quotes (`` in latex, I believe) >> >> Part 3, section 4.1: It's not clear how the boundaries between sections >> are established. How does a sender mark sections, or a receiver know where >> the boundaries are? >> >> Part 3, section 4.3, error field: "will be placed" should be "MUST BE >> placed" ? >> >> Part 4, section 4.1, 2nd para: can a message only be available _after_ the >> transaction has been discharged? Is the definition of "discharged" such >> that the message is already made available? >> >> >> --------------------------------------------------------------------- >> To unsubscribe, e-mail: amqp-unsubscribe@lists.oasis-open.org >> For additional commands, e-mail: amqp-help@lists.oasis-open.org >> > > > IIT Software GmbH > Fahrenheitstr. 1, D28359 Bremen, Germany > Tel: +49 421 2208-166, Fax: +49 421 2208-167 > Amtsgericht Bremen, HRB 18624, Geschaeftsfuehrer: Andreas Mueller > Steuernummer: 71/572/04100, VAT: DE199945912 > > > --------------------------------------------------------------------- > To unsubscribe, e-mail: amqp-unsubscribe@lists.oasis-open.org > For additional commands, e-mail: amqp-help@lists.oasis-open.org >
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]