SCI VGA Documentation

[Gromitigo]

Brian -
   You mentioned before that documenting the next version will be quite a task.  Have you seen "docbook"?  Basically, you write the documentation in one format (XML), and another program spits it out in a bunch of other formats(HTML, Multi-page HTML, PDF, etc).  It's what is used in the Linux Documentation Project.  Worth knowing, if you want to auto-format everything and write it once.  

http://tldp.org/LDP/LDP-Author-Guide/

We use it a lot at work...*shrug*

[Brian Provinciano]

I'll look into it.

My decompiler might give me some automatic docs as well. I've got the variable name labeling down very well. It names them depending on what they are assigned, what they assign values to, if they are used as params in kernels, uses with properties, selectors, sends, etc. I've mapped 114 kernels into my decompiler with their param and result  type/name assignments. So, it detects whether an something is a string, pointer, object, etc. It even can turn text definitions to real strings. For example, Display(123 345) will dump Display("The text from entry #345 in text.123"). It also supports every SCI version, so we can all figure out how LSL7 and such work.

I've expanded my decompiler to have a logger also, that lists kernel functions and their use, so it will be very useful! I have it set it to only dump unmapped kernels, and/or kernels that return values that shouldn't, or use more params than they should, etc.

I'd love to update my site with info, but I don't like taking time away from my work on it, heh.

[OmerMor]

Brian - why would there be a kernel call with wrong number of parameters and how come it works?

btw - I can read between the lines that you are very excited about your work and you like to post those updates, so why do you need us to nag you for them?  

[OmerMor]

oh- one more question - why not add an option for automatic comment in the end of lines that call display() that will show the current text resource?

so when you decompile you can choose to get:

display(123 345)

    or

display("bla bla bla") // (123 345)

    or

display(123 345) // "bla bla bla"



just a thought... :-)

[Brian Provinciano]

Right now, the compiler automatically embeds all strings in the script. I am planning on making it automatically place strings in text resources if written as "string", and embed them if written as @"string" or %"string" or something. That way, you will be able to view them as text, but they will still go back to the text resource.

RE the kernels: We have documentation and code for the Kernels, handling them with certain parameters and returning them with certain values. This information is put in the database, and if something doesn't match up, such as a function returning a value that is a "void function()" in the docs, it will let us know. It also helps us when disassembling the original ones, because we can understand how they work, so it's easier to reverse engineer them.

[OmerMor]

What I ment was how come we have the wrong information about kernel functions?

if we figured that the kernel foo() has this signature:
void foo(string, int)

then how come it's possible to find out later that it has a different signature? I don't think sci supports polymorphism, right?
so what this means is that the earlier RE efforts were not 100% correct with some of the kernel functions?

[Brian Provinciano]

many kernel functions have different uses, with different types of returns and params, and we believe they are all correctly decoded, but it's primarily for use with SCI11/SCI32 kernels for the future implementations in FreeSCI. It will help us see how they are used in scripts in conjunction with the disassembly to make perfect recreations.

[OmerMor]

many kernel functions have different uses, with different types of returns and params...

Does that mean that SCI supports polymorphism?

[Brian Provinciano]

Most people wouldn't believe how versatile SCI is, and yes, it supports polymorphism. If an instance or class is created from another, it can either use it's existing methods, or override them with it's own. As well as overriding them, it can also still call the parent's method, as well that can call it's parent, etc. The functions, methods and procedures can use any number of parameters of any typecast. Have a look at the kernel docs with SCI Studio, as well as the rest keyword.

SCI code is written like this:
 Display("something" 100 aProp aVar)

it is compiled into something like this:
pushi 4
lofss "something"
pushi 100
pTos aProp
lst aVar
callk Display 8

that says were's calling it with four (1,2,3,4) parameters, and that's how you write it. However, there are actually five. Remeber in the docs "paramTotal"? Yes, that's param(0). Many functions use it to determine how many parameters to read. It's used all over the place (obj.sc for starters).

[OmerMor]

Thanks for the info... I'll look it up.