-= Files =-
   / 
      bio.pl
      board.pl
      guest.pl
      gwho.pl 
      help.tar.gz
      home.pl
      images.tar.gz
      mail.pl
      portal.pl 
      realm.pl 
      registration.pl 
     ./admin 
          admin-access.pl
          admin-chat.pl 
          admin-realm.pl 
          admin-text.pl 
          adminuser.pl
          swho.pl 
     ./config 
          config-ignore.pl 
          config-puppet.pl 
          config-puppeteer.pl 
          config-realm.pl 
     ./post 
          dice.pl 
          private.pl 
          who.pl 
     ./commandline 
          webchatcmd.pl 
          ./dump
               mysql.txt
                   ./mysql
                       webchat.access
                       webchat.data
                       webchat.schema
     ./Ethereal
	  Audit.pm
          Comm.pm 
          Database.pm
          Filter.pm 
          Home.pm
          Login.pm 
          Param.pm 
          Post.pm 
          Table.pm
          Weather.pm 
          Who.pm 

./

Contains all of the files and directory in the order that they would
normally appear on the web server.

     bio.pl
       A simple script that redirects to the proper location.  Only
       if the field has been specified.
     board.pl
       Message board functionality for Ethereal Relams.  It uses
       a simplistic threaded, expanded model for ease of it.  With
       E-Mail notification when direct responses are made.
     guest.pl
       Read-only access to streaming posts in public realms.  This 
       can be disabled by setting Guest access to no or post.
     gwho.pl 
       Also known as Global Who is On, allows to see people in all 
       public realms 
     help.tar.gz
       Documentation related for use of Ethereal Realms from the 
       users perspective. 
     home.pl
       Home page component of Ethereal Realms.  Allows for hosting
       a small site through a simple interface.  Size limitations 
       and the ability to disable the feature are done though
       ./admin/admin-chat.pl 
     images.tar.gz
       Images used in the display of various pages for Ethereal
       Realms, allowing for simpler intergration if need be.
     mail.pl
       Internal mail module for Ethereal Realms.  Allows to hide, as
       a puppet when sending or receiving mail.
     portal.pl 
       The analogy of a portal was used in the naming of this script, 
       as it allows to access realms and all configuration controls. 
     realm.pl 
       Handling of chat styles and posting. This is where all of
       the role-playing and chatting will take place. 
     registration.pl 
       The registration of puppeteers script. Will send out an e-mail
       to confirm validity of users. 

-= File details =-

Admin

This contains all of the administrative scripts. All of which are
web-based and require administrative flags to be set on the puppeteer.
Note that all of the following scripts have hard coded look and feel as
the author felt that administrative scripts did not need to reply on the
look and feel of the system itself.

     admin-access.pl
        Access Control Lists for supervisors can be controlled
        directly from this script.   If you want to allow a puppeteer
        to supervise a room, then here would be the place to assign
        those priviliges
     admin-chat.pl 
        This script will give you direct access to the dbms that 
        the scripts rely on heavily for attributes. Makes sure you
        look through this script first as to determine all tags to 
        be correct and/or suitable for your system 
     admin-realm.pl 
        Handles the basic creation of public realms and the removal
        of any realm. 
     admin-text.pl 
        Text administration, allows you to select documents stored on 
        the database and to change them as needed. Uses a text area to 
        achieve this. May be prudent to use a text editor as to copy 
        and paste the changes. 
     admin-user.pl 
        Puppeteer control. Allows you to add/remove users, to add 
        supervisory and administrative flags and to make a few changes 
        as needed.
     swho.pl
        Similiar to the Global Who, except that private realms are 
        listed as well. 

Config

These are configuration scripts that are dependent of the look and feel
of the server. Except for realm-config.pl all scripts are accessible by
all puppeteers as to make changes.

     config-ingore.pl 
          Allows the user to add remove puppets from their ignore list.  
     config-puppet.pl 
          Allows a puppeteers to add/remove puppets as well as modify 
          tagline, titles, bios and images. An image will be downloaded 
          from the site listed and the size will be added automatically. 
     config-puppeteer.pl 
          Place where a puppeteer can change their password and e-mail
          address. This can only be done when the password is provided. 
     config-realm.pl 
          Required the supervisory flag to be accessed successfully. 
          Will allow modifications of realm rules and controls. 

Post

These scripts are normally only accessed though the use of the realm.plx
script.

     dice.pl 
          A very simplistic dice roller that uses Math::TrulyRandom 
          to make the 'rolls' a bit more interesting. This like 
          private messages will make a post to the main chat window. 
     private.pl 
          This will simply allow you to send out private messages to
          those in the current realm. This will message the
          puppeteer and not the puppets themselves. 
     who.pl 
          Displays who is currently playing in the realm. 

commandline

There are only two scripts in this folder. This is primarily because
it's functions differ from all the others. As in they require the use of
the command line, and will be seldomly access directly.

     dumps/ 
          Within this folder one will find the necessary documentation
          and configuration files to configure MySQL.  This is needed 
          in order to use the database system with Ethereal which is 
          a requirement. 
     webchatcmd.pl 
          Command line tools for the webchat system. Will handle 
          expiration of puppeteers, realms, posts, as well as allow
          you to generate mailing lists by displaying the (distinct) 
          E-Mail addresses of all the members. 

