[sldev] [PROTOCOL] Protocol Documentation

[Donovan Linden]

In the long run, we want to implement some sort of runtime service  
description query ability, perhaps invoked using the OPTIONS verb. I  
believe zero talked about this in one of his office hours quite a  
while back, but we haven't started on this yet. I do have some code  
that I wrote with this use case in mind in the mulib/shaped.py  
module, but it's not really being used by anything yet. I'm not sure  
how this approach would be combined with one-shot capabilities; maybe  
they can notice OPTIONS and not expire.

In both the short term and the long term, we definitely should be  
documenting the API of the client-accessible capabilities on the  
public wiki. As we go forward with the architecture working group,  
perhaps these API wiki pages could even be created before any of the  
code was written.

As for the markup to describe the capabilities in the wiki in the  
near term, I think plain old LLSD should be fine. Something like:

<map>
	<key>foo</key>
	<string />
	<key>bar</key>
	<uuid />
</map>

Thanks for pushing on this! We totally need a public love machine.

Donovan

On Oct 2, 2007, at 3:32 PM, John Hurliman wrote:

> I merged my own documentation skeleton page on the wiki with the  
> "Protocol" page at http://wiki.secondlife.com/wiki/Protocol, this  
> is still the official home of all protocol documentation for Second  
> Life and I assume will be the closest thing there is to an official  
> specification of "How Second Life Works".
>
> Community driven documentation is going to be more important then  
> it was previously due to the way the protocol is changing.  
> Traditionally we had everything going over UDP and the format of  
> things was documented by a file called message_template.msg. This  
> allowed clients to either build packets and verify them at runtime  
> (such as the SL viewer) or pre-generate code to represent packets  
> in memory (such as libsecondlife). With the new capabilities system  
> we have no message_template.msg, and there is no way to pre- 
> generate code to represent message structures or verify the  
> correctness of code at runtime. Right now you can't even query what  
> capabilities are available to clients although this may change in  
> the future.
>
> The message_template party was fun while it lasted but we are going  
> to have to go back to the traditional method of development,  
> meaning good documentation that unit tests can be built from and  
> third party implementations can work off of, since runtime or  
> compile time verification is no longer possible. Linden Lab  
> internally uses the viewer and simulator source code for  
> documentation (I'm told), so if we want a specification the  
> community will be responsible for generating it. Some open questions:
>
> * Is the current structure of the page a good breakdown of the  
> different sections of the protocol? Should things be split up or  
> consolidated in any places?
> * Since all of the capabilities will need to be described here we  
> need a standard markup to document them. Should the LLSD notation  
> format be used, or some other pseudo-markup?
>
>
> For some background, this was discussed at Zero Linden's office  
> hour today (Zero was out but other Lindens filled in). The  
> conversation went something like this:
>
> LL: the capabilities API may not necessarily be the same as the old  
> message template
> Me: so we need to hand-write new processing code for each  
> capability, unlike the old udp system
> Others: wouldn't a server-side changelog fix this?
> Me: if i understand right, things are transitioning from a system  
> where we have a file format detailing the structure of messages, to  
> a system where there is no documentation, no way of the client  
> knowing what it is supposed to handle or not, and no idea what  
> means what once you figure out the capabilities you are supposed to  
> handle
> LL: we can't log every change, it would be cluttered and irrelevant
> LL: the source code is very clear on how all of this works
> Others: the viewer isn't documentation, it's GPL licensed source  
> code that is neither a preferred medium for documenting a protocol  
> nor a license-compatible method of providing docs
> LL: it is very clear documentation
> Me: so we can look through the SL viewer source code to learn how  
> things work and reimplement it in BSD licensed libsecondlife correct?
> [13:31]  Rob Linden: Eddy, as long as you don't steal code, yes
> LL: so this whole discussion about documenting the capability API  
> is just so people can steal code?
> Others: no, we don't want your source code. please keep it
> Me: we would like documentation to write independent  
> implementations though
> Others: independent implementations... part of that whole  
> architecture working group thing
>
>
> John Hurliman
> _______________________________________________
> Click here to unsubscribe or manage your list subscription:
> /index.html