***********************************************************
CoolFission Documentation

This version of CoolFission is Copyright 1999, by Particle.
This is a shareware release, and should be considered as 
such. Educational institutions (i.e.: schools, colleges, 
universities) are not required to register this product. 
Commercial users MUST register this product. Send e-mail 
to bsptree@geocities.com about registration details.

No warranty of any kind is provided. The author, his 
family, friends, and pets are not responsible for anything!
Remember that if there is something you don't like; don't 
blame us, if there is something that you like, pay us. (In 
case of educational institutions, give us credit where it's 
due.) 

CoolFission is a powerful CGI backbone. It allows people to
quickly create complicated web-sites. In this release, 
which should be considered beta quality, there are not that 
many features however.

The idea behind CoolFission is that you write HTML code, 
just as if you were not using CoolFission. The difference 
is that now, you have the ability to inserts scripts into 
that HTML to be executed on the server whenever the page is
accessed. You can also include links to files, which you'd 
like parsed and included into the output.

***********************************************************
INSTALLING:

Installation is very simple. You simply take the 
coolfission.exe file and put it into your cgi-bin directory
(or other directory with cgi permissions)

You also place coolfission.cfg and also (usually) the 
coolfission.usr file. (the exact location of the usr file 
can be specified within the cfg file)

Set the appropriate executing permissions to 
coolfission.exe, reading permissions for coolfission.cfg 
and coolfission.usr, and writing permissions for 
coolfission.log, and you're done.

Note, at this moment, log file is not used.

***********************************************************
USAGE:

CoolFission starts up whenever you call it, usually by 
putting:

http://www.someserver.com/cgi-bin/coolfission.exe

into your browser. It then checks it's default 
configuration file, which is coolfission.cfg From this 
file, coolfission determines the location of the user file,
and other formalities.

The format of a cfg file is:

Name value

With # representing comments, for example:

#this is a comment
THIS_IS_SOME_NAME AND_THIS_IS_SOME_VALUE

Both name and value can be enclosed in double quotation 
marks if they contain spaces, however, it's not recommended
to have spaces in the name field.

After it has gotten the location of the user file, it 
checks to see how it will receive parameters. CoolFission 
works with both POST and GET methods. The first name gotten
from input is the name used as an alias. For example:

http://www.someserver.com/cgi-bin/coolfission.exe?coolfission

As you can see, in this example, "coolfission" is the alias
(the last one on the line)

Having got the alias, CoolFission goes on searching in the 
users file for that alias. The format of the users file is 
very similar to the CFG file. For example:

#comment
aliasname /full/path/to/file.html 

Alias is used to control access. Only the aliased names 
will be able to have access to coolfission (and thus, only 
they will be able to execute scripts within their html)

There is a default alias named coolfission, it poitns to a 
coolfission.html test page.

Once that is done, it goes and parses the file. Within the 
file, there are a few special CoolFission commands that are 
useful. For example, you can include other files to be 
parsed. This is very convenient, giving people the ability 
to have common headers/footers on their web-site.

The command to include a file is:

<special type="include" name="somefile.html">

All directory references should be relative to the 
directory where the file is located.

There is also the ability to display environment variables.
For example:

<special type="display" name="PARTICLE">

would display an environment variable named PARTICLE.

What would the ability to display environment variables be 
without the ability to set them? There is a command to add 
an environment variable:

<special type="ADD" name="PARTICLE" value="COOL">

This will give the environment variable named PARTICLE the
value of "COOL" ;-)

The most important feature however is probably the ability 
to execute scripts. At this point, only one scripting 
language is available. That language is Perl. Perl is 
freely available for all flavors of UNIX and Win32. (yes, 
even Windows95/98 run it) More information about perl can 
be found at www.perl.org 

To execute a script (perl script in this example) you'd do 
something like:

<script language="perl" runon="server">
<!--
print "<h3>This is the environment now:</h3>\n";
foreach $var (sort keys(%ENV)){
        print "<h4>$var = $ENV{$var}</h4>\n";
}
-->
</script>

The format is VERY similar to the JavaScript code used in 
conventional pages. However, notice the language now says 
"perl" instead of JavaScript, and runon parameter is 
present, telling us to execute it (and not leave it alone) 
Usually, you'd also want to enclose the script in a comment 
like the example above, since if for some reason, 
coolfission doesn't recognize the script, it will simply 
leave the code alone. (and you won't get a screwed up view 
in the browser if you have the code in a comment)

Note that CoolFission doesn't stop after a first run. So, 
you can easily combine these commands to form more powerful 
constructs. For example, a script can print out a command 
to include a file, set a variable, to display a variable. 

===========================================================
Warning: At this moment, there is no check for recursion. 
So, be careful in not including files which have already 
been included: Things like shown below should not be done 
(unless you know something I don't)

Filename: one.html
<special type=include name=two.html>

Filename: two.html
<special type=include name=one.html>

Just be careful (future versions will probably fix that).

Future versions will include much more scripting languages. 
For now, Perl should be able to do everything reasonably 
well.

***********************************************************
TIPS:

Usage tips:

***********************************************************
REFERENCE:

This section will go over a few basic commands.

===========================================================
Including SCRIPTS:
-----------------------------------------------------------
<script language="perl" runon="server">
<!--
print "<h3>This is the environment now:</h3>\n";
foreach $var (sort keys(%ENV)){
        print "<h4>$var = $ENV{$var}</h4>\n";
}
-->
</script>

===========================================================
Including OTHER FILES:
-----------------------------------------------------------
<special type="include" name="index.html">

===========================================================
Setting Variables:
-----------------------------------------------------------
<special type="ADD" name="PARTICLE" value="COOL">

===========================================================
Displaying Variables:
-----------------------------------------------------------
<special type="display" name="PARTICLE">

***********************************************************
Copyright(c) 1999, Particle

Send comments/requests to Particle <bsptree@geocities.com>
***********************************************************
