
                                  FanciANSI
                              Version 0.8 (beta)

---------------------------------------------------------------------------
Introduction.
---------------------------------------------------------------------------

Welcome to FanciANSI, Version 0.8, the first software release of Tom Lebens 
and FanciWare Software. FanciWare Software is sponsored by Fanciful Online, 
and is located at http://www.fanciful.org/FanciWare.htm on the World Wide 
Web. The latest version of FanciANSI is available at this address, via FREQ 
at 1:202/801 using magic name FANCIANSI, or in file area 1 on Fanciful 
Online (at 619.549.6685; telnet://online.fanciful.org; 
http://www.fanciful.org; log in using FANCI WARE as name, and SOFTWARE as 
password). So, if you are not sure whether this is the latest release of 
FanciANSI, you should first (right now!) download the latest version.

---------------------------------------------------------------------------
What it is?
---------------------------------------------------------------------------

One of my pet peeves, as a WINS (or Wildcat! 5) sysop, has been the need to 
maintain separate files, .BBS files and .HTM files for things such as
rules, BBS lists, newsletters, game bulletins, and announcements (you
know, bulletins and display files). In addition, files I receive
automatically, such as newsletters and BBS lists that I receive over the
FileBone, must be hand-converted, or processed with a batch file kludge to
allow their display both as .BBS files, and as .HTM files. With FanciANSI
I can process these files with a semaphore, and automatically and 
instantly update both the .BBS files and the .HTM files. And, when I make 
a change to a .BBS file, I no longer have to remember to make the same 
change in the .HTM file, which is far too much for my little brain to 
remember.

FanciANSI is my best answer to my problems, and hopefully it will help
you as well. FanciANSI is a WCX CGI script for displaying .BBS files (WC 
@Code format) to HTML callers, automatically, on the fly, in real time!

With this latest release, FanciANSI now supports the generation of either
HTML (i.e., a full blown web page), or JavaScript, so it can be called
using a simple <SCRIPT> tag within just about any web page. When used to
generate JavaScript, the calling web page can even be edited in most
WYSIWYG editors, such as FrontPage!

---------------------------------------------------------------------------
How do I get started?
---------------------------------------------------------------------------

To install this program, simply copy it into your Wildcat 5! (WINS) home 
directory, e.g., C:\WC5 or C:\WINS. It must be named html-bbs2htm.wcx. 
That's really all there is to it, although you will most certainly want to 
do more in order to make your HTML pages look really cool.

For now, though, give it a test run. The program is invoked from the 
address line of a web browser, and the basic syntax for this script is as 
follows: http://yoururl/code/html-bbs2htm?file=xxx&dir=yyy where yoururl is 
the URL of your WINS; xxx is the name of the .bbs file to be displayed, 
without the ".bbs" extension; and yyy is the subdirectory of your WINS home 
directory in which the file resides. The only valid parameters for yyy in 
the basic syntax are "bull" and "disp", which automatically reference your 
bulletin and display file directories, as specified in wcConfig. If you 
omit the &dir=yyy, FanciANSI defaults to "bull".

Here is a simple example:

http://www.fanciful.org:81/public/code/html-bbs2htm?file=bull1

