Readme file for ADVGUEST AND TEMPLGUEST, version 3

(I wrote this for advguest, so if you use templguest, simply substitute 
templguest every time you see advguest)

OVERVIEW
Advanced guestbook and Template guestbook formerly were two different scripts. Well,
they were kinda the same script with a different feature set. So now they're the
same script, because they were too darned close to being redundant.

I wrote the original advguest.cgi (advanced guestbook) because I didn't see any
features-packed guestbooks out there for free. I then wrote templguest (template
guestbook) because it was TOO STINKING HARD to code the correct html into the
body of the script itself, and I figured many people would have problems with it.

So I combined the two scripts - a features-packed guestbook that uses an html template
that you design to determine how your guestbook entries look.

Here are some of my guestbook's features:
	
	*	Cussword catching. No profanity filter is perfect, but mine comes close. I
		formerly borrowed a filter from someone else's script, but I wanted to write
		my own, because I wanted it to do everything I wanted it to do. My cussword
		catcher is flexible in that it catches words that are spelled unusually (such
		as with a space between each letter). It also checks for all variants of a word
		within reason.
	*	IP blocking. Because some people get brave when they sit behind a computer monitor
		we had to come up with a way to keep them from flaming you. My script allows you
		to put their IP address (which it reports to you in the e-mail report you get) in
		a list, and from that point forward, the script keeps them from using your guestbook.
	*	E-mail tracking. Many people like to build mailing lists of people that use their
		guestbook. I'm not one of them, but I figure you may be. My guestbook keeps a list
		of the e-mail addresses of those who sign it, along with their name, in a pipe-
		delimited list suitable for later use with my bulk e-mail program.
	*	E-mail syntax checking. Again, no e-mail address checker will ever be perfect, but
		this one at least makes the user enter a good fake. If they enter a non-address, the
		script will make them return and enter a real address.
	*	Spam confound. Though I don't personally use it, I included the ability for you to
		configure your guestbook to keep spam robots from harvesting your e-mail addresses
		by changing the @ symbol to something else (currently (at)). They hate that.
	*	HTML blocking. Nothing is more annoying than someone signing the guestbook and putting
		a link to some image somewhere else, or worse, including poorly coded html that screws
		up the rest of your guestbook. My script allows you to keep them from doing that.
	*	Database functionality. Though it's not a true database, it's close enough. My guestbook
		runs from a text file that keeps all your users' information in a pipe-delimited
		database format. This allows the flexibility to display only n entries per page (currently
		10), making load time a lot faster when viewing the guestbook. This also saves server
		hard drive space, because you're not storing html coding for each guestbook entry - that's
		written on the fly when the page is called. You'd be shocked how much space that saves.
		Really.
	*	One script does it all! No need to create a separate html page to call the guestbook.
		Instead, you just call "advguest.cgi" and the script displays the page for your users
		to enter their information. Similarly, if users want to view the page, all they do is
		call "advguest.cgi?view" and voila, they're viewing the first page of entries. It's
		extremely simple.
	* 	Other stuff that doesn't warrant its own bullet. My script checks to ensure your email
		list doesn't get duplicate names. It displays links for remaining guestbook entries at
		the bottom of the page. It receives both POST and GET input. It has extensive on-screen
		error reporting instead of arcane server error log reporting. It sends the user a "thank
		you" e-mail after they've signed, and sends you an e-mail notifying you that someone has
		signed your guestbook. It keeps smart alecks from typing in a long line of characters with
		no spaces in an attempt to make your guestbook look stupid. Oh, gee, there's so much I
		just don't have enough room to include it all...

WARNINGS:
	This guestbook is called "advanced" for a reason. It's not advanced in the sense that you
	need to know Perl programming to use it - what would be the point of that? No, it's 
	advanced in the sense that there are a ton of variables to configure, and they must be
	configured correctly, or the script won't work right. You should pay meticulous attention
	to the instructions below, or you'll be frustrated when the script won't work.

MAKING IT WORK.

