SFEHangman Copyright 2004, Kristina Pfaff-Harris 
(http://tesol.net/scripts/)

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=

Contents of this file:

		Program Summary
	        Known Problems with SFEHangman
		Copyright & Licensing Information
		Legal Notice & Disclaimer
		Getting Started with SFEHangman
		Notes about Non-English Languages
		Setting up Files, Directories, and Permissions
		What to Do About Problems
		Other Scripts

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=


Program Summary:

SFEHangman lets you set up a fun little Hangman game on your website.
You can add your own wordlists to the program, and even add users
if you want to let others add their own wordlists. There are two
modes: "easy" and "hard." The only difference is, with "easy," you
get 11 guesses (the hangman guy's eyes, nose, and mouth are filled
in) while with "hard," you only get 7 guesses (the hangman's head
pops up in one blow).

Another fun way to waste time while working on some word skills.
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Known problems with SFEHangman:


Well, it's a new program so I don't know of any problems yet. That's 
not to say there aren't any -- please report bugs!

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=

Licensing & Copyright Information:

The Licensing terms and conditions are listed within the sfehangman.cgi
program itself.  This program is Copyright 2004, Kristina L. Pfaff-Harris.
All rights reserved.  You may use this program free of charge provided you
agree to the License agreement contained within the program.


=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=

Legal Notice & Disclaimer:

This program is offered as-is and no warranty is given, either express or 
implied.  By downloading, modifying, copying, viewing, or using this 
program, you agree that neither the author of this program nor the 
owners or administrators of the site from which you downloaded this 
program are liable for any breach of security, damage or loss caused 
directly or indirectly by the use of this program, and that any such 
breaches, damage or loss is the sole responsibility of the person who 
downloads, modifies, copies, views, or uses this program.

The author has attempted to make this program as bug-free and secure as 
possible, but there is always the possibility of something being 
overlooked, hence the author disclaims any responsibility for problems 
incurred in the use of this program.

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=

Getting Started with SFEHangman:

This assumes that you have permission to execute cgi programs on your
server, and that you know where the programs have to go.  Sometimes,
a web server is set up so that all cgi programs must be in a single 
directory (usually /cgi-bin).  If you don't know whether or not you
have permission to do this, or if you don't know where the programs
must go, ask the technical support people for your website.

You'll need to modify sfehangman.cgi slightly for use on your own site.
Open this file in a plain text editor such as Notepad, BBEdit, Pico,
etc. You may also use an editor such as Microsoft Word or Wordpad, but
if you do, make SURE to save the file as plain text, or it will break.

sfehangman.cgi:

		There are a few places in this file that you will
		need to change.  All of the instructions for changing
		them are located in the file itself and marked with
		**CHANGE** so that you can find them easily.  Please
		be very careful when you make your changes.  If you
		accidentally leave out a " or a ; or forget to put
		\ (backslashes) in the right place, the program 
		will not run.  If you have problems after you make
		your changes, please check very carefully the changes
		you've made.


Once you've made these changes, you're ready to start uploading stuff
to your website. This is how I suggest you install the script.

 1. Make a directory on your website called "hangman-images". Chmod
 it 755. This should be somewhere on your main website, or 
 at least, probably not in your cgi-bin.

 2. Upload all the .gif files that came with the program into
 that directory. Make sure all the .gif files are chmod 644.
 
 3. In your cgi-bin, make a directory called "hangman-wordlists."

 4. Chmod hangman-wordlists 777, and upload the .txt files from
 the hangman-wordlists folder into there. Chmod those text files 766.

 6. Upload the hangman_users.txt file to your cgi-bin, and chmod it 766.

 3. Upload sfehangman.cgi to your cgi-bin (or whatever place you need to
 upload CGI scripts in order for them to be able to run). Chmod it 755.

Now you're ready to begin playing hangman! To start playing,
just bring up a web browser and type:

  http://www.yoursite.com/sfehangman.cgi

Where "www.yoursite.com/sfehangman.cgi" means the actual web address
of where your sfehangman.cgi program is. If all has gone well, it
will show you the game screen, and you're good to go!

To get to the admin interface to add users or add/delete word lists,
pull up:

 
  http://www.yoursite.com/sfehangman.cgi?FA=Admin

To log in, use what you put in $admin_username in the script as the username
and use what you put in $admin_password in the script as the password.
You should be able to start using it right away!

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Notes about Non-English Languages

The program only supports non-English characters for the various languages
in a certain way. Specifically, if you can type those special characters
into the form using a combination of ALT and a number under Windows
(for example, Alt-0223 for "ß" -- That is supposed to be the German
character that looks like "B" and sounds like "s"). I have absolutely
no idea whether this will work on other operating systems or even how
you would do it on other operating systems. The non-English language
support was built at the request of an American teacher of French who
was the one who told me how to make these characters in the first place.

So, basically, if you can tell me whether or not it works for you, and
what DOES work for you, that would be great! However, non-English
character support should be considered experimental, so don't put too
much store by it.

Okay, you have been warned. :-)

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Setting up Files, Directories, and Permissions

SFEHangman needs to be able to create and modify files on your server.
One of the main problems usually encountered in setting up SFEHangman
is figuring out what the "full system path to your files" is supposed 
to be.

Here's what I suggest.  Usually, user accounts have a folder or directory
structure something like this:

 /home/users/yourname/public_html

