[standards-jig] RFC Draft 3.2
iainshigeoka at yahoo.com
Wed Feb 20 18:04:01 UTC 2002
It looks great. Most of my issues are just spit and polish.
Editor nitpick: you occasionally use the word "above" or "below" to
reference proceeding or following sections. Since the text may be broken in
pages in unpredictable ways, something that is "below" in one big HTML doc
may be "above" when its broken onto a previous page. So in general, you
should avoid "above" and "below" and directly refer to the section number or
use words like "proceeding" or "following". I just got slapped for that one
so I thought I'd pass it on. :)
A few notes:
1.4 Excellent. I like the fact that you have included the standard RFC
nomenclature here. However, throughout the document, you have not
capitalized the instances of these words (MUST, MAY, etc) to indicate their
usage as RFC standard words. I think you should do so (search and replace
but watch for what is a keyword and what is just text).
>From - A client sending a 'from' attribute to jabberd will cause the server
to respond with a <stream:error> and bail (and thus not ignore it as this is
indicating). Shouldn't this description match the behavior of jabberd?
Also, if it is not too hard to do, the information regarding who normally
sends, and who ignores these attributes would be easier to understand in a
table. So keep the bullet list with the descriptions but place the roles an
responsibilities for each in a table:
to receiver JID ignored
from ignored receiver JID
id ignored session key
5.7 code example
Can you prefix the packets with initiator: and receiver: so you can see this
is a conversation?
5.8 code example
I like the example. Should you note here that on most production servers,
you will need to authenticate (or otherwise establish your identity as
receiving-ID) and set your presence to "available"? The latter may be over
the top but the former issue may be something that critical readers will
wonder (how does the host know who I am?) I definitely realize this is a
simple example but if someone were to type this in against jabberd they
would not see the same results... I think that you should probably just
keep it as is but its something to consider.
Bottom example. Are you required to send the <stream:error> in the case of
malformed XML? I thought most Jabber entities will just bail out without
6.2.2 should you mention that each child may occur at most one time? This
is expressed in the schema but not the dtd. And seems significant enough to
warrant mention in the descriptive text.
6.2.5 I think it would be good to consistently format the examples.
Previously string constants are quoted with single quotes ('). These
examples use double quotes ("). Although this is valid, it may be
confusing. Can you you one or the other throughout? The same issue applies
to how you are formatting the attribute names (') and values ("). I'm not
sure if it is consistent or not but just wanted to mention it here.
6.3.2 Once again, mention that each child element may occur at most one
Bullet "priority". I think you should insert the word "integer" as
priorities can only be integer numbers equal to or greater than zero: An
integer number representing...
6.4.1 "id" bullet. Second sentence. I think the word "may" should be
"SHOULD" or "MUST". I would vote for MUST.
"type" bullet. First sentence. Remove quotes around "conversation". The
quotes and your current conventions make it look like "conversation" is a
valid type attribute value. It reads just as well without the quotes
"set" type sub-bullet. Should mention that 'set' can be used in multi-chunk
replies terminated by a final 'result' reply. (e.g. iq:search)
6.4.5 You may want to show an example of a multi-chink reply as well.
7.1. Third paragraph. Can't x extensions be found in some iq elements as
well. In particular I was thinking of the x:event, x:expire, x:delay. If
so, the first sentence parenthesis should be (and less frequently the
presence and iq elements)
Section 8 or 10. Typically the RFCs I've read that have security features
will include a section that analyzes the weaknesses or possible attacks on
those security features. For example, dialback relies upon and is
vulnerable to DNS hacks. Should we include something like that here? An
example, see the BEEP rfc (RFC3080).
Do You Yahoo!?
Get your free @yahoo.com address at http://mail.yahoo.com
More information about the Standards