[standards-jig] Re: [docs] Doc feedback - things that should be fixed

Iain Shigeoka 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: 
>http://docs.jabber.org/proto/html/example-vcard-temp.txt and 
>http://protocol.jabber.org/vcard-temp/vCard-XML-DTD-v2-20000321.txt
>
>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 
>assume...

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 
happening.

>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 
them.

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).

Thoughts?  Comments?

-iain

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 mailing list