[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: [OASIS Issue Tracker] (MQTT-421) WD11 Review comments by Stefan (restored from MQTT-417)
[ https://issues.oasis-open.org/browse/MQTT-421?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Stefan Hagen updated MQTT-421:
------------------------------
Description:
Not ready yet (current reading position before line 2769).
Nits/Suggestions:
# ---
1) Better separate MQTT specific tokens from the associated "english language" terms
As already noted once in a comment inside the editors word document: I suggest to format the controlled vocabulary when the MQTT specific type/instance is meant with a specific format (say fixed width serif font) - there should be e.g. Datatype already in the OASIS boilerplate.
This eases parsing by the reader (like the MUST versus must of RFC2119 controlled vocabulary).
Sample "Session Expiry Interval" (also in headers!) looks ok in header, but due to the title casing wrong inside the "textual" prose and also steals away our possible "normal english" usage of such a term.
2) Avoid ambiguity in document navigation of fiels being members of more than one packet "type"
To offer better referencing through the first "outer scope" section level header, prefix the field section heads by there containing packet type separated e.g by a not too short dash "--" (neither "-" nor "---")
3) Do not repeat yourself - and annoy the reader by formulesque "sed 's/foo/bar/g; s/baz/zab/g;'" like template explosion
Refactor all these many(!) local "do not add to packet if would increase packet size > packet size maximum ..." MUST NOT stuff into a single clear such statement attached to the according maximum size description, and instead refer to as with other network connection ending rules etc. via "as described in section REF_HERE" or the like.
Similar for the ever recurring "Bits 3,2,1 and 0 of the WHATEVER packet are reserved and MUST be set to 0,0,0 and 1 respectively."!
Note, that this also "repairs a nit" the variations where "0, 0, 0" whith spaces and commas as compared to "0,0,0" are used.
# ---
@Abstract lines 26-29:
These characteristics make it ideal for use in many situations, including constrained environments such as for communication in Machine to Machine (M2M) and Internet of Things (IoT) contexts where a small code footprint is required and/or network bandwidth is at a premium.
# - >
Suggest to allow or to contain the and case, put examples at the end of the argument and order the former alphabetically, and pull shared term context before the list:
These characteristics make it ideal for use in many situations, including constrained environments where a small code footprint is required or network bandwidth is at a premium, e.g. for communication in the context of Internet of Things (IoT) or Machine to Machine (M2M).
# < -
# ---
@Abstract lines 30-45:
The protocol runs over TCP/IP, or over other network protocols that provide ordered, lossless, bi-directional connections. Its features include:
* Use of the publish/subscribe message pattern which provides one-to-many message distribution and decoupling of applications.
* A messaging transport that is agnostic to the content of the payload.
* Three qualities of service for message delivery:
+ "At most once", where messages are delivered according to the best efforts of the operating environment. Message loss can occur. This level could be used, for example, with ambient sensor data where it does not matter if an individual reading is lost as the next one will be published soon after.
+ "At least once", where messages are assured to arrive but duplicates can occur.
+ "Exactly once", where messages are assured to arrive exactly once. This level could be used, for example, with billing systems where duplicate or lost messages could lead to incorrect charges being applied.
* A small transport overhead and protocol exchanges minimized to reduce network traffic.
* A mechanism to notify interested parties when an abnormal disconnection occurs.
# - >
Suggest to pull the requirements left with MQTT instead of The protocol and state TCP/IP as sample at end; and features include reads weaker than provides (or the like without exclusively this allows for skipped capabilities) allowing for edited list items reading more clear IMO; also trimmed down the sub-sub items which explained a lot more, than - I think - is expected / useful in an abstract - YMMV (maybe the "At least once" might deserve a catchy example also?):
MQTT requires a stack of network protocols that provide ordered, lossless, bi-directional connections like e.g. TCP/IP provides. It provides:
* Publish/subscribe message pattern for one-to-many message distribution and decoupling of applications.
* Messaging transport agnostic of the payload content.
* Message delivery offering three distinct qualities of service:
+ "At most once", where messages are delivered according to the best efforts of the operating environment and thus messages may get lost, for example, with ambient sensor data.
+ "At least once", where messages are assured to arrive but duplicates can occur.
+ "Exactly once", where messages are assured to arrive exactly once, for example, with billing systems.
* Reduced network traffic through small transport overhead and minimized protocol exchanges.
* Mechanism to notify interested parties when an abnormal disconnection occurs.
# < -
# ---
@"1.3 Normative references" lines 425-447:
@"1.4 Non-Normative references" lines 450-560:
Suggested to avoid linebreaks inside statements like "DOI 10.17487/RFC2119", "December 2011", "RFC 1928", and the like
# ---
@"1.5.4 UTF-8 Encoded String" line 607:
As a normative quite convoluted sentence( start) reads a bit indirect:
A UTF-8 encoded sequence 0xEF 0xBB 0xBF is always to be interpreted to mean U+FEFF ("ZERO
# - >
Suggested rewording:
The UTF-8 encoded sequence 0xEF 0xBB 0xBF is always interpreted as U+FEFF ("ZERO
# < -
# ---
@"1.5.6 Binary Data" full sentence at line 663/664:
Note: The below "Where used" sounds more unclear, than the previous a "Binary Data is represented by" statement.
[Bytes. ] Where used the data consists only of the data portion of the field, which can take any value and
does not include first two length bytes.
Maybe better describe the effective length range in bytes of the rpresentation (if necessary at all)
# ---
@"1.7 Editing convention" at lines 680-683
As the yellow highlight to many readers most probably looks like unintented leftovers from draft stages instead the intended and in this section explained rationale, suggested is to move this section before the first such highlighted statement.
# ---
@2.3 Payload line 808 a chapter reference did was not found "Error! Reference source not found."
# ---
@3.1.2.1 Protocol Name and 3.1.2.2 Protocol Version
Comparing the MAY part of the paragraphs starting lines 846 and 859 resp.
I would just like to get affirmation, that indeed we suggest a server returns
0x84 (Unsupported Protocol Version) also in the "Protocol Name dislike case"
and that this is no copy-paste-missed-specialization nit.
# ---
@3.1.2.10 Keep Alive, line 974
Has:
maximum value is 18 hours 12 minutes and 15 seconds.
Suggested (to motivate the very special numbers) reads clunky, but then I am a German, so maybe the English can cook it more to the point:
maximum value is 18 hours 12 minutes and 15 seconds (65535 is the maximal value a Two Byte Integer can hold).
If that was meant as a motivating riddle, please keep it :))
# ---
@3.1.2.16 Topic Alias Maximum lines 1139-1141:
Now:
The Server MUST NOT send a Topic Alias in a PUBLISH packet to the Client greater than Topic Alias Maximum [MQTT-3.1.2-30].
Should (in my understanding, Topic Alias Maximum is a number for a count, and one counts topic aliases, before sending the allowed amount, then
also the question would be if there could be topic alias sendings spanning multiple PUBLISH packets, but then what do I know, maybe
some MQTT practitioner knowledge is lacking here in my mind, please forgive me as theoretical newbie, thanks):
The Server MUST NOT send more Topic Aliases than Topic Alias Maximum in a PUBLISH packet to the Client [MQTT-3.1.2-30].
# ---
@3.1.2.18 Request Problem Information lines 1168-1170 in [MQTT-3.1.2-33]:
Suggest to list the MUST NOT (strong) requirement first, and the MAY (alert variation ahead) part second.
# ---
@3.1.3 Payload esp. [MQTT-3.1.3-1] giving an order requirement in lines 1205 an 1206
COMPARE to all
@3.1.3.1 Client Identifier (ClientID) esp. line 1212 [MQTT-3.1.3-3]
and
@3.1.3.2 Will Topic esp. line 1239 [MQTT-3.1.3-9]
and
@3.1.3.4 User Name esp. line 1246 [MQTT-3.1.3-10]
a) Suggest to **not** have overlap in requirements, thus to keep the ordering requirement of the "children" exclusively inside [MQTT-3.1.3-1] and
b) The "early" ending of yellow background (maybe due to active cross reference or link text) i.e. not stretching upto the Requirement marker token is irritating (to the reporter).
# ---
@3.1.4 Response line 1254 and any other occurence of "MQTTv5.0" in our work product (besides the title and maybe some conformance section stuff):
I remember there was heated discussion when re-convening the MQTT TC about the "un-float-ness" of the version identity being an integer 5 instead of the 5.0 enforced in title etc. by OASIS rules for formal document management.
Suggest to change occurences like the one in line 1254 of "MQTTv5.0" instead to either a) "MQTT version 5" or even b) "MQTT version of this specification"
This does in no way bend OASIS rule and in the same vain emphasizes the fact, that any next MQTT version will not be "5.x with x != 0" but instead 6 or 7 or what not. The (b) variant the reporter would prefer (as reader) when not a specific version number comparison is targeted in the statement but more a somehow indirect version number relationship is the target, and (a) when say a version number field or a specific UTF-8 string with the value like for the "Protocol Version" field.
If we want to play nice with everyone, we could note early on in the document, that "in this specification the statement "MQTT version 5" is equivalent with stating both "MQTTv5.0" or "MQTT version 5.0".
# ---
@3.1.4 Response line 1277 suggest to rethink the placement of the requirement token, as without the yellow background (formats may not offer it, accessibility issues may render it invisible) it is unclear, where the mandatory statement ends. Proposed is to insert the square bracket insulated req token into the sentence right after the last mandatory "word" instead of after the final punctuation mark of the "mixed mode" sentence.
# ---
@3.2.2.5 Receive Maximum line 1413 simple typo replace "that" with "than". Also - being a German native this may only be unclear to me - why do we vary may and might in the non-normative comment sections (and maybe we should just concat adjacent such "section" with a plural indicating header like "Non-Normative comments")?
# ---
@3.2.2.6 Maximum QoS lines 1428-1445 suggest reordering of requirements to group per targeted "role" (server or client) and tag the requirement(s)
currently at lines 1442-1445 (token is not present). By grouping the requirements per role, one could also better separate those (inside the group with a shift-ENTER kind of line break (instead of new paragraph ENTER))
# ---
@3.2.2.10 Topic Alias Maximum line 1499
Maybe the reporter really misunderstood the nature of topics and a TOPIC ALIAS MAXIMUM, but if the understanding (that a topic is not a counter itself) is correct, here is another requirement awaiting rewording;-)
# ---
@3.3.1.3 RETAIN lines 1657-1678 are maybe not as clear as they could (eg. result looks identical and question rises, what if RETAIN == 1 and subscription did already exist?)
# ---
@3.3.2.1 Topic Name line 1724 "in section Error! Reference source not found.. It is a Protocol Error if the Topic Name is zero length"
Suggest to find the "reference source".
# ---
@3.3.2.4 Payload Format Indicator lines 1736-1738
Reporter thinks "Note that the UTF-8 Data in the Payload does not include a length prefix, nor is it subject to the restrictions described in section 1.5.3."
is irritating due to being a "note" in normative text, and the content being "does not include" + "nor restricted by something elsewhere".
Question: Could we add a more simply helpful detail info here?
# ---
@3.3.2.6 Topic Alias line 1766 simple typo replace "seta" with "sets" in "It seta a Topic Alias mapping"
# ---
@3.4.2.1 PUBACK Return Code has req token tagged statement inside a table's right most column (with head Description), suggested is to better reference only in that table cell and instead push out the mandatory statement with its tag inot the main prose ("left margin anchored") so it will not be overlooked.
# ---
@3.5.2.1 PUBREC Return Code similar to "@3.4.2.1 PUBACK Return Code has req token tagged statement inside a table's right most column ..." with dito proposed change.
# ---
@3.8.3 Payload line 2218 reference to "section 0" looks fishy, please check the real section target in the cross-reference.
# ---
@3.8.3.1 Subscription Options lines 2225 and 2230 read like they would profit from replacing "represent" with "represents" as a single bit is a singular entity (sorry, if my language feeling is incorrect here)
# ---
@3.8.4 Response line 2303 there is a "might" bracketed by quite some RFC2119 MUST occurences in neighbouring sentences, please consider using RFC2119 MAY or reword slightly to not leave the reader throwing a coin on which kind of may/MAY we might have meant.
# ---
@3.8.4 Response line 2311/2 consider using a non-breaking space between any "TYPE" "VALUE" prose statements to avoid reading flow interrupting line breaks like here between the type "QoS" and its value "0" here.
# ---
@3.8.4 Response line 2317 has no separate Non-Normative comment header associated and like already suggested at "@3.2.2.5 Receive Maximum line 1413" maybe best concat all adjacent non-normative comment blocks and prefix them with a plural version of that special header
# ---
@3.8.4 Response line 2328 "The Subscription Identifiers are part of the session state in the server and return to the client receiving a"
does read like these IDs would be more active, than they are, suggested rewrite into passive, i.e. "The Subscription Identifiers are part of the session state in the server and are returned to the client receiving a"
# ---
@3.8.4 Response line 2339/40 "The server is not obliged to use the same set of Subscription Identifiers in are transmitted PUBLISH packet." reads unclear to the reporter, please specify if "in are" should be "that are" or "in a" or ...
# ---
@3.8.4 Response line 2340 "If the client remade a subscription [...]" - as it is normative text, reads unclear (the verb!) how to remake is the question. Should we reformulate or should the reporter be educated instead; please advise.
# ---
@3.8.4 Response line 2343/4 the line breaks the sentence between "has" and "sent" rather surprisingly considering the left line space estate
# ---
@3.8.4 Response line 2347 "Usage scenarios, for illustration if Subscription Identifiers." (reads a tad incomplete)
# ---
@3.9.2.3 User Property lines 2407/8 and all other requirements of this kind "spread all over" should be refactored to wher we define the "Maximum Packet Size" and instead of copy-pasting (mostly the generic master rule) only refer in a requirement like so:
"It is a Protocol Error to include this property if it would increase the packet size beyond the one set as described in {[MQTT-x.y.z-n]- or section-ref}"
instead of the present:
"The sender MUST NOT send this property if it would increase the size of the SUBACK beyond the Maximum Packet Size specified by the session partner"
# ---
@3.10.3 Payload line 2452 reads "[MQTT-3.10.3-1] as defined in section Error! Reference source not found., packed contiguously." and if the reference were to be found would read better.
# ---
@3.10.3 Payload line 2454 again a suspicious "section 0" reference, please correct.
# ---
@3.11.2 Variable Header line 2496 replace "The Variable Header of the UNSUBACK Packet the following fields in the order:" with "The Variable Header of the UNSUBACK Packet contains the following fields in the order:" (missing verb)
# ---
@3.12 PINGREQ – PING request line 2537 another suspicious reference to "section 0" - please note the intended section instead.
# ---
@3.13 PINGRESP – PING response line 2555 yet another suspicious reference to "section 0" - please note the intended section instead.
# ---
@3.14.1 Fixed Header line 2581 suggested to replace "The server or client" with "The receiver" as only that role can act upon the received value and the statement then reads clearer (an initial "or" makes the single line of reasoning a two lane problem ...)
# ---
@3.14.2.1 Disconnect Return Code line 2602 "dito, only the other end of the channel" - suggested to replace "The Client or Server sending" with "The sender of".
# ---
@3.15.2 Variable Header lines 2692/3 as with the "TYPE"non-breaking-space"VALUE" instance above, only for "section"non-breaking-space{CROSS_REFERENCE}
Also check globally ...
# ---
@4.1.1 Non-Normative example lines 2761-2768 reads irritating (after all these "Non-normative comment" indented unnumbered section heads) suggested is to use a caption like format element and ad global numbering to it like so: "Example {THE_COUNTER}: specific text of caption" and then have the example inside a special block element if it is code like, or as here more similar to the Non-normative comment "text block" structure.
# ---
Component and JIRA's severity field "priority (shiver)" set in the hopes it will be only editorial and trivial to fix whatever I will find.
To cite Richard's announcement of WD11 ready to review:
The editors have requested that each TC member open one Jira containing their feedback comments. The editors can then process anything editorial, remove duplicates, and bring more substantial issues to the attention of the TC.
was:
Not ready yet (current reading position before line 2484).
Nits/Suggestions:
@Abstract lines 26-29:
These characteristics make it ideal for use in many situations, including constrained environments such as for communication in Machine to Machine (M2M) and Internet of Things (IoT) contexts where a small code footprint is required and/or network bandwidth is at a premium.
# - >
Suggest to allow or to contain the and case, put examples at the end of the argument and order the former alphabetically, and pull shared term context before the list:
These characteristics make it ideal for use in many situations, including constrained environments where a small code footprint is required or network bandwidth is at a premium, e.g. for communication in the context of Internet of Things (IoT) or Machine to Machine (M2M).
# < -
# ---
@Abstract lines 30-45:
The protocol runs over TCP/IP, or over other network protocols that provide ordered, lossless, bi-directional connections. Its features include:
* Use of the publish/subscribe message pattern which provides one-to-many message distribution and decoupling of applications.
* A messaging transport that is agnostic to the content of the payload.
* Three qualities of service for message delivery:
+ "At most once", where messages are delivered according to the best efforts of the operating environment. Message loss can occur. This level could be used, for example, with ambient sensor data where it does not matter if an individual reading is lost as the next one will be published soon after.
+ "At least once", where messages are assured to arrive but duplicates can occur.
+ "Exactly once", where messages are assured to arrive exactly once. This level could be used, for example, with billing systems where duplicate or lost messages could lead to incorrect charges being applied.
* A small transport overhead and protocol exchanges minimized to reduce network traffic.
* A mechanism to notify interested parties when an abnormal disconnection occurs.
# - >
Suggest to pull the requirements left with MQTT instead of The protocol and state TCP/IP as sample at end; and features include reads weaker than provides (or the like without exclusively this allows for skipped capabilities) allowing for edited list items reading more clear IMO; also trimmed down the sub-sub items which explained a lot more, than - I think - is expected / useful in an abstract - YMMV (maybe the "At least once" might deserve a catchy example also?):
MQTT requires a stack of network protocols that provide ordered, lossless, bi-directional connections like e.g. TCP/IP provides. It provides:
* Publish/subscribe message pattern for one-to-many message distribution and decoupling of applications.
* Messaging transport agnostic of the payload content.
* Message delivery offering three distinct qualities of service:
+ "At most once", where messages are delivered according to the best efforts of the operating environment and thus messages may get lost, for example, with ambient sensor data.
+ "At least once", where messages are assured to arrive but duplicates can occur.
+ "Exactly once", where messages are assured to arrive exactly once, for example, with billing systems.
* Reduced network traffic through small transport overhead and minimized protocol exchanges.
* Mechanism to notify interested parties when an abnormal disconnection occurs.
# < -
# ---
@"1.3 Normative references" lines 425-447:
@"1.4 Non-Normative references" lines 450-560:
Suggested to avoid linebreaks inside statements like "DOI 10.17487/RFC2119", "December 2011", "RFC 1928", and the like
# ---
@"1.5.4 UTF-8 Encoded String" line 607:
As a normative quite convoluted sentence( start) reads a bit indirect:
A UTF-8 encoded sequence 0xEF 0xBB 0xBF is always to be interpreted to mean U+FEFF ("ZERO
# - >
Suggested rewording:
The UTF-8 encoded sequence 0xEF 0xBB 0xBF is always interpreted as U+FEFF ("ZERO
# < -
# ---
@"1.5.6 Binary Data" full sentence at line 663/664:
Note: The below "Where used" sounds more unclear, than the previous a "Binary Data is represented by" statement.
[Bytes. ] Where used the data consists only of the data portion of the field, which can take any value and
does not include first two length bytes.
Maybe better describe the effective length range in bytes of the rpresentation (if necessary at all)
# ---
@"1.7 Editing convention" at lines 680-683
As the yellow highlight to many readers most probably looks like unintented leftovers from draft stages instead the intended and in this section explained rationale, suggested is to move this section before the first such highlighted statement.
# ---
@2.3 Payload line 808 a chapter reference did was not found "Error! Reference source not found."
# ---
@3.1.2.1 Protocol Name and 3.1.2.2 Protocol Version
Comparing the MAY part of the paragraphs starting lines 846 and 859 resp.
I would just like to get affirmation, that indeed we suggest a server returns
0x84 (Unsupported Protocol Version) also in the "Protocol Name dislike case"
and that this is no copy-paste-missed-specialization nit.
# ---
@3.1.2.10 Keep Alive, line 974
Has:
maximum value is 18 hours 12 minutes and 15 seconds.
Suggested (to motivate the very special numbers) reads clunky, but then I am a German, so maybe the English can cook it more to the point:
maximum value is 18 hours 12 minutes and 15 seconds (65535 is the maximal value a Two Byte Integer can hold).
If that was meant as a motivating riddle, please keep it :))
# ---
@3.1.2.16 Topic Alias Maximum lines 1139-1141:
Now:
The Server MUST NOT send a Topic Alias in a PUBLISH packet to the Client greater than Topic Alias Maximum [MQTT-3.1.2-30].
Should (in my understanding, Topic Alias Maximum is a number for a count, and one counts topic aliases, before sending the allowed amount, then
also the question would be if there could be topic alias sendings spanning multiple PUBLISH packets, but then what do I know, maybe
some MQTT practitioner knowledge is lacking here in my mind, please forgive me as theoretical newbie, thanks):
The Server MUST NOT send more Topic Aliases than Topic Alias Maximum in a PUBLISH packet to the Client [MQTT-3.1.2-30].
# ---
@3.1.2.18 Request Problem Information lines 1168-1170 in [MQTT-3.1.2-33]:
Suggest to list the MUST NOT (strong) requirement first, and the MAY (alert variation ahead) part second.
# ---
@3.1.2.18 Request Problem Information lines 1168-1170 in [MQTT-3.1.2-33]:
Suggest to list the MUST NOT (strong) requirement first, and the MAY (alert variation ahead) part second.
# ---
@3.1.3 Payload esp. [MQTT-3.1.3-1] giving an order requirement in lines 1205 an 1206
COMPARE to all
@3.1.3.1 Client Identifier (ClientID) esp. line 1212 [MQTT-3.1.3-3]
and
@3.1.3.2 Will Topic esp. line 1239 [MQTT-3.1.3-9]
and
@3.1.3.4 User Name esp. line 1246 [MQTT-3.1.3-10]
a) Suggest to **not** have overlap in requirements, thus to keep the ordering requirement of the "children" exclusively inside [MQTT-3.1.3-1] and
b) The "early" ending of yellow background (maybe due to active cross reference or link text) i.e. not stretching upto the Requirement marker token is irritating (to the reporter).
# ---
@3.1.4 Response line 1254 and any other occurence of "MQTTv5.0" in our work product (besides the title and maybe some conformance section stuff):
I remember there was heated discussion when re-convening the MQTT TC about the "un-float-ness" of the version identity being an integer 5 instead of the 5.0 enforced in title etc. by OASIS rules for formal document management.
Suggest to change occurences like the one in line 1254 of "MQTTv5.0" instead to either a) "MQTT version 5" or even b) "MQTT version of this specification"
This does in no way bend OASIS rule and in the same vain emphasizes the fact, that any next MQTT version will not be "5.x with x != 0" but instead 6 or 7 or what not. The (b) variant the reporter would prefer (as reader) when not a specific version number comparison is targeted in the statement but more a somehow indirect version number relationship is the target, and (a) when say a version number field or a specific UTF-8 string with the value like for the "Protocol Version" field.
If we want to play nice with everyone, we could note early on in the document, that "in this specification the statement "MQTT version 5" is equivalent with stating both "MQTTv5.0" or "MQTT version 5.0".
# ---
@3.1.4 Response line 1277 suggest to rethink the placement of the requirement token, as without the yellow background (formats may not offer it, accessibility issues may render it invisible) it is unclear, where the mandatory statement ends. Proposed is to insert the square bracket insulated req token into the sentence right after the last mandatory "word" instead of after the final punctuation mark of the "mixed mode" sentence.
# ---
@3.2.2.5 Receive Maximum line 1413 simple typo replace "that" with "than". Also - being a German native this may only be unclear to me - why do we vary may and might in the non-normative comment sections (and maybe we should just concat adjacent such "section" with a plural indicating header like "Non-Normative comments")?
# ---
@3.2.2.6 Maximum QoS lines 1428-1445 suggest reordering of requirements to group per targeted "role" (server or client) and tag the requirement(s)
currently at lines 1442-1445 (token is not present). By grouping the requirements per role, one could also better separate those (inside the group with a shift-ENTER kind of line break (instead of new paragraph ENTER))
# ---
@3.2.2.10 Topic Alias Maximum line 1499
Maybe the reporter really misunderstood the nature of topics and a TOPIC ALIAS MAXIMUM, but if the understanding (that a topic is not a counter itself) is correct, here is another requirement awaiting rewording;-)
# ---
@3.3.1.3 RETAIN lines 1657-1678 are maybe not as clear as they could (eg. result looks identical and question rises, what if RETAIN == 1 and subscription did already exist?)
# ---
@3.3.2.1 Topic Name line 1724 "in section Error! Reference source not found.. It is a Protocol Error if the Topic Name is zero length"
Suggest to find the "reference source".
# ---
@3.3.2.4 Payload Format Indicator lines 1736-1738
Reporter thinks "Note that the UTF-8 Data in the Payload does not include a length prefix, nor is it subject to the restrictions described in section 1.5.3."
is irritating due to being a "note" in normative text, and the content being "does not include" + "nor restricted by something elsewhere".
Question: Could we add a more simply helpful detail info here?
# ---
@3.3.2.6 Topic Alias line 1766 simple typo replace "seta" with "sets" in "It seta a Topic Alias mapping"
# ---
@3.4.2.1 PUBACK Return Code has req token tagged statement inside a table's right most column (with head Description), suggested is to better reference only in that table cell and instead push out the mandatory statement with its tag inot the main prose ("left margin anchored") so it will not be overlooked.
# ---
@3.5.2.1 PUBREC Return Code similar to "@3.4.2.1 PUBACK Return Code has req token tagged statement inside a table's right most column ..." with dito proposed change.
# ---
@3.8.3 Payload line 2218 reference to "section 0" looks fishy, please check the real section target in the cross-reference.
# ---
@3.8.3.1 Subscription Options lines 2225 and 2230 read like they would profit from replacing "represent" with "represents" as a single bit is a singular entity (sorry, if my language feeling is incorrect here)
# ---
@3.8.4 Response line 2303 there is a "might" bracketed by quite some RFC2119 MUST occurences in neighbouring sentences, please consider using RFC2119 MAY or reword slightly to not leave the reader throwing a coin on which kind of may/MAY we might have meant.
# ---
@3.8.4 Response line 2311/2 consider using a non-breaking space between any "TYPE" "VALUE" prose statements to avoid reading flow interrupting line breaks like here between the type "QoS" and its value "0" here.
# ---
@3.8.4 Response line 2317 has no separate Non-Normative comment header associated and like already suggested at "@3.2.2.5 Receive Maximum line 1413" maybe best concat all adjacent non-normative comment blocks and prefix them with a plural version of that special header
# ---
@3.8.4 Response line 2328 "The Subscription Identifiers are part of the session state in the server and return to the client receiving a"
does read like these IDs would be more active, than they are, suggested rewrite into passive, i.e. "The Subscription Identifiers are part of the session state in the server and are returned to the client receiving a"
# ---
@3.8.4 Response line 2339/40 "The server is not obliged to use the same set of Subscription Identifiers in are transmitted PUBLISH packet." reads unclear to the reporter, please specify if "in are" should be "that are" or "in a" or ...
# ---
@3.8.4 Response line 2340 "If the client remade a subscription [...]" - as it is normative text, reads unclear (the verb!) how to remake is the question. Should we reformulate or should the reporter be educated instead; please advise.
# ---
@3.8.4 Response line 2343/4 the line breaks the sentence between "has" and "sent" rather surprisingly considering the left line space estate
# ---
@3.9.2.3 User Property lines 2407/8 and all other requirements of this kind "spread all over" should be refactored to wher we define the "Maximum Packet Size" and instead of copy-pasting (mostly the generic master rule) only refer in a requirement like so:
"It is a Protocol Error to include this property if it would increase the packet size beyond the one set as described in {[MQTT-x.y.z-n]- or section-ref}"
instead of the present:
"The sender MUST NOT send this property if it would increase the size of the SUBACK beyond the Maximum Packet Size specified by the session partner"
# ---
@3.10.3 Payload line 2452 reads "[MQTT-3.10.3-1] as defined in section Error! Reference source not found., packed contiguously." and if the reference were to be found would read better.
# ---
@3.10.3 Payload line 2454 again a suspicious "section 0" reference, please correct.
# ---
Component and JIRA's severity field "priority (shiver)" set in the hopes it will be only editorial and trivial to fix whatever I will find.
To cite Richard's announcement of WD11 ready to review:
The editors have requested that each TC member open one Jira containing their feedback comments. The editors can then process anything editorial, remove duplicates, and bring more substantial issues to the attention of the TC.
> WD11 Review comments by Stefan (restored from MQTT-417)
> -------------------------------------------------------
>
> Key: MQTT-421
> URL: https://issues.oasis-open.org/browse/MQTT-421
> Project: OASIS Message Queuing Telemetry Transport (MQTT) TC
> Issue Type: Bug
> Components: edits
> Affects Versions: 5, wd11
> Reporter: Stefan Hagen
> Priority: Trivial
> Labels: editorial
>
> Not ready yet (current reading position before line 2769).
> Nits/Suggestions:
> # ---
> 1) Better separate MQTT specific tokens from the associated "english language" terms
> As already noted once in a comment inside the editors word document: I suggest to format the controlled vocabulary when the MQTT specific type/instance is meant with a specific format (say fixed width serif font) - there should be e.g. Datatype already in the OASIS boilerplate.
> This eases parsing by the reader (like the MUST versus must of RFC2119 controlled vocabulary).
> Sample "Session Expiry Interval" (also in headers!) looks ok in header, but due to the title casing wrong inside the "textual" prose and also steals away our possible "normal english" usage of such a term.
> 2) Avoid ambiguity in document navigation of fiels being members of more than one packet "type"
> To offer better referencing through the first "outer scope" section level header, prefix the field section heads by there containing packet type separated e.g by a not too short dash "--" (neither "-" nor "---")
> 3) Do not repeat yourself - and annoy the reader by formulesque "sed 's/foo/bar/g; s/baz/zab/g;'" like template explosion
> Refactor all these many(!) local "do not add to packet if would increase packet size > packet size maximum ..." MUST NOT stuff into a single clear such statement attached to the according maximum size description, and instead refer to as with other network connection ending rules etc. via "as described in section REF_HERE" or the like.
> Similar for the ever recurring "Bits 3,2,1 and 0 of the WHATEVER packet are reserved and MUST be set to 0,0,0 and 1 respectively."!
> Note, that this also "repairs a nit" the variations where "0, 0, 0" whith spaces and commas as compared to "0,0,0" are used.
> # ---
> @Abstract lines 26-29:
> These characteristics make it ideal for use in many situations, including constrained environments such as for communication in Machine to Machine (M2M) and Internet of Things (IoT) contexts where a small code footprint is required and/or network bandwidth is at a premium.
> # - >
> Suggest to allow or to contain the and case, put examples at the end of the argument and order the former alphabetically, and pull shared term context before the list:
> These characteristics make it ideal for use in many situations, including constrained environments where a small code footprint is required or network bandwidth is at a premium, e.g. for communication in the context of Internet of Things (IoT) or Machine to Machine (M2M).
> # < -
> # ---
> @Abstract lines 30-45:
> The protocol runs over TCP/IP, or over other network protocols that provide ordered, lossless, bi-directional connections. Its features include:
> * Use of the publish/subscribe message pattern which provides one-to-many message distribution and decoupling of applications.
> * A messaging transport that is agnostic to the content of the payload.
> * Three qualities of service for message delivery:
> + "At most once", where messages are delivered according to the best efforts of the operating environment. Message loss can occur. This level could be used, for example, with ambient sensor data where it does not matter if an individual reading is lost as the next one will be published soon after.
> + "At least once", where messages are assured to arrive but duplicates can occur.
> + "Exactly once", where messages are assured to arrive exactly once. This level could be used, for example, with billing systems where duplicate or lost messages could lead to incorrect charges being applied.
> * A small transport overhead and protocol exchanges minimized to reduce network traffic.
> * A mechanism to notify interested parties when an abnormal disconnection occurs.
> # - >
> Suggest to pull the requirements left with MQTT instead of The protocol and state TCP/IP as sample at end; and features include reads weaker than provides (or the like without exclusively this allows for skipped capabilities) allowing for edited list items reading more clear IMO; also trimmed down the sub-sub items which explained a lot more, than - I think - is expected / useful in an abstract - YMMV (maybe the "At least once" might deserve a catchy example also?):
> MQTT requires a stack of network protocols that provide ordered, lossless, bi-directional connections like e.g. TCP/IP provides. It provides:
> * Publish/subscribe message pattern for one-to-many message distribution and decoupling of applications.
> * Messaging transport agnostic of the payload content.
> * Message delivery offering three distinct qualities of service:
> + "At most once", where messages are delivered according to the best efforts of the operating environment and thus messages may get lost, for example, with ambient sensor data.
> + "At least once", where messages are assured to arrive but duplicates can occur.
> + "Exactly once", where messages are assured to arrive exactly once, for example, with billing systems.
> * Reduced network traffic through small transport overhead and minimized protocol exchanges.
> * Mechanism to notify interested parties when an abnormal disconnection occurs.
> # < -
> # ---
> @"1.3 Normative references" lines 425-447:
> @"1.4 Non-Normative references" lines 450-560:
> Suggested to avoid linebreaks inside statements like "DOI 10.17487/RFC2119", "December 2011", "RFC 1928", and the like
> # ---
> @"1.5.4 UTF-8 Encoded String" line 607:
> As a normative quite convoluted sentence( start) reads a bit indirect:
> A UTF-8 encoded sequence 0xEF 0xBB 0xBF is always to be interpreted to mean U+FEFF ("ZERO
> # - >
> Suggested rewording:
> The UTF-8 encoded sequence 0xEF 0xBB 0xBF is always interpreted as U+FEFF ("ZERO
> # < -
> # ---
> @"1.5.6 Binary Data" full sentence at line 663/664:
> Note: The below "Where used" sounds more unclear, than the previous a "Binary Data is represented by" statement.
> [Bytes. ] Where used the data consists only of the data portion of the field, which can take any value and
> does not include first two length bytes.
> Maybe better describe the effective length range in bytes of the rpresentation (if necessary at all)
> # ---
> @"1.7 Editing convention" at lines 680-683
> As the yellow highlight to many readers most probably looks like unintented leftovers from draft stages instead the intended and in this section explained rationale, suggested is to move this section before the first such highlighted statement.
> # ---
> @2.3 Payload line 808 a chapter reference did was not found "Error! Reference source not found."
> # ---
> @3.1.2.1 Protocol Name and 3.1.2.2 Protocol Version
> Comparing the MAY part of the paragraphs starting lines 846 and 859 resp.
> I would just like to get affirmation, that indeed we suggest a server returns
> 0x84 (Unsupported Protocol Version) also in the "Protocol Name dislike case"
> and that this is no copy-paste-missed-specialization nit.
> # ---
> @3.1.2.10 Keep Alive, line 974
> Has:
> maximum value is 18 hours 12 minutes and 15 seconds.
> Suggested (to motivate the very special numbers) reads clunky, but then I am a German, so maybe the English can cook it more to the point:
> maximum value is 18 hours 12 minutes and 15 seconds (65535 is the maximal value a Two Byte Integer can hold).
> If that was meant as a motivating riddle, please keep it :))
> # ---
> @3.1.2.16 Topic Alias Maximum lines 1139-1141:
> Now:
> The Server MUST NOT send a Topic Alias in a PUBLISH packet to the Client greater than Topic Alias Maximum [MQTT-3.1.2-30].
> Should (in my understanding, Topic Alias Maximum is a number for a count, and one counts topic aliases, before sending the allowed amount, then
> also the question would be if there could be topic alias sendings spanning multiple PUBLISH packets, but then what do I know, maybe
> some MQTT practitioner knowledge is lacking here in my mind, please forgive me as theoretical newbie, thanks):
> The Server MUST NOT send more Topic Aliases than Topic Alias Maximum in a PUBLISH packet to the Client [MQTT-3.1.2-30].
> # ---
> @3.1.2.18 Request Problem Information lines 1168-1170 in [MQTT-3.1.2-33]:
> Suggest to list the MUST NOT (strong) requirement first, and the MAY (alert variation ahead) part second.
> # ---
> @3.1.3 Payload esp. [MQTT-3.1.3-1] giving an order requirement in lines 1205 an 1206
> COMPARE to all
> @3.1.3.1 Client Identifier (ClientID) esp. line 1212 [MQTT-3.1.3-3]
> and
> @3.1.3.2 Will Topic esp. line 1239 [MQTT-3.1.3-9]
> and
> @3.1.3.4 User Name esp. line 1246 [MQTT-3.1.3-10]
> a) Suggest to **not** have overlap in requirements, thus to keep the ordering requirement of the "children" exclusively inside [MQTT-3.1.3-1] and
> b) The "early" ending of yellow background (maybe due to active cross reference or link text) i.e. not stretching upto the Requirement marker token is irritating (to the reporter).
> # ---
> @3.1.4 Response line 1254 and any other occurence of "MQTTv5.0" in our work product (besides the title and maybe some conformance section stuff):
> I remember there was heated discussion when re-convening the MQTT TC about the "un-float-ness" of the version identity being an integer 5 instead of the 5.0 enforced in title etc. by OASIS rules for formal document management.
> Suggest to change occurences like the one in line 1254 of "MQTTv5.0" instead to either a) "MQTT version 5" or even b) "MQTT version of this specification"
> This does in no way bend OASIS rule and in the same vain emphasizes the fact, that any next MQTT version will not be "5.x with x != 0" but instead 6 or 7 or what not. The (b) variant the reporter would prefer (as reader) when not a specific version number comparison is targeted in the statement but more a somehow indirect version number relationship is the target, and (a) when say a version number field or a specific UTF-8 string with the value like for the "Protocol Version" field.
> If we want to play nice with everyone, we could note early on in the document, that "in this specification the statement "MQTT version 5" is equivalent with stating both "MQTTv5.0" or "MQTT version 5.0".
> # ---
> @3.1.4 Response line 1277 suggest to rethink the placement of the requirement token, as without the yellow background (formats may not offer it, accessibility issues may render it invisible) it is unclear, where the mandatory statement ends. Proposed is to insert the square bracket insulated req token into the sentence right after the last mandatory "word" instead of after the final punctuation mark of the "mixed mode" sentence.
> # ---
> @3.2.2.5 Receive Maximum line 1413 simple typo replace "that" with "than". Also - being a German native this may only be unclear to me - why do we vary may and might in the non-normative comment sections (and maybe we should just concat adjacent such "section" with a plural indicating header like "Non-Normative comments")?
> # ---
> @3.2.2.6 Maximum QoS lines 1428-1445 suggest reordering of requirements to group per targeted "role" (server or client) and tag the requirement(s)
> currently at lines 1442-1445 (token is not present). By grouping the requirements per role, one could also better separate those (inside the group with a shift-ENTER kind of line break (instead of new paragraph ENTER))
> # ---
> @3.2.2.10 Topic Alias Maximum line 1499
> Maybe the reporter really misunderstood the nature of topics and a TOPIC ALIAS MAXIMUM, but if the understanding (that a topic is not a counter itself) is correct, here is another requirement awaiting rewording;-)
> # ---
> @3.3.1.3 RETAIN lines 1657-1678 are maybe not as clear as they could (eg. result looks identical and question rises, what if RETAIN == 1 and subscription did already exist?)
> # ---
> @3.3.2.1 Topic Name line 1724 "in section Error! Reference source not found.. It is a Protocol Error if the Topic Name is zero length"
> Suggest to find the "reference source".
> # ---
> @3.3.2.4 Payload Format Indicator lines 1736-1738
> Reporter thinks "Note that the UTF-8 Data in the Payload does not include a length prefix, nor is it subject to the restrictions described in section 1.5.3."
> is irritating due to being a "note" in normative text, and the content being "does not include" + "nor restricted by something elsewhere".
> Question: Could we add a more simply helpful detail info here?
> # ---
> @3.3.2.6 Topic Alias line 1766 simple typo replace "seta" with "sets" in "It seta a Topic Alias mapping"
> # ---
> @3.4.2.1 PUBACK Return Code has req token tagged statement inside a table's right most column (with head Description), suggested is to better reference only in that table cell and instead push out the mandatory statement with its tag inot the main prose ("left margin anchored") so it will not be overlooked.
> # ---
> @3.5.2.1 PUBREC Return Code similar to "@3.4.2.1 PUBACK Return Code has req token tagged statement inside a table's right most column ..." with dito proposed change.
> # ---
> @3.8.3 Payload line 2218 reference to "section 0" looks fishy, please check the real section target in the cross-reference.
> # ---
> @3.8.3.1 Subscription Options lines 2225 and 2230 read like they would profit from replacing "represent" with "represents" as a single bit is a singular entity (sorry, if my language feeling is incorrect here)
> # ---
> @3.8.4 Response line 2303 there is a "might" bracketed by quite some RFC2119 MUST occurences in neighbouring sentences, please consider using RFC2119 MAY or reword slightly to not leave the reader throwing a coin on which kind of may/MAY we might have meant.
> # ---
> @3.8.4 Response line 2311/2 consider using a non-breaking space between any "TYPE" "VALUE" prose statements to avoid reading flow interrupting line breaks like here between the type "QoS" and its value "0" here.
> # ---
> @3.8.4 Response line 2317 has no separate Non-Normative comment header associated and like already suggested at "@3.2.2.5 Receive Maximum line 1413" maybe best concat all adjacent non-normative comment blocks and prefix them with a plural version of that special header
> # ---
> @3.8.4 Response line 2328 "The Subscription Identifiers are part of the session state in the server and return to the client receiving a"
> does read like these IDs would be more active, than they are, suggested rewrite into passive, i.e. "The Subscription Identifiers are part of the session state in the server and are returned to the client receiving a"
> # ---
> @3.8.4 Response line 2339/40 "The server is not obliged to use the same set of Subscription Identifiers in are transmitted PUBLISH packet." reads unclear to the reporter, please specify if "in are" should be "that are" or "in a" or ...
> # ---
> @3.8.4 Response line 2340 "If the client remade a subscription [...]" - as it is normative text, reads unclear (the verb!) how to remake is the question. Should we reformulate or should the reporter be educated instead; please advise.
> # ---
> @3.8.4 Response line 2343/4 the line breaks the sentence between "has" and "sent" rather surprisingly considering the left line space estate
> # ---
> @3.8.4 Response line 2347 "Usage scenarios, for illustration if Subscription Identifiers." (reads a tad incomplete)
> # ---
> @3.9.2.3 User Property lines 2407/8 and all other requirements of this kind "spread all over" should be refactored to wher we define the "Maximum Packet Size" and instead of copy-pasting (mostly the generic master rule) only refer in a requirement like so:
> "It is a Protocol Error to include this property if it would increase the packet size beyond the one set as described in {[MQTT-x.y.z-n]- or section-ref}"
> instead of the present:
> "The sender MUST NOT send this property if it would increase the size of the SUBACK beyond the Maximum Packet Size specified by the session partner"
> # ---
> @3.10.3 Payload line 2452 reads "[MQTT-3.10.3-1] as defined in section Error! Reference source not found., packed contiguously." and if the reference were to be found would read better.
> # ---
> @3.10.3 Payload line 2454 again a suspicious "section 0" reference, please correct.
> # ---
> @3.11.2 Variable Header line 2496 replace "The Variable Header of the UNSUBACK Packet the following fields in the order:" with "The Variable Header of the UNSUBACK Packet contains the following fields in the order:" (missing verb)
> # ---
> @3.12 PINGREQ – PING request line 2537 another suspicious reference to "section 0" - please note the intended section instead.
> # ---
> @3.13 PINGRESP – PING response line 2555 yet another suspicious reference to "section 0" - please note the intended section instead.
> # ---
> @3.14.1 Fixed Header line 2581 suggested to replace "The server or client" with "The receiver" as only that role can act upon the received value and the statement then reads clearer (an initial "or" makes the single line of reasoning a two lane problem ...)
> # ---
> @3.14.2.1 Disconnect Return Code line 2602 "dito, only the other end of the channel" - suggested to replace "The Client or Server sending" with "The sender of".
> # ---
> @3.15.2 Variable Header lines 2692/3 as with the "TYPE"non-breaking-space"VALUE" instance above, only for "section"non-breaking-space{CROSS_REFERENCE}
> Also check globally ...
> # ---
> @4.1.1 Non-Normative example lines 2761-2768 reads irritating (after all these "Non-normative comment" indented unnumbered section heads) suggested is to use a caption like format element and ad global numbering to it like so: "Example {THE_COUNTER}: specific text of caption" and then have the example inside a special block element if it is code like, or as here more similar to the Non-normative comment "text block" structure.
> # ---
> Component and JIRA's severity field "priority (shiver)" set in the hopes it will be only editorial and trivial to fix whatever I will find.
> To cite Richard's announcement of WD11 ready to review:
> The editors have requested that each TC member open one Jira containing their feedback comments. The editors can then process anything editorial, remove duplicates, and bring more substantial issues to the attention of the TC.
--
This message was sent by Atlassian JIRA
(v6.2.2#6258)
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]