[Verse-dev] Minor updates; spec verification

[Emil Brink]

Hello.

I've just committed some minor changes to the CVS HEAD (the to-become-R5
code). They were found while doing some spec work, more of which below.

The changes in verse.h are:

* There is a typedef void VNOPackedParams, that introduces an opaque
   type name for the data block returned by verse_method_call_pack().
   This used to be a void * everywhere, which is less informative.
* VNOPackedParams is used where needed.
* The final arg to verse_send_connect(), the 'expected_host_id' uint8
   pointer, was made const. It really is, so it should be.

These should be very quick to adapt any client code for.

As an example, building Purple against the updated Verse core results in 
zero warnings or errors, just like before; this is probably because the 
code uses void *, which are converted by C anyway. I'm still going to 
update Purple to use the proper type name now, of course.

                                  -x-

I've also spent a while trying to machine-verify the specification
document, at least the API parts of it. This is in response to there
being some complaints within the Uni-Verse project that the documen-
tation is lacking. Here is what I did:

1) Write a quick XSLT transform that goes from the custom XML in
    which the protocol is defined, and into C header syntax.
    (The interested can look at 
<http://projects.blender.org/viewcvs/viewcvs.cgi/verse-spec/protocol/commands2header.xsl?rev=1.1&cvsroot=verse&content-type=text/vnd.viewcvs-markup>
     it's just a couple of pages.)
2) Concatenate the result with the "real" verse.h from CVS.
3) Include the result in a one-line C program.
4) Try to compile said program, relying on the GCC compiler to catch
    any mismatched declarations that are the result of errors in the
    protocol spec.
5) Observe the compiler's output.

I did this yesterday afternoon/evening (only took 2-3 hours), and I
found a handful of minor issues with the documentation. They have of
course all been fixed now, and the VNOPackedParams type as mentioned
above has also been integrated into the specification.

Thanks to Camilla for the tip to use GCC to do the parsing and 
comparison, it's way easier and better than any quick hack I could
have thrown together.

Apologies for not doing this testing earlier. More feedback always
helps me to know where more work is needed. If you find an error or
omission in the documentation, don't just sit on it thinking "haha,
what a loser", report it so that I can at least try to fix it. Thanks.

Regards,

/Emil