(note the "dir" element is left off, so FanciANSI defaults to "bull".

Give it a try. View some of your bulletins or display files through your
web browser.

After you have taken the program for a spin, and made sure it's working in 
its most basic format, continue with these instructions to really make your 
HTML displays dazzling.

---------------------------------------------------------------------------
Dazzling displays?
---------------------------------------------------------------------------

There are three ways to make your displays dazzling. The first is to use
the above format, but to add header and footer HTML of your own. It's real 
easy. The second is to use a configuration file to specify not only the 
header and footer files, but also the file to display and its directory.
This allows you to venture outside your "bull" and "disp" directories, but
only if you have created a configuration file first. The third is to have
FanciANSI generate JavaScript output, instead of HTML, and to call 
FanciANSI using a <SCRIPT> tag. Using this approach, the call to FanciANSI
is "hidden" within the pages HTML, so you won't see the call in the 
address line of your browser.

Why is a config file worth the trouble? Why generate JavaScript? Read 
on . . .

---------------------------------------------------------------------------
Header and Footer files without a configuration file. (Default and custom)
---------------------------------------------------------------------------

All ya gotta do is create the header and footer files, and stick 'em in the 
right directory. You can create a default header and a default footer for 
both your bulletin files, and your display files, i.e., files in the "bull" 
directory and files in the "disp" directory. You can also, or instead, 
create custom header and/or footer files for each file in your "bull" 
directory and "disp" directory. And, you can mix and match, so a custom 
header works with a default footer. If you have both a custom header or 
footer and a default header or footer, the custom header or footer will 
always take precedence over the default header or footer.

Now first things first. Where do the default/custom header files go, and 
what are they called?

Here are the file names to use, and the directories into which the files 
must be placed. The file names must be precisely as specified below, and 
they must be in the designated directories, or FanciANSI will not detect 
them, and thus will instead display the hard coded (ugly) header and footer 
instead.

 Bulletins: (must be in "bull" directory, as specified in wcConfig)
    Headers:
       Default:
          header-bulletin.htm
       Custom:
          header-filename.htm (where filename = filename without extension)
    Footers:
       Default:
          footer-bulletin.htm
       Custom:
          footer-filename.htm (where filename = filename without extension)
 Display Files: (must be in "disp" directory, as specified in wcConfig)
    Headers:
       Default:
          header-display.htm
       Custom:
          header-filename.htm (where filename = filename without extension)
    Footers:
       Default:
          footer-display.htm
       Custom:
          footer-filename.htm (where filename = filename without extension)

Thus, by way of example, if you create a file with the name and path of 
c:\wc5\bull\header-bulletin.htm and a file with the name and path of 
c:\wc5\bull\footer-bulletin.htm, these files will be added to EVERY file in 
the "bull" directory that one displays using FanciANSI, UNLESS there is a 
"custom" header/footer for a particular file. If I create a file named 
c:\wc5\bull\header-bull1.htm and a file named c:\wc5\bull\footer-bull1.htm, 
these two files will be used with "bull1.bbs" in lieu of the default 
header/footer files.

The format for the header/footer files is the same as for the header/footer 
files used in conjunction with config files, which is documented below.

---------------------------------------------------------------------------
So what about these config files? (Advanced)
---------------------------------------------------------------------------

An advanced (or .cfg file) syntax is also supported by this version, 
allowing custom header and footer files, and display of ANY text file you 
specify, not just .bbs files and not just files in your "bull" and "disp" 
directories. This syntax uses a .cfg file (which you must create) and has a 
syntax as follows: http://yoururl/code/html-bbs2htm?file=xxx&dir=cfg where 
yoururl is the URL of your WINS; and xxx is the name of a .cfg file located 
in the "data" directory (but leave off the ".cfg" extension in the call).

Use of a config file is the ONLY way to display files outside your "bull" 
and "disp" directories, or without a .bbs extension. This is for security
purposes.

---------------------------------------------------------------------------
So what does this config file look like?
---------------------------------------------------------------------------

Format for .cfg file (placed in "data" directory)

Line 1: fully qualified directory path of main input file
        either in "c:\wc5\bull\" format or in "wc:\bull\"
        format. (NOTE THE "\" AT THE END OF THE PATH IS
        REQUIRED IN THE PRESENT VERSION.)
Line 2: filename and extension of main input file, e.g.,
        "bull1.bbs"
Line 3: fully qualified directory path and filename of
        header file
Line 4: fully qualified directory path and filename of
        footer file

---------------------------------------------------------------------------
Example bull1.cfg file (placed in "data" directory)
---------------------------------------------------------------------------

wc:\bull\
bull1.bbs
wc:\http\FanciTemps\bull1-header.htm
wc:\http\FanciTemps\bull1-footer.htm

---------------------------------------------------------------------------
Here is an example of a header file! (For default, custom or advanced)
---------------------------------------------------------------------------

Example Header File (wc:\http\FanciTemps\bull1-header.htm)
<html>

<head>
<title>Bulletin 1: System Rules</title>
</head>

<body>

<p align="center"><a href="http://www.fanciful.org/default.htm">
<img src="http://www.fanciful.org/graphics/fancibanner.gif"
alt="fancibanner.gif (8924 bytes)" border="0" width="468" 
height="60"></a></p>

<h2 align="center">Bulletin 1: System Rules</h2>

---------------------------------------------------------------------------
And, and an example of a footer file. (For default, custom or advanced)
---------------------------------------------------------------------------

Example Footer File (wc:\http\FanciTemps\bull1-footer.htm)
<p><a href="http://www.fanciful.org/FanciWare.htm">
Return to FanciWare Home Page</a></p>

<p><a href="http://www.fanciful.org/default.htm">
Return to Fanciful Online's Internet Home Page</a></p>

<p><em><font size="3">Copyright 1996/97/98/99 
Tom F. Lebens</font></em></p></body></html>

---------------------------------------------------------------------------
So who needs JavaScript? (JavaScript)
---------------------------------------------------------------------------

Well no one I suppose, but if you want to be really cool it's a must have!

One of the things that troubles me with earlier version of FanciANSI was
that the cart seemed to pull the horse. In other words, the whole page had
to be generated by FanciANSI, instead of just the part you wanted to
create on the fly. What I really wanted was a code you could stick into
the HTML somewhere that would cause the web server to stick in the stuff
you wanted created on the fly.

My first inclination was to use Wildcat 5! or WINS templates to accomplish
this, however that still invloved calling a server-side CGI script of some
kind, and required that I write the server-side CGI.

Well I already had FanciANSI to strip the @-codes, but we were talking 
about a pretty different approach.

So, back to the drawing board I went.

As it turns out, the <SCRIPT> tag in HTML has a SRC="url" attribute. And,
after studying Ray, "Mastering HTML" from Sybex, and Flanagan, 
"JavaScript: the Definitive Guide", I finally realized that a URL was a
URL!

What I mean by this is that a URL is a pointer to a source of some kind
of output. Generally we think of URL's as pointing to static HTML pages,
but as the internet has exploded, we have come to know that a URL may be
an ASP, or a CGI, the output of which is HTML.

The books above suggest that when the <SCRIPT> tag is used, the URL can
point to a source of JavaScript. This sauce can be static, or can be a
CGI. And, the source can even be on an entirely different server from the
original page!

So, wha-la, all FanciANSI needed to be able to do was output JavaScript
instead of HTML, and a whole new chapter would be opened for FanciANSI.

Just imagine! You can now use FanciANSI to display a newsletter, the 
text of which does not even reside on your computer!

The possibilities are really quite endless. Just imagine your local BBS
list being maintained at one central repository (running Wildcat 5! or 
WINS) can now be displayed on any web page anywhere on the internet! 
When an update is made, all of these pages are instantly updated in the
blink of an eye!

You can even call FanciANSI more than once in a single HTML document!

Be creative, and please do let the author know of the inventive ways in
which you use FanciANSI!

---------------------------------------------------------------------------
Okay, okay, how do I do it?
---------------------------------------------------------------------------

First, you must use the additional syntactical element, "language", and set
it equal to "JavaScript". Thus, the syntax becomes 
http://yoururl/code/html-bbs2htm?file=xxx&dir=yyy&language=javascript or 
http://yoururl/code/html-bbs2htm?file=xxx&dir=cfg&language=javascript.
In either case, header and footer files are ignored--they are HTML files
after all.

The only other valid value to which "language" can be set is HTML, but if
"language" is omitted, FanciANSI will default to HTML so that it is 
compatible with prior versions.

---------------------------------------------------------------------------
Now the call
---------------------------------------------------------------------------

Using the syntax above, all that is needed now is to insert a couple of
tags into your HTML document where you want the text to show up.

They are as follows:

<script language="JavaScript" type="text/javascript" src="URL">
<!--
// -->
</script>

where URL is the URL of FanciANSI in the syntax denoted above.

There are some additional things that can be added to this basic set of 
tags, some of which are illustrated in the complete HTML example below:

<head>
<title>This is an example</title>
</head>
<body>
<h1>Bulletin 1</h1>

<!-- Here is the call to the software that automatically converts the 
bulletin -->

<font size="3">
<script language="javascript" type="text/javascript" 
src="http://www.fanciful.org:81/public/code/html-bbs2htm-dev?
file=bull1&language=javascript"> <!--Broken for readability-->
<!--
// -->    
</script>
<noscript>
<p>
In order to view, you must use a JavaScript enabled browser
</p>
</noscript>
</font>

<!-- End of call to software that automatically converts the bulletin -->

</body>
</html>

Whew! That's a lot of gobledegook! Just remember, though all, you really
need are the two <SCRIPT> tags, and the URL, and you are all set.

Oh, and one other thing. There is one drawback to this approach. Any
browser that does not support JavaScript will not support this approach.
So, if you want to be really super tricky, you will include a link to
FanciANSI within the <NOSCRIPT></NOSCRIPT> tags that generates HTML. I
mention this particularly because with all of the wireless devices coming
onto the internet, there may be more of a need to support non-JavaScript
browser for at least the short run.

---------------------------------------------------------------------------
Bugs!? <splat!>
---------------------------------------------------------------------------

There are no known bugs in version 0.8 (beta).
Visit http://www.fanciful.org/FanciWare.htm for the latest bug report.

---------------------------------------------------------------------------
So what's the catch?
---------------------------------------------------------------------------

This script may pose minor security risks, depending on your particular
setup, so please take every precaution and be aware of what this script
does. For security reasons, this script is only functional with ".bbs"
files in the "bull" and "disp" directories, OR ANY FILE YOU SPECIFY IN A
PROPERLY FORMATTED .CFG FILE, which you must create. Thus, the security
risk basically lies in the fact that using this program, a caller whether
they are logged in or not) can display the contents of any .BBS file in
your "bull" directory or your "disp" directory. Beyond that, you must
create a .cfg file in your "data" directory.

