Bob, you're too efficient. I haven't had the time to comment on your
previous draft and already there is another one! The followng comments
then are with respect to the version just posted:
line 101: I'd suggest calling this the paremeter-part, which will simplify
the text in line 103 and let you get rid of the single quotes, which I think
are confusing.
line 102: this says that data is an optional part ... is it really optional or
just
dependent upon the operation?
line 103: I'd suggest calling parameters operation-parameters. Line 103, for
example, would read "The parameter-part consists of a sequence of one
or more operation-parameters. ...
I'd also suggest introducing the notion of parameter groups here rather
than in lines 115-117.
line 108 - 118: I still don't like overloading the name-length field, but if no
one
else cares, I'll go along with this agreement.
Do we reserve all negative lengths to have some meaning in the future?
Is the concept of a signed binary integer machine and language
independent, or do we need to back off to hex values and just say
0xFFFF and 0xFFFE (not -1 and -2)?
line 109: Is there a semantic difference between sending an additional parameter
value using the 0x0000 flag as opposed to sending a valid name-length, repeating
the parameter-name, and then the additional value? I don't think there is, but
if so
it ought to be noted.
lines 113 and 118: I'm just fussing with the words here I guess. You say that a
parameter
with the value 0xFFFF or 0xFFFE consists of only a name-length. I guess I'd
say that
these aren't parameters at all, but rather when encountering these values when
inspecting
what would normally be the next parameter name-length field, these "flags"
signal
end of parameters or end of parameter group.
line 128: suggest using the term paremeter-part instead of parameters
I'd suggest adding the names you've introduced here, e.g. END_PARAMETERS, to
the text in lines 112-118 where you define these flags.
line 165: what does the ellipsis denote? I assume it means other
parameter-group
0xFFFE secquences, but coudl also be read as
- more 0xFFFE sequences
- something undefined between 0xFFFE and the next parameter group
line 186: Isn't this really a diagram of a parameter-set?
line 190: I suppose it's obvious, but rather than u bytes, should you say
'length-of-name' bytes?
line 211-212: I'd either put this sentence after the first diagram describing
the
request operation, or actually include the response diagram.
lines 217-218: Why are operations signed values? Would it be crisper if you
used the capitalized term SIGNED-SHORT defined in the ABNF (or just deleted
this sentence since it has been defined in the ABNF)?
Is there value in showing the decimal value rather then the hex value in the
encoding? Is there any logic behind the assignment of codes to the
operations? Should there be?
lines 221-222: same comment as above for lines 217-218.
lines 231-239: This section seems redundant to me. I think all of this is clear
from the
previous section.
lines 232-234: Probably don't need to say that the name-length is two-byte
binary signed
integer in big endian order twice here. Also see comments above on using the
term two byte
binary signed integer.
line 243: You ought to say where the target URI is specified.
lines 247-251: I can't find reason-phrase in the model doument (although I have
to admit
I didn't look very hard). If a reason phrase is included, why isn't it in it's
own parameter
group?
line 253: I'd suggest rephrasing this to say "The remaining parameters are
encoded in
parameter-groups."
lines 253-257: This may be a bit of a departure in the ABNF, but what if we
defined the syntax of a
a request to be
version operation operation-parameters object-attributes [data].
and a response to be
version status [reason phrase] object-attributes [data]
You would still use the flags as defined to separate things as you
have defined them, but to me it would really clarify things and you
wouldn't need a lot of the complex language you have in this
section. I don't think this changes the bits that flow over the wire,
it just simplifies (I think) the description. You also don't need to
even include the tables in lines 271-279 since this mapping is
obvious from the ABNF notation. The only change with bits on
the wire is that you might see extra 0xFFFE flags for empty groups
(e.g. no operation-parameters).
table following line 271: last-document should be last-document-flag.
table following line 274: you show reason phrase in the second
parameter group. This conflicts with the statement in lines 250-251
which says that reason phrase will be the first parameter in the first
parameter group. Again, I think such confusion can be avoided by
declaring this in the ABNF as in the above recommendation.
table following line 285: Do we need signed integers? Is the notion
of signed machine and language independent?
lines 287-288: Is the notion of signed (negative values) machine and
language independent enough or do we just reserve the hex values
0xFFFF and 0xFFFE?
If the notion of negative numbers is machine and language independent,
do we need to reserve all negative lengths for future extension?
line 294: " .The dataSHALL" should read "The data Shall ..."
lines 294-295: These lines seem more than is required (and therefore adds
complexity) I think it would be simpler and would define the data sufficiently
to say
"The data part includes any data required by the operation.
line 296: What does this mean? Why the use of the word "may"?
lines 307-308: I don't know why you would put the URI in the operation layer?
Why is this an issue?
table following line 333:
I think more text is required to describe some of the semantics of
these headers. Perhaps it is obvious to one well versed in http,
but, for example, I think the use of connection header could use
more words than is available in the "values and Conditions"
column. When MUST a connection be closed? Who MAY
close a connection and under what conditions.
lines 345-352: The security sub-group is working on wording for this section.
Please do not
send this document to the ietf until we complete -- by the end of this week.
In particular, we will not define any application specific security mechanisms
so most of
what you have in this paragraph is incorrect.
Since we assume http, I did not review the appendix.
Roger K deBry
Senior Techncial Staff Member
Architecture and Technology
IBM Printing Systems
email: rdebry at us.ibm.com
phone: 1-303-924-4080