or

 /home/users/yourname/WWW

Or something like that. 

(IMPORTANT: If you are on a Windows-type system (Windows 95, 98, NT) then 
the folder or directory structure will be something like "C:/users/yourname" -- 
In other words, it's pretty much the same but must start with the drive 
letter and a colon, rather than a "/". ) The "/home/users/yourname" part 
is known as your "home directory" and the "public_html" or "WWW" part is 
known as your "Document Root" or "web root".  Basically, people on the web can
see things in your web root, but they can't see things in just your
base home directory because it is "outside" your web root.

Please note that when I say "/home/users/yourname" I am speaking of
your "home directory" as it is known to the tech folks.  If you ask
your tech support people "What is the full system path to my home
directory?" then they should be able to tell you.  Sometimes this might
be something like "/var/opt/web/data/yourlogin" or something totally
different.  You've got to get this information from the people who
run the server where your website is.  

Now, on some web servers, all of your files are in your web root, and
there's no way to get out of it.  If this is the case, there may be hope.
Sometimes, your cgi-bin directory (if you have one) will refuse to show
the contents of files to people unless they're actually CGI scripts. If
this is the case, find your cgi-bin directory, and make your folders in
there.  In sfehangman.cgi, where it asks you to set "$path_to_wordlists", 
make it:

 $path_to_wordlists = "/path/to/your/cgi-bin/hangman-wordlists";

All in all, it really doesn't matter where you put your directories for
the SFEHangman files.  However, it must be writeable by the web server,
so this is often the way you have to do it.  Note that *nothing* on the
web is truly secure, so please take this with a grain of salt.  Someone
who is determined to get at the files probably can -- this will
just make it a tiny bit harder. Not that it matters much, because, after
all, this game is for fun only, right? :-)

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
What to Do About Problems:

A few notes:  If bringing up the sfehangman.cgi in your browser gives you 
an error (especially "Internal Server Error"), here are a few things to
check:
 
 1. Did you ftp the file in ascii mode?  You must ftp cgi programs in
 perl in ascii mode or they won't work.

 2. Did you change the permissions of the sfehangman.cgi program to
 be 755 (On some programs you need to click "read" and "execute" for
 the file to do the same thing.)?

 3. Is the path to perl with the #! on the very, very first line of 
 the file?  Sometimes this is tricky to tell, but there cannot be
 even a single blank line before #!/usr/bin/perl and the top of the
 file or it won't work.

 4. In the sfehangman.cgi program, did you leave out a " or a ;, or
 did you use "" when it says to use ''?

 5. Did you check the FAQ at http://tesol.net/scripts/FAQ/ for the
 most common problems? Your issue may already be covered there!

IMPORTANT:  If you contact me with a problem about this program, you
            MUST give me as much information as possible.  Please 
            include:

            The name of this program.  (I have several programs on this
            website, so if you email me saying "The program doesn't work"
            I won't know what you're talking about.)

            The version of this program. (This is SFEHangman version 1.0).

            The error message you got.

            The location of where you have set up the script on your
	    website so I can take a look at it.

Please try to check the FAQ (http://tesol.net/scripts/FAQ/) first and try
to see if you can figure out what's going wrong. If none of that helps you,
and you just can't get it running, please email me with as much detail
as possible about what's going wrong. I'm really happy to help, but if
you don't give me enough information, I cannot help you. If you call a
mechanic and say "My car doesn't work," or you call a doctor and say "I'm
injured," they're not going to be able to do much for you until you 
describe the problem. Same for CGI scripts. :-)

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=

Other Scripts:

If you like this program, try some of the other CGI
scripts available at Kristina's Scripts for Educators:

        http://www.tesol.net/scripts/

Currently available are:

AddrBook:          A simple web-based address book
AffordaBilly:      Loan payment affordability calculator: how big a loan can you afford?
AutoCGIMail:       Create your own custom email forms and scripts online!
CGI-Subscribe:     An email mailing list manager
Chat-N-Time:       Real-time web-based chat
CrosswordMaker:    A tool to create and grade HTML crossword puzzles
GradeORama:    	   Online gradebook server
HeadCount:         Simple headcount/attendance program.
MakeBook:          A guestbook/ongoing story program.
PayBackTime:       Calculator for how long it will take to pay off a debt or loan.
QAMaker:           Online FAQ/Question & Answer list generator
Quadratic-O-Matic: A simple quadratic equation solver
QuizTest:          Offer multiple-choice/true-false quizzes
RandomQuiz:        Generates quizzes with randomly selected questions
RemindMe:          An email auto-reminder service
SFEBanner:     	   Simple banner, quote, image rotator.
SFEBlackJack:      Simple online video BlackJack game
SFEPoker:          Simple online video Poker game
SFESurvey:         Another survey/quiz generator.
SFEWordSearch:     Generate printable wordsearch puzzles
SillySearch:       Let people search for pages on your website
SillyCount:        Let's you create a web-page counter.
SillySite:         A simple web-page creation program
VeryInteresting:   Loan Interest calculator and amortization table generator
VocabSearch:       Create and search a list of vocabulary words
Votesie:           Online voting booth/Poll generator
Web-B-Mail:  	   Private, web-only email-like system with pictures.
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Thanks for using SFEHangman!
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=