1. CHANGING VARIABLES
	As simple as the script is, there are still some variables to change within the
	script itself.

 	$link
 	This is the URL to your home page. For instance, my home page is located at
 	http://www.conservatives.net/atheist/scripts/
 	so that's what I put in the $link value.
 	
 	$mailfile
 	This is the blank text file that will contain the mailing list this script compiles
 	as users enter their names and e-mail addresses. You should create a completely blank
 	ASCII text file, upload it to your server and set the permissions for world read/write.
 	Then, you should put the file's location in the $mailfile variable. This is a UNIX directory,
 	not a url. For instance, on my server, the file is at
 	/usr/home/leif/public_html/conservatives/atheist/scripts/bulk/testlist.txt
 	Note that the address begins with a slash, and contains a directory, not a url. 
 	*** IF YOU DON'T KNOW WHAT I'M TALKING ABOUT, TALK TO YOUR SYSTEM ADMINISTRATOR. Ask her 
 		write the address to your directory in the server. Many times, you can also surmise
 		the directory from looking at the directory location in your FTP program.
 		DO NOT e-mail me and ask me what your directory is. I don't know.
 	
 	$bookfile
 	This is the same as above, but it is a blank text file that will become your guestbook.
 	Do the same: create a blank text file, upload it, set its permissions to world read/write
 	and put its location in the $bookfile variable.
 	
 	$newform
 	This is the URL that allows the script to find itself. It is NOT a UNIX directory, it is
 	a URL, just like you would type into the location bar of your web browser to go to a page.
 	It should be something like mine: http://www.conservatives.net/atheist/scripts/advguest.cgi
 	
 	$mailprog
	This is the location of your "sendmail" program. Most Web servers have them. This is NOT
	your POP mail or your SMTP mail. It is a program resident on Web servers that allows
	the web server to send e-mail. If you don't know where your sendmail program is (and if
	you think this value should have an @ in it, this means YOU), CALL YOUR SERVER'S ADMINISTRATOR
	AND ASK WHERE THE SENDMAIL PROGRAM IS.
	
	$themmail
	This variable's default value is 1. That means the script will send a "thank you" e-mail
	to the user once they have signed your guestbook. If you DO NOT want the script to send
	them a "thank you" e-mail, set this value to 0.
	
	$myemail
	If $themmail is set to 1, you MUST put an e-mail address in the $myemail variable. It is
	the e-mail address that will appear in the "From" portion of the "thank you" e-mail the
	user receives after signing your guestbook. Ideally, this should be YOUR e-mail address.
	***	WARNING, WILL ROBINSON!!! YOU MUST include a backslash (\) before the @ symbol when
		you code your e-mail address into this variable, or Perl will choke and puke. For 
		instance, my e-mail address is scripts@conservatives.net. But when I put my e-mail
		address into the $myemail variable, I would write it like this:
		scripts\@conservatives.net
	
	$memail
	This variable's default value is 0. That means the script will NOT send you an e-mail
	telling you when someone has signed your guestbook. I set it to 0 by default because 
	literally hundreds of people sign my guestbook, and I got tired of my e-mail box being full.
	If you want to receive an e-mail when someone signs your guestbook, set $memail to 1.
	
	$from_mail
	This technically should be the EXACT same address as the $myemail address. I put a different
	variable for it in case you want the "from" address to have a different address than your own.
	I probably should just ditch this extra variable, but I'm too lazy.
	
	$permit_html
	This variable's default value is "no". That means if the user codes html into her entry,
	the script will replace her html coding with ASCII equivalents, which makes her look dumb
	for trying to put html into her guestbook entry. If you don't mind people coding html into
	your guestbook, set this variable's value to "yes".
	
	$MailMessage
	This is the message that will appear in the body of the "thank you" e-mail that will be sent
	to the user if the "$themmail" value is set to 1. You can (and should) modify this value, but
	be careful. If you use two lines of text (as I have done), be sure to follow the same convention
	I have used. Namely, each line must end with a quotation mark, and each new line must begin
	with a period, a space and a new quotation mark. The final line must end with a newline character
	(\n), a quotation mark and a semicolon (;) If you don't follow these conventions, the script
	will choke, and you won't know why.
	
	@FoundByList
	My guestbook has a menu that allows the user to select an option to tell you how she got to
	your site. This variable is where you input the options that will be displayed to the user.
	You can add options or subtract them, but again, be careful. Each item must be preceded by
	a single quote mark and followed by a single quote mark. There must be a comma between each
	item on the list (outside the quote marks). The final item on the list must be followed by
	a closing parenthesis. If you follow the style I have set in the script, you shouldn't have
	too many problems.
	
	$SpamConfound
	This tells the script to replace the @ sign in e-mail addresses with "(at)" to confound
	e-mail address-harvesting spam robots. It makes the e-mail addresses look funky, though, so I 
	set the default value to "no", which means the script will display e-mail addresses in the
	normal way. If you truly want to replace @ with (at), set the value of this variable to "yes".
	
	@bannedlist
	This is a list of IP addresses that cannot use your script. I put a made-up IP address in the
	list to give you an idea how it works. As with the @FoundByList above, each item must be surrounded
	by single quote marks, and each must be separated by a comma outside the quote marks. If someone
	flames your guestbook, add their IP address to this list, and they won't be able to sign the 
	guestbook again. A word to the wise, however: Many IP addresses are assigned when people log
	into the Internet, so the crafty user may not be banned the first time you try. But if you 
	diligently keep adding IP numbers as you are flamed, you will eventually get them, because
	each ISP only has so many IP numbers available.
	
	$template
	This is the UNIX directory to find your template file (see my above note about UNIX directories).
	The template file is what tells the script how to display your guestbook entries, and it is
	explained below in detail.
	
	$Hed{T}
	This is the headline that will appear both in the title bar of the browser window when
	someone views your guestbook and on the guestbook page itself.
	
	$Hed{Bg}
	This is the background color for your guestbook. I generally try to enter English values
	into this variable, because it's easier (i.e., "white" "black"). However, if you want to enter
	a hexidecimal value (like #FFFFFF for "white"),then be sure to include a backslash (\) before
	the # sign: $Hed{Bg} = "\#FFFFFF";
	***	HINT: If you want a background image instead of a background color, change the $Hed{Bg} itself
		to $Hed{Bk}. Thus, if your background image was called "background.gif", you would code the
		following:
		$Hed{Bk} = "background.gif";
		
	$Hed{Font}
	This is the font color to display on the page. See the section on background color to learn
	about writing hexidecimal values here instead of English color names.
	
	$Hed{FontFace}
	This is a list of fonts you want the page to look for before displaying the browser's default
	font. The font faces I list by default in the script are sans serif fonts that are pretty common.
	
	$PageLinkColor
	This is the color that links on the page will display. See above for hexidecimal instructions.
	
	$HeaderFile
	If you use a virtual include header on your site (as I do on mine), this is where you put its
	location. If you don't, leave this value blank and the script will do without it.
	
	$FooterFile
	Same as above.
	
	require 'web-lib.pl'
	This program requires my "web-lib.pl" script library. You must download it
	(http://www.conservatives.net/atheist/scripts/index.html?web-lib)
	and install it in the same directory as you install the script. Set its permissions the same
	as you set the permissions for the script (see below).


YOU'RE DONE WITH CONFIGURATION! Pat yourself on the back and get some espresso.

2. HTML configuration.
The only html configuration you have to do with this guestbook is in the template itself.
Here's how to set up the template.
	The template works like this: Each entry on the guestbook is displayed as the script
	pulls its information from your database (see $bookfile above). The script then goes
	to the template file to see what HTML stuff to encase the guestbook entry in.
	On my example template (available at http://www.conservatives.net/atheist/scripts/template)
	I use tables to encase my guestbook entries in the purple stuff you see on my site.
	But you, by no means, are restricted to using tables. You can do whatever you want.

	The only things you have to include are the following:
	<date> 			(this displays the date)
	<name> 			(this displays the user's name)
	<emailaddress>	(displays their e-mail address)
	<city>			(their city)
	<state>			(their state)
	<country>		(their country)
	<foundyou>		(displays how they found your site)
	<comments>		(displays their comments)
	
	And really, I lied. You don't even have to include all of those. Include whatever you
	want, and the script will display what you include. It's so simple, it's scary.
	
	For instance, say I just wanted a simple (non-tables) guestbook that displayed
	all the above information. I could do it like this:
	Name: <name><br>
	E-mail: <a href=mailto:<emailaddress>><emailaddress></a><br>
	City: <city> State: <state> Country: <country><br>
	Found you by: <foundyou><br>
	Date signed: <date><br>
	Comments: <comments><hr>
	
	If that's what my template file looked like, my guestbook would display the following
	when it read my entry:

	Name: Leif Wright
	E-mail: <a href=mailto:scripts@conservatives.net>scripts@conservatives.net</a>
	City: Muskogee State: OK Country: USA
	Found you by: Surfed on in
	Date signed: Sunday, May 7, 2000
	Comments: What a great site you've got here. You've obviously got good taste in scripts.<hr>

	
        
3. Setting the permissions
	For a script to work on a web server, the user must have permission to use the
	script. The way you give them permission is to tell the server who can access the
	file. This can be done through your FTP program.
	Once you've uploaded the file, select it on the remote server by clicking once
	on its icon. You should have a menu item that allows you to set or modify
	permissions. Set the permissions as follows:
	Owner:    read/write/execute
	Group:    read/execute
	Everyone: read/execute
	If you are using Telnet, use this command: chmod a+x advguest.cgi
	
	Next, you must set the permissions for the bookfile file. Permissions for 
	that file must be:
	Owner:    read/write/execute
	Group:    read/write/execute
	Everyone: read/write/execute
	If you are using Telnet, use this command: chmod a+w bookfile.txt 

4. Getting everything online
	Upload the files to your server, set the permissions and you're ready to rip!


