Readme File for MAIL-A-FILE by CGI City (http://icthus.net/CGI-City)
Author/Programmer - Peter N. Go
Last Update - 03/08/99


----------
DISCLAIMER
----------
In no event will CGI City be liable to the user of this script or any third party for any 
damages, including any lost profits, lost savings or other incidental, consequential or 
special damages arising out of the operation of or inability to operate this script, even 
if user has been advised of the possibility of such damages. 


----------------------
WHAT IS 'MAIL-A-FILE'?
----------------------
MAIL-A-FILE is a web-based form-to-email program with file attachment features.
It is written in Perl. 


----------------------------
HOW DOES 'MAIL-A-FILE' WORK?
----------------------------
MAIL-A-FILE makes use of two libraries namely:

  CGI_LIB.PL - (c) by Simon Tneoh Chee-Boon
  Email: tneohcb@pc.jaring.my              
  URL:   http://www.tneoh.zoneit.com/perl/CGI_LIB/

  MAIL_LIB.PL (slightly revised version of MIME Lite.pm)
  MIME Lite originally developed and (c) by Eryq
  Email: eryq@enteract.com
  URL:   http://enteract.com/~eryq

CGI_LIB.pl is used to parse data (including the file attachment) from the web form.
MAIL_LIB.pl is used to generate the MIME email messages.


-----
FILES
-----
The compressed file that you get should include the following:

(a) mail_a_file.cgi - the script which takes the data fom the web form and processes them 
    to a MIME email message.

(b) CGI-LIB.pl - a Perl library/module that parses the data (including the file attachment) 
    from the web form.

(c) MAIL-LIB.pl - a Perl library/module that generates the MIME email messages.

(d) index.html - a sample HTML form which may be used to send the mail messages from the 
    web browser.

(e) readme.txt - this file.


------------
REQUIREMENTS
------------
In order for MAIL-A-FILE to be installed and run properly, the following are required:

1.  A web host server that runs a Unix operating system (eg: Linux).
2.  CGI-BIN access.
3.  A Perl interpreter properly configured and installed.
4.  Pizza and a tall glass of root beer (optional). 


-------------------------
INSTALLATION INSTRUCTIONS
-------------------------
1.  Use a text editor to modify the file named "mail_a_file.cgi".
    Edit only the variables within the portion marked like so:
    ##############################
    ##  ASSIGN THESE VARIABLES  ##
    ##############################
    Do not edit/modify anything beyond that line.


    Use a text editor to modify the file named "MAIL_LIB.pl".
    Look for the line (roughly the 10th line after the copyright info): 
	my $SENDMAIL = "/usr/sbin/sendmail -t -oi -oem";
    You may change this to correctly point to your server's path to the sendmail program.
    Otherwise, leave the file as-is without modifications.

2.  Have some of that pizza and root beer.

3.  Once you have finished modifying the file(s), you need to upload to your web host server.
    It is already assumed that your web host allows custom CGI scripts to be installed. To 
    upload, simply FTP the following files into your cgi-bin directory: 

     (a) mail_a_file.cgi
     (b) CGI_LIB.pl
     (c) MAIL_LIB.pl

    You can actually create another directory within your cgi-bin and upload the files there. 
    Just make sure that if you create a new directory, it is chmod to 755.

4.  Create a directory on your server to hold all uploaded files temporarily. This directory 
    must be given a chmod 777. The script deletes temp files in this directory that are
    older than 1 day so you don't have to worry about the directory getting filled up 
    unnecessarily.

5.  Using a text editor, modify the file named "index.html" to suit your own site's overall 
    appearance. Look for the <FORM METHOD="POST" ENCTYPE="multipart/form-data" ...> tag
    and change the ACTION="http://yourdomain.com/cgi-bin/mail_a_file.cgi" to point corrrectly 
    to where you installed the mail_a_file.cgi script. Change only the ACTION part and leave
    the others as-is.

6.  Upload via FTP this file to your web host server:

    (d) index.html

7.  Once all files have been uploaded, chmod the following files/directories accordingly:

    (a) mail_a_file.cgi ................ chmod 755
    (b) CGI_LIB.pl ..................... chmod 755
    (c) MAIL_LIB.pl .................... chmod 755
    (d) index.html ..................... leave as-is

    Here is a sample directory tree with the corresponding chmod you can pattern after:

    YOUR ROOT DIRECTORY
          |
          |____CGI-BIN directory (chmod 755)
          |       |
          |       |____(a) mail_a_file.cgi (chmod 755)
          |       |____(b) CGI_LIB.pl (chmod 755)
          |       |____(c) MAIL_LIB.pl (chmod 755)
          |
          |____HTML Sub-directory (where your HTML files might be located)
                  |
                  |____MAIL-A-FILE Sub-directory
                             |
                             |____(d) index.html 
                             |
                             |____Your Temp Sub-directory (chmod 777)

    IMPORTANT NOTES: 
    ----------------
    The above directory tree is only an example. You may create your own
    structure. Just make sure you chmod accordingly and that you specify the
    correct paths within the scipts to the appropriate directories.

    If there are no chmod values indicated, it means you need not do any
    chmod after uploading.

8.  Done with the installation. Have another slice of pizza.


------------------
RUNNING THE SCRIPT
------------------
From your web browser, type the URL to the "index.html" file. 
Example: http://yourdomain.com/index.html

Fill out the form and press the submit button. Things should be working properly.

By the way, too much pizza might not be good for you :)


----------
DISCLAIMER
----------
Again.

In no event will CGI City be liable to the user of this script or any third party for any 
damages, including any lost profits, lost savings or other incidental, consequential or 
special damages arising out of the operation of or inability to operate this script, even 
if user has been advised of the possibility of such damages. 


------------------
REPORT ANY BUGS TO
------------------
CGI City - cgicity@icthus.net

or 

Peter N. Go (author)
peter@arachinc.com

Always include your registration number when communicating with us.







