photoview.pl help.txt file, version 1.51

Despite having a decent number of lines of code, there is really not much that NEEDS to be edited,
and there is not too much that can go wrong.

First, configure all the variables at the top of the program; these are the only things 
that need to be changed; the html that the program will output can be changed later, after
you have gotten the program up and running okay. 

This version (1.51) adds better error messages than the previous version (1.31), as well as 
using strict. Before you get the program set up, set $debuggy to '1', and then you will get 
very informative error messages, telling you exactly what went wrong, where.
===================================================================================
okay, this is an example of what the $text_file should look like:

(thumbnail)       (width)  (height) (fullsize pic) (width) (height) (Title)
with tabs between every field and newlines for each different image.
Remember: the thumbnails and full-sized images must all be in the same directory as the $text_file

bridesmaid-a.jpg	137	200	bridesmaid.jpg	588	861	The Bridesmaid
bridges-a.jpg	135	200	bridges.jpg	629	929	Bridge
cara-true-a.jpg	200	170	cara-true.jpg	623	529	Portrait of a soul
eddie_g-a.jpg	132	200	eddie_g.jpg	610	925	Eddie G.
ellen_bride-a.jpg	159	200	ellen_bride.jpg	743	932	The Lovely Bride
hand_in_dark-a.jpg	134	200	hand_in_dark.jpg	613	917	Holding On

=====================================================================================


**********************************************************************
here is some info on the important variables (others are well enough explained in the code):

$text_file = the name of the text file that contains the image size and title information; it 
must be in the same directory as the thumbnail and full-sized images

$absolut_directory = the absolute path to the base photo gallery directory. What I mean by base 
photo gallery directory is that all the photo gallery directories must be subdirectories within 
that directory (i.e.: my base is /data/domains/mikegoode.com/public_html/photo/gallery, and my 
galleries are subdirectories of /gallery/, such as /gallery/mike2/).

$program = the url of the program

$small_multiplier = 
$medium_mulitplier = 
$large_mulitplier = 
	--these set the decimal to multiply the full-sized image's size (in pixels) by to get the 
smaller images that the viewer subroutine can get. I recommend starting with the defaults, and 
changing them based upon the size pictures you use. 

************************************************************************

other things that you may want to change in the code:

1.  (does not apply in version 1.55 or later!!)

allowing titles longer than 4 words -- find the section of code that looks like this:

		@ga_title = split(/=/, $gallery_title);
		my($a1) = shift(@ga_title);
		my($a2) = shift(@ga_title);
		my($a3) = shift(@ga_title);
		my($a4) = shift(@ga_title);
		$gallery_title = "$a1 "  . "$a2 " . "$a3 " . "$a4";

add on as many more variables (ie, $a5, $a6, $a7) as you want title words, and then add them to the
 concatenation line (the last line) like this:

$gallery_title = "$a1 "  . "$a2 " . "$a3 " . "$a4 " . "$a5 " . "$a6 " . "$a7";

Make sure to include a space after the variabe name before the quotes, so that there will be spaces
 between the title words.

2.  customizing the html of the thumbnail gallery: to change the header or footer html, simply go 
to that section of the code (it is indicated in the code), and then simply input normal html where 
I indicate you should put it.

3.  customizing the ouput of the actual thumbnails: this will be a bit harder, and require some 
perl knowledge, but just go to the loop that prints out the thumbnail photos (you will notice it 
right before the line: "print "$gal_footer";"), and change the html there. however, you will need 
to include a backslash (\) before every quote (") or other special perl characters in the html

4.  customizing the output on the image viewer page. Simply change the html at the very bottom of 
the lines of code. However, as in #3, you must include backslashes before quotes (and unlike in 
point #2, where you can put just plain html).


********************************************************************************
The damn thing won't run!!!! Your script sucks!!!!!
********************************************************************************

okay, the script did not work right after you uploaded it, and you want to fix it; here is my guide
 for solving many common problems, and things you should check:

When program called, displays "you do not have permission to access /cgi-bin/ . . ." this means you
 need to chmod the program to world executeable

when the program is called, you get a server error saying "Internal Server Error" or some other 
mysterious and cryptic message. This means that the program is not 
working. The main reasons for this are: 
	1. incorrect $absolut_directory or $program in program, or incorrect url in link to 	
program. check these first, as they are easy to correct and very common errors.

	2. you changed the html or code and messed up the perl syntax. check the syntax (is there a
 	semi-colon at the end of every line?). It may be helpful to get a text editor that will 
	check your perl syntax (try www.carbon6.com for their perldev program for windows, which is 
	not too bad)
	
when the program is called, it displays broken picture links and like stuff: this probably 
indicates that the $text_file is set up wrong, so the wrong data is gettting into the wrong variables. 

when the program is called, it works fine, except there is one or more broken 
thumbnails and links at the end -- these are not actual pictures. If you have a newline after 
the last line in the $text_file, then the program will interpret it as another entry and try to display 
it, even though there is nothing there. simply delete the newline and do not use a return after the last line.

when the program is called, it gives you my error screen, saying that it cannot chdir to some 
directory. This means that in calling the program from the URL, you entered an invalid directory
or one that does not exist. The program must be called like this: 

http://www.yoururl.com/cgi-bin/photoview.pl?http://www.yoururl.com/photogallerydirectory/subdirectory&Directory=Title&gallery
important: do not include the trailing slash after the gallery subdirectory--just have the ampersand
immediately follow that.

when the program is called, it gives you my error screen, saying that it cannot open the $text_file.
You do not have the proper name of your $text_file in the program code, or you put your $text_file
in the wrong directory
************************************************************************************