[standards-jig] Re: [docs] Doc feedback - things that should be fixed
iainshigeoka at yahoo.com
Mon Oct 15 15:26:20 UTC 2001
At 05:56 PM 10/14/2001 +0200, you wrote:
>Some things I noticed in the docs, and that I think should be fixed.
>Overall, the docs are sadly not very coherent.. :/
Agreed. I've been suggesting changes through the standards-jig list as
part of the standards jig effort. I forgot to Cc this list. I wonder
which is the appropriate venue for it... J.c/foundation guys have any input?
>1) In http://docs.jabber.org/proto/html/vcard-temp.html
>This contains two broken links:
>Furthermore it should probably link to http://www.vcard-xml.org/, too
>The same for http://docs.jabber.org/jpg/html/main.html#REFVCARD-TEMP I'd
Agreed. Plus, for a temporary fix it sure has been around for a
while. Perhaps we should revisit this? Adam Theo's profile jig may be
able to take this and run... Who coordinates these decisions? Or do we
(Jabber community) just do these things and see what happens?
>2) The 0k / digest docs should make it clear that you are expected to send
>hashs as lowercase hex dump. This is important esp. for 0k auth, since
>there the resulting hash is digested again and again - but what you have
>to digest is actually the lowercase-hex-representation. This definitly
>should be clarified
Yes. I certainly agree. Jer has said he is working on a new draft of 0k
anyhow so perhaps we can have him make sure he addresses these concerns.
If it is case sensitive, I think it is an implementation bug in the server
not an issue for the standard (or will require a change to the standard
because one or the other is incorrect). Unfortunately, it also means the
clients will contain the same bug for compatibility... but it is probably
better to fix it rather than hack the standard.
For message digests, the hash values (and info to be hashed) are raw byte
data (even if the input happens to be text). The hex representation is
just a way to represent the data in ascii/utf8 (so it is xml
friendly). SHA should produce a 160 bit message digest. Raw bit data. If
you are doing subsequent hashes on the return digest data, you need to
re-hash that 160 bit message digest as raw data. At least that is the
spec. Bits are bits and the hex representation of the 160 bit md should be
the same whether you use capitol 'A' or lower 'a' to represent the hex
number. It is an extra step that gains you nothing to turn the raw md to
text, then hash that although it may be done that way because of the
implementation... I don't think so though.
>3) The http://docs.jabber.org/proto/html/clientserver.html at are a bit
>brief on auth; it might be a good idea to mention that you can do an
>auth-get first to determine what auth methods are supported (I think this
>feature is not directly mentioned anywhere; you can only extrapolate it
>from some of the example in the 0k docs and in other places)
>More importantly, though, JPG should be updated:
>http://docs.jabber.org/jpg/html/main.html#REFIQAUTH claims wrongly that
>type="get" is "Not used in this context". Wrong!
I completely agree on both counts.
>4) The 0k docs could need some pseudo-code to clarify how they work
>exactly. If you want I can provide this.
Like I said, Jer is working on this so perhaps you could collaborate
directly with him. 0k definitely needs fixing up so it is good to see this
>Finally, could somebody clarify what the current overall status of the
>docs is, and if anybody is working on something in this area? I see that
>(at least judging from docs.jabber.org) we still lack a single coherent
>description of at least the base jabber features (JPG is a good start, but
>it lacks to many things, and is more of a reference, with in many cases
>not enough explanation).
This is my impression: Docs are in a bit of limbo as the foundation settles
down and standards are moved under the care of relevant jigs. You should
check out the new x:event revamp for what is being proposed as the new doc
format for standards. I think that conversation went on in
standards-jig. There are several people working on the problem but from
different angles and not in any really coordinated way right now. My
impression is that Peter Saint-Andre is probably the best person to be
called the coordinator of the docs effort (is this correct Peter)?
I recently posted to the standards-jig (see its archives) that I am working
on a book on programming jabber in java and would like to put together a
"pretty" version of the spec. I am going to donate the organized "Jabber
spec" section of the book to Jabber (probably just make it a free download
from my home page since I'm not sure how it would fit in with the overall
jabber docs organization).
I'm currently in the process of working up a "quick reference chart" of the
protocols. As you have suggested, a _single_ coherent description of
Jabber is lacking. I've been pleasantly surprised to see that just this
simple reference chart (even in its current crude form) is extremely useful
in getting your mind around the Jabber protocols and mentally organizing
I'm also playing with some ways to present a protocol "at a glance",
perhaps in a chart or table. The goal of my book's "Jabber specification"
section being to create a three-tier "drill-down" organization. (at least
it looks that way right now.) You look at the reference chart to get info
about the protocols as a whole. If you need to know how to implement/debug
one, you pop over to the protocol quick reference. Finally, for the full
protocol spec, you can go to the write up on the protocol with background,
theory, and sample XML and source code.
IMHO, this "specification as a book" approach is not what jabber is
currently working on... instead we seem to be targeting an ietf-style
collection of separate specifications. My impression is that these specs
would then be tied together in white papers or programmer guides to link
the specs together to form a programmer friendly document. That is my
impression and I'm not sure if it is a good or bad approach to take (I
haven't really formed an opinion yet).
btw - I know there is another jabber book effort underway and it may also
be documenting the jabber protocols in some really neat way...
Do You Yahoo!?
Get your free @yahoo.com address at http://mail.yahoo.com
More information about the Standards