Thus, access is significantly limited, and a user cannot display files
indiscriminately. But, if you have confidential .bbs files in your "bull"
directory or your "disp" directory THEY CAN BE VIEWED BY THIS SCRIPT.

---------------------------------------------------------------------------
What's next?
---------------------------------------------------------------------------

Users need not be logged in order to use this program, although a future
option will allow you to operate in a secure mode, allowing only users who
are logged in to access files (or at least certain files--you will be able
to specify "insecure" files). These future options will also include the
ability to limit access via this program to certain files.

As always, I am always eager to hear what ideas you have for improving
this program, and what cool uses you have come up with for it. We often
update the program based on the feedback we receive from users. Send your
suggestions to tom.lebens@fanciful.org (but see the section below entitled
"Support").

---------------------------------------------------------------------------
So how do I register?
---------------------------------------------------------------------------

No need! I saved the best for last! This program is freeware. Just keep 
running your BBS, and providing a first class experience for your users, 
and that's pay enough. If you insist, however, send donations to:

Tom Lebens
%FETF
4250 Executive Sq., Ste. 510
La Jolla, CA 92131

Mark the envelope "PERSONAL"

---------------------------------------------------------------------------
Support!
---------------------------------------------------------------------------

Well, I'll do my best to help, but I am real busy, and can't guarantee that 
I will get back to you right away (or at all). I will apologize in advance, 
and don't take offense if I don't respond. But, I get over 100 e-mail 
messages a day, and I simply can't handle them all with a personal 
response. If you have a REAL bug that you have found, or a REAL suggestion 
for improving the software, I will definitely respond. And, if you do have 
a problem that is not addressed in these doc's there is a good chance I 
will respond to that. But, I will probably not respond if the answer is in 
these docs, so better read 'em again if you don't get a response.

My e-mail address is tom.lebens@fanciful.org; and netmail is 1:202/801

---------------------------------------------------------------------------
Closing
---------------------------------------------------------------------------

Hey thanks for reading this blabber. Enjoy the program, and check the web 
site often, as we are adding new feature fairly often.

---------------------------------------------------------------------------
3/21/2000, Copyright 1999, 2000, Tom F. Lebens
---------------------------------------------------------------------------

