#!/usr/local/bin/perl -T

###############################################################################
# 							USER_HELP.PL
# 
#	This script was written by Michael E. Schechter (mschechter@earthlink.net)
#	Last Modified:  18 NOV 98
#
#   You may copy this under the terms of the GNU General Public
#   License or the Artistic License which is distributed with
#   copies of Perl v5.x for UNIX.
#
#	Purpose: provides a supporting application for other Perl CGI scripts
#	to facilitate the use of online help to the users of said script.
#
#	Change the hardcoded location of cgi-lib.pl if you do not store it
# 	in a libs subdirectory beneath the location of this script.
###############################################################################

# Okay, let's get started.  First, we tell Perl to bypass the buffer, and then
# print out the http header so we can do some debugging from the web.  We then
# require the cgi-lib.pl library file (note the hard-coded location), and use
# it to parse our incoming form data.

$| = 1;
print "Content-type: text/html\n\n";
&CgiRequire("./libs/cgi-lib.pl");
&ReadParse(*form_data);

# This script must be called with a query string that contains the item
# "config_file."  This will be a subdirectory that will contain the setup
# file.  So, check to be sure that it is there, untaint it with a regular
# expression match, and require the help.setup file.  If we don't receive
# "config_file" in the query string, we will just use some default values.

if ($form_data{'config_file'} ne "") {
	$form_data{'config_file'} =~ /^(\w+\/?\w*)/o;
	&CgiRequire("./$1/help.setup");
} else {
	$help_name = 'Requested Help';
	$bodytag = '';
	$basefont_tag = '';
	$hi_txt = '"#000000"';
	$help_dir = "./";
}

# An absolute must value that is passed by the query string is "help_topic."
# This will be a number that is keyed to a numbered text file that contains
# the information for the help we are seeking.  Read this value in, untaint it
# with a regular expression match, and assign it to the $topic variable.  We will
# then start our HTML output by calling the header subroutine.

$form_data{'help_topic'} =~ /^(\d{1,2})/o;
$topic = $1;
&header("$help_name");

# Okay, if our help topic has been passed to us, we are going to open the file.
# If we can't open the file, we will use the CgiDie subroutine in cgi-lib.pl to
# print out a useful error message and die.  Otherwise, we will read through the
# file line by line.  The first line of the help file should start with the 
# string "SUBJECT->" which we will use to display our help subject.  So we scan
# for that on every pass.  If the line does not start with "SUBJECT->", we will
# just print it out as is.  Otherwise, we will call the help_subject subroutine
# to nicely format the subject on the page.  Note that since the first line of
# the text file for the help subject should have the "SUBJECT->" string in it,
# it will be at the top of the page.  We will print out the whole file, close it,
# then finish up the HTML page with contact information for the user.

if ($topic ne "") {
	open (HELPTEXT, "$help_dir$topic.txt") ||
	&CgiDie ("I am sorry, but I was unable to open the help text file you
			  have requested.  The value I have is $form_data{'help_topic'}.
			  Would you please check the path and the permissions.");
	while (<HELPTEXT>) {
		unless ($_ =~ /^SUBJECT->(.*)/i) {
			print $_;
		} else {
			&help_subject($1);
		}
	}
	close (HELPTEXT);
	print qq!
		<p><font size="1">
		For comments or questions, contact <a href="mailto:$admin_email?subject=Help with Help">
		System Administrator</a></font></body></html>!;
	exit;
} 

# If our help topic was not defined, we will print out an error message and die.

else {
	&help_subject("Incorrect Configuration");
	print qq!
		There has been a misconfiguration in the file that you accessed this help script from.
		No help topic was specified in the link.  Please contact the
		<a href="mailto:$admin_email?subject=Misconfiguration">System Administrator</a> and
		provide information on what page you accessed this help link from, so the problem may
		be corrected. Thank you.
		</body></html>!;
	exit;
}

###############################################################################
# Subroutine:  CgiRequire()
#
#   Parameters:
#		A list of files to require into this script.
#
#   Usage:
#		&CgiRequire( "file1", "file2", ... , "filen");
#
#   Output:
#		None, if all files successfully required.  Error message if
#		any file is not successfully required.
#
#	Comments:
# 		This subroutine will take a list of files, and check each one in turn
#		to exist and be set to readable by the script.  If the file is, it will
#		be "required" into this file.  If it is not, an error message will be
#		displayed, and the script exited.
###############################################################################

sub CgiRequire {
	my (@require_files) = @_;
	foreach $file (@require_files) {
		if (-e "$file" && -r "$file") {
			require "$file";
		} else {
			print "I'm sorry, I was not able to open $file.  Would you
				   please check to make sure that you gave me a valid filename
				   and that the permissions on $require_file are set to allow me
				   access?";
			exit;
		}
	}
}

###############################################################################
# Subroutine:  &header();
#
#   Parameters:
#		$title = A string to be used as the title for the HTML page being 
#				 generated.  This value is optional.
#
#	Usage:
#		&header( "My Title" );
#
#	Output:
#		A properly formatted head section for the HTML page being generated,
#		with the title passed used as the title for the page.  Also generates
#		the body tag and basefont tag if so specified in the .setup file.
###############################################################################

sub header {
	my ($title) = @_;
	if ($title eq "") {
		$title = "HELP";
	}
	print qq!
		<html><head><title>$title</title></head>
		<body$bodytag>
		$basefont_tag!;
}

###############################################################################
# Subroutine:  &help_subject();
#
#   Parameters:
#		$subject = A string to be used as the subject for the help topic being
#				   displayed.  This value is optional.
#
#	Usage:
#		&help_subject( "My Help Subject" );
#
#	Output:
#		A properly formatted H3 tag wrapping the passed subject.  The subject
#		line is formatted using the $hi_txt variable from the setup file.
###############################################################################

sub help_subject {
	my ($subject) = @_;
	if ($subject eq "") {
		$subject = "Your Requested Help";
	}
	print qq!
		<h3><font color=$hi_txt><center>$subject</center></font></h3><p>!;
}