Ethereal

This chat server aims to be somewhat object oriented. The following
folder contains classes and their methods used throughout
the chat system.

     Audit.pm
          Auditing modules used to store administrative and 
          supervisory tasks done within the system.
     Comm.pm 
          Handles all of the post gatrhing and insertiong into the
          database system. 
     Crypto.pm 
          Handles encoding features within Ethereal's parameters. 
     Database.pm 
          Designed primarily to hide most of the work used to access 
          the database. Will handle things from making a database 
          handle to retrieving documents.
     Filter.pm
          A safer, centralized method of filtering HTML based on a few
          factors.  This includes a somewhat primitive version of HTML
          tag closing for those that tend to forget.  
     Home.pm
          Home page module, currently only used for the removal of home
          folders on the system.
     Login.pm 
          Simple authentication module, as to make the scripts easier 
          to deal with. 
     Param.pm 
          Converts the parameters received into a hash, and will embed
          key data as either hidden fields (POST) or inline for use 
          in GET. 
     Post.pm 
          Handles the display of posts to the various viewing methods.
     Table.pm 
          Default table creation, used extensively in the scripts. 
          Really cuts down on code and increases maintainability. 
     Weather.pm
          Handles the parsing of the METAR weather reports.  Also will
          retrieve them as needed for use in weather forecasts on 
          the system and individual realms.
     Who.pm 
          Primary component of who.pls, handles the retrieval and 
          display; of who is currently on. 

-= Installation =-

Before you even begin you will need to retrieve three perl modules that
were not included with Ethereal realms.    This is primarily for the
fact that they were not created by the author of the scripts and thus
where not included. All of these modules can be retrieved by using CPAN.

     Digest::MD5 
          MD5 cryptographic hashing 
     Image::Size 
          Used to determine the size of retrieved image
     LWP::UserAgent
          Used in the retrieval of images for the module above. 
     MIME::Base64 
          Base64 encoding and decoding capabilities 
     MIME::Entity
          Tools for handling MIME encoded Emails, used for sending 
          posts to users.

The CPAN module itself can greatly simplify the installation of the
above modules.  As it also makes sure that dependencies are installed
in order to properly install the main modules.   In order to use CPAN
simply type in the following at the command prompt:

 > perl -MCPAN -e shell;

Then type in the following:
 cpan> install DBI
 cpan> install Msql-Mysql-modules
 cpan> install Compress::Zlib
 cpan> install Digest::MD5
 cpan> install Image::Size
 cpan> install LWP::UserAgent
 cpan> install MIME::Base64
 cpan> install MIME::Entity


After these modules have been downloaded and installed, you should
download the tar.gz file containing this distribution.  This is done by
decompressing the file, make sure all of the listed files above are in
fact there and do the following steps.

NOTE: The installation of the modules above will most probably need
other modules. Read the installation instructions of each module
specifically to determine what is needed

Copy the contents of ./webchat so to that it can be found by perl when
it searches for modules. In the authors case the location was: 
/usr/lib/perl5/site_perl/5.005/Ethereal/ (Linux RedHat 6.0) or
/usr/local/libdata/perl5/site_perl/Ethereal/ (OpenBSD 2.7-2.9) for 
which the Webchat directory is to complete the names of the 
modules which are called Ethereal::NAME.

Copy the remaining file structure of scripts with exception of the
./commandline path to a directory within webserver. You will need to
make sure that this directory can execute scripts (the ExecCGI in
Apache) bit or is a script alias. Otherwise the scripts will not be
accessible and not yield much result other then a display of the source
code. 

Next, configure the database according to the specific instructions
listed within the ./commandline/dumps directory.   The current database
installation and configuration system uses database dumps to makes
things easily and less complicated then changes done in Database.pm.    

As of version 1.3.0 and above there are no longer DBMs for use
with Ethereal.  They have been removed due to problems with Perl
on certain distributions or Unix variants.  As a result the next
step requires you to change one file:  Database.pm

Lines 56 to 60 should be adapted to meet your needs.  While this
may seem less gallant in a way, it does allow for the tags to
be placed in the database and allows for the subsequent use
of multiple web servers with one singular or clustered database
as a backend. 

Finally, all of the scripts including administrative scripts should be
operational.  Please make use of admin-chat.pl in order to change from
the defaults used by Ethereal itself, even though we do not mind added
visitors.


NOTE: registration.pl assumes you are using sendmail, as a result
  people using QMail may have problems, if the sendmail wrapper is not
  properly configured. The author was unable to test on a QMail server. 

NOTE: Future revisions may or may not include a Makefile.pl this has 
  yet to be determined. Also, oneshould be able to use
  Apache::Registry or at the very least Apache::PerlRun with the 
  scripts, this feature is tested on Ethereal Realms and should be possible, 
  since there was a very strict enforcement of variables as well as proper
  closing of the database and DBM's upon end of scripts.
