-= Files =-
   / 
      bio.pl
      board.pl
       * board
       * sysboard.pl
      gallery.pl
       * gallery
      gwho.pl
      mail.pl
      poll.pl
      portal.pl 
       * go
       * static.pl
      realm.pl 
       * stream.pl
      registration.pl
       * confirmation.pl
      reset.pl
      weblog.pl
       * extlog.pl
       * quicklog.pl
      webring.pl
       * ring

     ./admin 
          swho.pl
          system.pl
           * access.pl
           * attrib.pl
           * contact.pl
           * font.pl
           * genre.pl
           * gummy.pl
           * poll.pl
           * realm.pl
           * template.pl
           * weblog.pl

     ./config 
          ignore.pl 
          gallery.pl
          gummies.pl
          home.pl
          puppet.pl 
          puppeteer.pl 
          realm.pl 

     ./gz
          css.tar.gz
          gummies.tar.gz
          help.tar.gz
          images.tar.gz
          js.tar.gz

     ./post 
          colours.pl
           * zoom.pl
          dice.pl 
          private.pl 
          who.pl 

     ./commandline 
          convert.pl 
          erealms.pl 
          release.pl
	  rewrite.pl
          spel.pl

          ./dump
               password.txt
               postgres.txt
                   ./postgres
                       ethereal-schema.sql
                       ethereal-functions.sql
                       ethereal-data.sql

     ./eRealms
	  Audit.pm
          Comm.pm 
          Database.pm
          Filter.pm 
          Home.pm
          Image.pm
          Login.pm
          Mail.pm 
          Param.pm 
          Post.pm 
          Pull.pm
          Spel.pm
          Stamp.pm
          Table.pm
          Template.pm
          Weather.pm 
          Who.pm

NOTE:  Filenames with * prefixing their names are in fact simply
       symbolic links, meaning they point to the file above and work
       based on filenames.

./

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
      * board
      * sysboard.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.

     gallery.pl
      * gallery
       The gallery sub-component of Ethereal realms.  This is the
       client side which allows users to see displayed works.

     gwho.pl 
       Also known as Global Who is On, allows to see people in all 
       public realms.

     mail.pl
       Internal mail module for Ethereal Realms.  Allows to hide, as
       a puppet when sending or receiving mail.

     portal.pl 
      * go
      * static.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 
      * stream.pl
       Handling of chat styles and posting. This is where all of
       the role-playing and chatting will take place. 

     registration.pl
      * confirmation.pl
       The registration of puppeteers script. Will send out an e-mail
       to confirm validity of users. 

     reset.pl
        This script allows one to reset passwords for users excluding
        anyone with a degree of priviledge as to avoid abuse.

     weblog.pl
      * quicklog.pl
       Allows for the passing of quick information to all users on the
       site.   This is done through a new style system which works like
       a weblog.

     webring.pl
      * ring
       Integrated webring like behaviour for public and hybrid realms.


-= 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.

     swho.pl
        Similiar to the Global Who, except that private realms are 
        listed as well. 

     system.pl
      * access.pl
      * attrib.pl
      * contact.pl
      * font.pl
      * genre.pl
      * gummy.pl
      * poll.pl
      * realm.pl
      * template.pl
      * weblog.pl
        This is the heart of the system configuration.   Re-created
        from previous versions as to take on a more Control Panel look
        and feel similiar to what the hosts have been using.


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.

     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/system.pl 

     ingore.pl 
       Allows the user to add remove puppets from their ignore list.  

     gallery.pl
       The management of galleries by users themselves.

     gummies.pl
       A way to be shown every gummy at the same time so you can
       select a preffered one with more ease.

     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. 

     puppeteer.pl 
       Place where a puppeteer can change their password and e-mail
       address. This can only be done when the password is provided. 

     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.pl
script.

     colours.pl
       Colours will show you a list of all colours so you can select
       colours in the realm with more certainty.  

     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. 

     zoom.pl
       Allows for the expansion of posts into another window for 
       easier modification and spell checking.

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 PostgreSQL.  This is needed 
       in order to use the database system with Ethereal which is 
       a requirement. 

     convert.pl
       This is a primitive tool that can be used in the migration of
       SQL from MySQL databases to Postgres.  It is used as a pipe
       from a process to generally a file.

     erealms.pl 
       Command line tools for Ethereal Realms itself. 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.

     release.pl
       This allows people to generate SQL necessary for releases
       of the code.  THis serves little use with normal operations.

     rewrite.pl
       This is especially useful for those that cannot move the
       libraries into a system search position.   Once the CHANGE
       values within the file are adapted to match the needs of
       the administrator, the script will adapt the files to use
       the proper instance of perl and find the appropriate
       modules.

     spel.pl
       Daemon which will interact with iSpell and allow the system
       to run the actual client side in accerealted mode.



gz

This will contain a series of files which can be used to populate the
system with a certain set of defaults.   These are generally not kept
up to date, but will serve as a staging area.

     css.tar.gz
       Example css code which will allow you to format the basics for
       the site.

     gummies.tar.gz
       All images needed to host a base set of gummies are in this
       archive.

     images.tar.gz
       Images used in the display of various pages for Ethereal
       Realms, allowing for simpler intergration if need be.

     help.tar.gz
       Documentation related for use of Ethereal Realms from the 
       users perspective. 

     js.tar.gz
       Base javascript used on the system.


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.

     Image.pm
       Allows the manipulation of image.   This is basically a
       wrapper around Image::Magick.

     Login.pm 
       Simple authentication module, as to make the scripts easier 
       to deal with. 

     Option.pm
       Option handling module.  Meaning options that are specific on
       a straight line.

     Mail.pm
       Mail handling module, which allows for the standardization and
       seperation of the mailing process from the scripts.

     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.

     Pull.pm
       Module used to retrieve posts for users and administrative
       users.

     Spel.pm
       Spell checking module, which will work in conjuction with the
       spell checking daemon.    The typo in the name is done on
       purpose.

     Stamp.pm
       Timestamp handling module used exclusively with posting.

     Table.pm 
       Default table creation, used extensively in the scripts. 
       Really cuts down on code and increases maintainability. 

     Template.pm
       Makes formatting easier by using pre-defined templates.  This
       is core in the creation of the Gallery.

     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::Magick
          Imagine manipulation library, replacement for Image::Size
          other then legacy use.

     Image::Size 
          Used to determine the size of retrieved image

     LWP::UserAgent
          Used in the retrieval of images for the module above. 

     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 Digest::MD5
 cpan> install Image::Magick
 cpan> install Image::Size
 cpan> install LWP::UserAgent
 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 ./eRealms 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/eRealms/ (Linux RedHat 6.0) or
/usr/local/libdata/perl5/site_perl/eRealms/ (OpenBSD 2.7-3.4) for 
which the Webchat directory is to complete the names of the 
modules which are called eRealms::NAME.

NOTE:  If the scripts use the wrong instance of Perl or if you cannot
       move the modules into a searched path.   Look at the 
       ./commandline/rewrite.pl file for help.

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 other then the database
dumps themselves:  Database.pm

Lines 85 to 88 of eRealms::Database 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 back end. 

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

NOTE:  Ethereal Realms 3.0.0 was final release of the functions under
       function under MySQL.  Future versions have been optimized for
       operation under PostgreSQL and can be found at the following
       link: http://www.postgresql.org 
