Fortune Cookie

                            BASIC INFORMATION

Name: Selena Sol's Fortune Cookie
Version: 3.0
Last Modified: 08-14-96

                               DESCRIPTION

This fortune cookie script will go through a data file of "fortunes"
choose an admin defined number of them at random and display them on the
web.  For myself, I prefer to use Netscape frames to display the multiple,
automatically reloading fortunes in one frame and an HTML page in another,
but the script could easily be modifiable to only show one fortune at a
time without frames.  The script may also be configured to choose from a
variety of data files.

                          COPYRIGHT INFORMATION

This application was written by Selena Sol (selena@eff.org,
http://www.eff.org/~erict) having been inspired by countless other Perl
authors.  Feel free to copy, cite, reference, sample, borrow, resell or
plagiarize the contents.  However, if you don't mind, please let me know
where it goes so that I can at least watch and take part in the
development of the memes. Information wants to be free, support public
domain freware.  Donations are appreciated and will be spent on further
upgrades and other public domain scripts.

Finally, PLEASE SEND WORKING URL's to selena@eff.org.  I maintain a list
of implementations around the world.

				 SUPPORT

This script comes with no gaurentees or warranties.  I am not a
programming professional.  I am a web-hobbiest and my scripts are
continually evolving as I learn more. Don't expect the scripts to be
perfect. 

Bug reports are greatly appreciated but installation support is
extremely discouraged. I have attempted to include as much information as
I could think of in this README and in the Customization and Installation
FAQ available at http://www.eff.org/~erict/Scripts/.  Please try ALL
available sources of information BEFORE you email me.  But if you must,
make sure to include the following bits of information (I may not respond
to your email if you do not answer ALL of the following questions):

1. What type of Web server are you running?
2. What type of Operating System is the Web server running on?

3. What is the "exact" error message from the Web?
4. What is the "exact" error message in your web server's error log?
5. What is the "exact" error message you receive when running the script
       from the command line.

6. Are you running this script on an ISP?  If so, what is the email
       address of the Sysadmin there?
7. Are you using a virtual server setup?  If so, what is the root path set
       in your Web server's environment?

8. In which directory is the Perl interpreter located?
9. In which directory is sendmail located (if you are using a script which
       demands use of sendmail)

Again, I MAY NOT ANSWER YOUR QUESTION unless you have answered all nine of
these questions.

                BASIC INSTALLATION (DOWNLOADING THE SCRIPT)

It is recommended that you point your Web browser to "Selena Sol's Script
Archive" to get the latest version of this script.  The Script Archive is
located at the following URL:

                    http://www.eff.org/~erict/Scripts/

From the "Script Archive" frontpage follow the hyperlinks to the detailed
page dedicated to this script.  Then click on the hyperlink "Download the
scripts as a single tar file".

                BASIC INSTALLATION (UNARCHIVING THE APPLICATION)

Once you have downloaded the TAR file (a single file containing all
associated files in their relative positions under the root directory),
transfer the TAR file to an executable directory on your web server and
untar them.  On UNIX systems, you may type the following at the
command line:

                          tar xvfp filename.tar

       (If you are using a non-UNIX Operating System, you may 
       download a TAR/UNTAR program by pointing your Web browser
       to http://www.shareware.com).

                 BASIC INSTALLATION (SETTING PERMISSIONS)

Your Web server must have permission to read, write or execute as needed.
Each sub-directory and file in the application has its own correct
permissions level associated with it.  Once you have unarchived (UNTAR)
the application, you must then set the correct permissions.  On UNIX
systems, you will use the "chmod" command.   The following table is a
quick guide to setting permissions for UNIX servers.

	PERMISSION	COMMAND
	rwxrwxrwx 	chmod 777 filename		
	rwxrwxr-x	chmod 775 filename
	rwxr-xr-x	chmod 755 filename
	rw-rw-r--	chmod 664 filename
	rw-r--r--	chmod 644 filename

	Note: Not setting your permissions correctly is the 
	NUMBER 1 reason why installations fail.  Take time to 
	get this right.

The actual permissions required for the subdirectories and files used by
this application are listed in the next section.

         BASIC INSTALLATION (FILES, DIRECTORIES, AND PERMISSIONS)

The TAR file will then expand into a root directory called Fortune_cookie.
Fortune_cookie will contain several sub-directories and several files.  
The diagram below depicts the directory structure as well as the
permissions which must be applied to the files and subdirectories used by
the application.

Fortune_cookie Root Directory (drwxr-xr-x)
   |____Fortune_files Sub-directory (drwxr-xr-x)
   |       |____cyberia.dat (-rw-r--r--)
   |       |____eff.dat (-rw-r--r--)
   |____cgi-lib.pl (-rw-r--r--)
   |____nph-fortunes.cgi (-rwxr-xr-x)
   |____nph-fortunes.html (-rw-r--r--)
   |____nph-fortunes.setup (-rw-r--r--)

Fortune_cookie - This is the application's root directory.  The Web server
    must have read and execute privileges

Fortune_files is a subdirectory containing the files which archive all of
    the possible fortunes which can be randomly chosen by the script to
    display.  In the distribution, there are two sample fortune files,
    cyberia.dat and eff.dat.  The subdirectory must be readable and
    executable by the web server and the files must be readable.

    name.dat is the format which this script uses for data files.
    Each data file contains a list of fortunes that are to be
    randomly searched.  In the distribution, I include both eff.dat
    and cyberia.dat, but you may certainly create your own.  These
    data files are in a specific format which is not particularly
    confusing, but the format must be followed exactly.

    Specifically, each fortune must be separated by two % signs
    and a % sign myst be the last line of the file.
    Thus, your new data file might be...

    Hello
    %%
    Goodbye
    %%

    The script would then randomly choose either Hello or Goodbye.

cgi-lib.pl is a library file which is used to parse incoming POST
    or GET data.

nph-fortunes.cgi is the main application which choose the random fortunes.
    This file must be readable and executable by the web server.

nph-fortunes.html is a file containing the routines necessary to generate
    your personalized HTML headers and footers.  The file must be readable
    by the web server and contains two subroutines page_header and
    page_footer which you can edit to your own specifics so long as you
    only touch the HTML portion of the subroutine.

nph-fortunes.setup is the file which is used to define server specific
    variables and options.  It must be readable by the web server and
    defines the following variables:

    $number_of_fortunes_to_display is the number of fortunes to display
    before stopping.  My eff.dat file is pretty huge so we don't want this
    thing going on forever...too much server resources considering the
    browser will probably move on to another page.

    $default_data_file is the data file that this script should grab
    fortunes from if the user does not specify another one.

    $number_seconds_to_display is the number of seconds that the script
    should wait for the user to read the fortune before it loads another
    one.
    
    $fortune_file_directory is the location of the directory containing
    the fortune data files. 

    $location_of_cgi_lib is the location of cgi-lib.pl on your local
    server.

			   RUNNING THE SCRIPT

This script should be run by pointing your browser to nph-fortunes.cgi
For example, you might use a URL such as:

      http://www.foobar.com/cgi-bin/Fortune_cookie/nph-fortunes.cgi

Also, when you call a data file other than the "main one" you must call it
by appending information to the URL which calls the script.  The exact
form uses a variable called fortune_file and might look like

    http://www.foobar.com/nph-fortunes.cgi?fortune_file=foobar.dat

The script will then use foobar.dat as the data file.