[Verse-dev] Verse protocol spec

[Emil Brink]

Hello.

I've been working (on and off) on creating some kind of better
version of the Verse specification document, since I find Eskil's PDF
to have some issues.

I'm using DocBook for the new document, combined with some custom XML
and XSLT for the command descriptions. Source will be available even-
tually, I assume.

The current result of these efforts, in HTML form, are available
here: <http://www.blender.org/modules/verse/verse-spec/book1.html>.

This is very much a work in progress, and to be regarded as a snap-
shot in time.

Some statistics for this snapshot:

system:   Emitted 16+5 commands. 12 descriptions, coverage is 57.1%.
object:   Emitted 13+3 commands. 1 descriptions, coverage is 6.2%.
geometry: Emitted 14+5 commands. 17 descriptions, coverage is 89.5%.
material: Emitted 1+1 commands. 0 descriptions, coverage is 0%.
bitmap:   Emitted 4+2 commands. 3 descriptions, coverage is 50%.
text:     Emitted 4+3 commands. 0 descriptions, coverage is 0%.
curve:    Emitted 3+3 commands. 0 descriptions, coverage is 0%.

The mathematically inclined immediately sees that these seven command
categories together define 77 command. Me, I had to use a calculator.
The notation X+Y above means X commands and Y aliases. Aliases are
mainly of interest to implementors, you can think of them as saying
there are X+Y commands defined, that's how it seems in use.

Known problems, except for being incomplete:
* It's incomplete (audio node is missing, for instance).
* It's wackily formatted. In particular, the command reference is a
  bit verbose to have all in-line on the front page, but that's the
  way the tools render it at the moment.
* The command references are not numbered correctly, they are all
  given the "I" numeral. This seems to be a DocBook bug.
* There should be far more cross-linking.
* Command data types need to be much more rigidly treated. I've been
  sketching something in this department.
* How aliases should be treated is being debated by Eskil and me,
  there might be changes in the wording to make "command" and
  "function" two distinct concepts.

For the commands, the big circle means "this command does not have
its parameters specified" and the big downward-pointing triangle
means "this command does not have a description". These are there
just to show me where I have work to do, and go away with time of
course.

Regards,

/Emil