#!/opt/local/bin/perl5.34

use strict;

use Spidy;

use File::Copy;
use File::Path;
use File::Basename;
use File::Find;

my $s = Spidy->new();
if( keys %{$s->{'args'}->{'templates'}} ) {
  my $dir = dirname( $INC{'Spidy.pm'} ) ."/Spidy/Templates";
  my $file_path = $s->{'args'}->{'file_path'} || '.';
  if( $s->{'args'}->{'templates'}->{'all'} ) {
    $s->{'args'}->{'templates'}->{'xml'} = 1;
    $s->{'args'}->{'templates'}->{'image'} = 1;
    $s->{'args'}->{'templates'}->{'group'} = 1;
  }
  
  mkpath($file_path) unless -e $file_path;
  if( $s->{'args'}->{'templates'}->{'xml'} ) {
    if( -e "$file_path/gallery.xml" ) {
      warn "$file_path/gallery.xml exists, will not overwrite!\n";
    } else {
      print "Creating $file_path/gallery.xml\n";
      copy( "$dir/gallery.xml", $file_path ) or 
        die "copy of $dir/gallery.xml to $file_path/. failed: $!";
    }
  }
  if( $s->{'args'}->{'templates'}->{'image'} ) {
    if( -e "$file_path/image.tmpl" ) {
      warn "$file_path/image.tmpl exists, will not overwrite!\n";
    } else {
      print "Creating $file_path/image.tmpl\n";
      copy( "$dir/image.tmpl", $file_path ) or 
        die "copy of $dir/image.tmpl to $file_path/. failed: $!";
    }
  }
  if( $s->{'args'}->{'templates'}->{'group'} ) {
    if( -e "$file_path/group.tmpl" ) {
      warn "$file_path/group.tmpl exists, will not overwrite!\n";
    } else {
      print "Creating $file_path/group.tmpl\n";
      copy( "$dir/group.tmpl", $file_path ) or 
        die "copy of $dir/group.tmpl to $file_path/. failed: $!";
    }
  }
  exit;
}

$s->show_sizes()    if $s->{'args'}->{'show_sizes'};
$s->drop()          if $s->{'args'}->{'drop_db'};
$s->create()        if $s->{'args'}->{'create_db'};
$s->insert()        if $s->{'args'}->{'load_db'};
$s->build_images()  if $s->{'args'}->{'images'};
$s->build_html()    if $s->{'args'}->{'html'};

if( $s->{'args'}->{'icons'} ) {
  my @icons;
  my  $dir = dirname( $INC{'Spidy.pm'} );
  find(  
    sub { 
      $File::Find::dir !~ /CVS/ 
        && /^.+\..+$/ 
        && push @icons, "$File::Find::dir/$_";
     },
    "$dir/Spidy/Icons"
  );
  
  my $file_path;
  if( $s->{'tree'} && $s->{'tree'}->{'file_path'} ) {
    $file_path = $s->{'tree'}->{'file_path'};
  } else {
    $file_path = $s->{'args'}->{'file_path'};
  }
  
  File::Path::mkpath("$file_path/icons", 1 , 0755 ) unless -d "$file_path/icons";
  
  # the sort is needed so the test results
  # are consistent.  Without it we cant guess the
  # order of icons that the find function found.  So
  # we order them here.
  foreach my $icon ( sort @icons) {
    my $file = $icon;
    $file =~ s/^.*\///;
    if( -e "$file_path/icons/$file" ) {
      warn( "icon already exists: $file\n" ) if $s->{'args'}->{'verbose'};
      next;
    }
    print "Creating $file_path/icons/$file\n";
    copy($icon, "$file_path/icons");
  }
}

=head1 NAME

spider - Command line interface to the Spider Eyeballs Image Gallery Creator perl modules

=head1 SYNOPSIS

 # create static html gallery with images stored in
 # one large directory
 spider --file gallery.xml \
        --filePath /home/httpd/htdocs/gallery \
        --inputImagePath /home/fiber/images

 # create static html gallery with images stored
 # next to the html files
 spider --file gallery.xml \
        --filePath /home/httpd/htdocs/gallery \
        --inputImagePath /home/fiber/images \
        --outputImagePathType 'relative'


 # modperl httpd.conf sample:
 <Directory /var/www/opensource >
   SetHandler perl-script
   PerlHandler Spidy::Registry
   PerlSetVar ConfigFile os.xml
   PerlSetVar InputImagePath /var/images/opensource
   PerlSetVar Sizes small,medium,original
 </Directory>

 # for modperl you still need to go to /var/www/opensource
 # and create the images:
 spider --file os.xml \
        --inputImagePath /var/images/opensource \
        --sizes small,medium \
        --nohtml

=head1 DESCRIPTION

B<spider> is a command line interface to the Spider Eyeballs Image Gallery Creator
perl modules.  It creates
an image gallery website that is easily navigated and very clean.  Each image 
can be viewed in various resolutions, and galleries can easily be browsed
with the automatically created thumbnail images.  The website content can be
customized by editing the input xml document, and further customizations can
be made by editing the input template pages.

Unfortunately there is no magic bullet that I have found to make image 
manipulation fast. So depending on your system hardware and the original
image sizes, this program can take several hours to create the images needed for
your website.  Creating just the pages is pretty quick though.  So once you 
have created the images, you can tweak the xml file or the html templates and
the website will be recreated quickly.  The site at 
http://www.spidereyeballs.com/os2000 took 1 hour, 1 minute and 26 seconds with
our hardware and very high-resolution images.  For a very good example of what
Spider eyeballs can do, check out http://www.spidereyeballs.com/os5

Recent enhancements have made it possible to run under modperl.  You can
use the spider tool to load a database with the config file contents and
then use that database under modperl, or you can just use the xml config
file and have modperl parse the xml when it needs to.  See the MODPERL
section for more details.

=head1 PROGRAM OPTIONS

Below is a description of the command line optins that can be given to 
the spider program.  

=head2 Options Table

 Name                  Value	        Default
 ----                  -----            -------
 GENERAL OPTIONS
 convert               path             search PATH
 congif                path             ./config
 file                  path             -none-
 help                  -none-           off
 html                  yes|no           yes
 icons                 yes|no           yes
 images                yes|no           yes
 test                  -none-           off
 verbose               -none-           off
  
 IMAGE OPTIONS
 forceImages           -none-           off
 graphicsBuilder       module
 gravity               direction        northwest
 inputImagePath        path             .
 outputImagePath       path             <filePath>/images
 outputImageType       file type        <same as input>
 outputImagePathType   fixed|relative   fixed
 sizes                 size list        all
 sizes                 -none-           off
 watermark             file name        -none-
 
 HTML OPTIONS
 baseUrl               URL              -none-
 bundleDownload        yes|no           no
 defaultSize           size             small
 filePath              path             .
 imageUrl              URL|path         images
 imageTmpl             path             <tmplPath>/image.tmpl
 groupTmpl             path             <tmplPath/group.tmpl
 tmplPath              path             <Spidy Inst>/Template
 bgColor               color            black  (#000000)
 fgColor               color            white  (#FFFFFF)
 vlinkColor            color            purple (#7E26CE)
 linkColor             color            blue   (#4A4AFF)
 inputFilePath         path             .
 parentUrl             URL              -none-
 
 TEMPLATE OPTIONS
 getImageTemplate     -none-            off
 getGroupTemplate     -none-            off
 getTemplates         -none-            off
 getXmlTemplate       -none-            off
 
 DATABASE OPTIONS (under early development)
 createDB             -none-            off
 loadDB               -none-            off
 dropDB               -none-            off
 warnSql              -none-            off
 server               hostname          -none-
 database             text              spider
 user                 text              -none-
 password             text              -none-
 type                 Pg|Mysql|Sybase   -none-
 port                 number            -none-
 
 MODPERL OPTIONS
 ConfigFile           path              -none-
 ImagePath            path              ./images
 InputImagePath       path              -none-
 Sizes                size list         all
 ParentUrl            url               -none
 GroupObject          perl module       Spidy::CGI::Group
 ImageObject          perl module       Spidy::CGI::Image
 GroupTemplateFile    path              <tmplPath>/group.tmpl
 ImageTemplateFile    path              <tmplPath>/image.tmpl
 BgColor              color             black (#000000)
 FgColor              color             white (#FFFFFF)
 DatabaseName         text              spider
 DatabaseUser         text              -none-
 DatabasePassword     text              -none-
 DatabaseType         Pg|Mysql|Sybase   -none-
 DatabaseServer       hostname          type specific
 DatabasePort         number            type specific
 WarningSql           yes|no            no

=head2 General Option Descriptions

=over 4

=item convert I<path>

If the 'convert' Image Magick program is not in one of the directories 
specified in your PATH environment variable, then you need to set this option.
The argument should be the full path to the 'convert' program.  This
program will be used to create the various sized images for the website.

=item config I<path>

The config option allows users to save B<spider> command options to a file
then reuse those options whenever spider is used.  So if a file "myconfig"
contains:

 --file gallery.xml
 --inputImagePath input_images
 --sizes small,medium
 --parentUrl http://www.spidereyeballs.com

Then to load spider with those options, just use C<spider --config myconfig>.
If you wish use all the options from myconfig, but say, only want size 'small', then
you can run C<spider --config myconfig --sizes small> and the command line
will override what is in the config file.  There is a default value of
"./config" so if you were to rename the "myconfig" file to "config", then all you
need to run is C<spider> or C<spider --sizes small> and all the options from
the "./config" file will automatically get used.

If you use --config with no argument it will not use any config files.   This is handy
if you have a 'config' file in the current directory but don't want it to be used with spider.

=item debug I<-none->

This is a boolean flag to produce debugging messages.  Basically it will
display a indented display of the xml document that was supplied with
option B<file>.  It will also product various other messages as the program
goes along.

=item file I<path>

This option is mandatory.  The argument should be the name of the
xml file describing the site.  See the B<Configureation File> section
below.

=item help I<-none->

Boolean flag, when set it will display the usage information for B<spider>.

=item html I<yes|no>

This flag determines whether or not the program will create the html files
for the website.  The default is 'yes'.

=item icons I<yes|no>

This flag determines if the program should copy the default icons to the
<filePath>/icons directory.  Set this to no if you want to want to use
your own icons, or you can just delete the icons after they move.  If the
icon already exists it will not be overwritten.

=item images I<yes|no>

This flag determines whether or not the program will create the images files
for the website.  The default is 'yes'.  Even if images is 'yes' it will not
overwrite the images if they alreay exist.  Use B<forceImages> to overwrite
existing images.

=item test I<-none->

Use this command to just make sure the xml file specified with the
B<file> option is a well-formed xml document.

=back

=head2 Image Option Descriptions

=over 4

=item forceImages I<-none->

Boolean flag to force image creation.  This flag is only necessary if you
have previously created the images, and you want to overwrite the existing
files.  The default is 'no', so B<spider> will not overwrite images if they
exist.

=item graphicsBuilder I<module>

Use this argument to change the tools used to generate the images. Currently
"ImageMagick", "Imager", and "PerlMagick" are supported.  "ImageMagick" is the
default (which uses the command line Image Magick utilities like 'convert').
"Imager" is a perl image generator where the output images take up less
memory than those generated with Image Magick, and it can be slightly faster.
"PerlMagick" is the perl interface for Image Magick.  The file sizes and quality
are nearly identical to those generated with Image Magick, but it can be up to
four times faster.

=item gravity I<direction>

This flag is passed to the Image Magick 'composite' utilty during creation
of B<watermark>s.  If --watermark is not used, then this option is useless.
The possible values for this are: center, north, northeast, east, southeast,
south, southwest, west, northwest.  The default value is 'northwest'.

=item inputImagePath I<path>

The argument to this option is the path to the original images to be used
in creating the site.  The images to use should be listed in the xml document
named with the B<file> option.  The default is '.', the current directory.

=item outputImagePath I<path>

The argument to this is the base path were all the images will be placed.  Each
image will be placed in a corresponding 'size' directory, so all the 'small'
images will be put in the 'small' directory.  If the B<outputImagePathType>
is 'fixed' or not defined, then the output images will be placed in the
outputImagePath and no subdirectories (other than then size name) will be
added to the directory path.  The default for this scenario is "B<filePath>/images".
If the B<outputImagePathType> is 'relative' then the
output image path will be relative for each image, depending on the input xml document.  If the image
is under a group named 'puppies', then the images will be put in
the directory <outputImagePath>/puppies/<size>/.  The default for this scenario is the same
as B<filePath>.  Also see B<imageUrl> and B<outputImagePathType> if you use this option.

=item outputImageType I<file type>

This option will allow you to force all of the output images to be a specified type,
no matter what type the input images are.  The input images can be anything that
the Image Magick 'convert' tool can handle (basically anything).  So you can leave your
input images as photoshop images, and just specify --outputImageType='jpg' to force
them all do be created and resized as JPEG images.  The default output image type is the same
as the input image.

=item outputImagePathType I<fixed|relative>

Specifies the output image path type.  If all the output images should be in the
B<outputImagePath> with no relation to the groups they fall under,
then the B<outputImagePathType> should be 'fixed'.  Basically 'fixed' means all the
output images will be placed in a single directory (per size).  If B<outputImagePathType>
is 'relative' then the output images will be put in the B<outputImagePath> but
also divided into subdirectories based on the group name.  The default is 'fixed'.

=item sizes I<size list>

With an argument, the sizes option forces B<spider> to only create images
of the specified sizes.  The argument should be a comma delimted list of size
names.  All the possible size names can be retireved using C<spider --sizes>, 
see above for details.  Ex:  '--sizes small,original'.

=item sizes I<-none->

If this paramater is not given any paramaters, then B<spider> does not create
any html or images, it simply reports the names of the various sizes that
B<spider> knows about.  Ex:

 prompt> spider --sizes
 +--------+-----+------+-------+------+---------+------+
 |name    |width|height|quality|padded|watermark|custom|
 +--------+-----+------+-------+------+---------+------+
 |thumb   |   60|    60|     80|yes   |no       |no    |
 |teeny   |  250|   200|     80|no    |yes      |no    |
 |small   |  400|   300|     80|no    |yes      |no    |
 |medium  |  500|   400|     80|no    |yes      |no    |
 |large   |  800|   600|     90|no    |yes      |no    |
 |xlarge  | 1300|  1000|     97|no    |yes      |no    |
 |original|    *|     *|     80|no    |no       |no    |
 +--------+-----+------+-------+------+---------+------+

After you know the possible sizes, then you can supply those sizes to the 
the B<sizes> option when creating images, and it will only create the images
for the specifed sizes.

If you have customized the sizes in the xml file (see the B<size> xml tag below), 
then it will report the customized sizes.  Just run spider so it will read in
the xml file, something like: 
C<spider --file gallery.xml --inputImagePath images --sizes>. 
And if your xml file looked something like:

 <gallery>
   <size name="thumb" max_width="100" max_height="100"/>
   <size name="itty-bitty" max_width="10" max_height="10" padded="1"/>
   <group>
     ...
   </group>
 </gallery>

Then the sizes table would look like:

 +----------+-----+------+-------+------+---------+------+
 |name      |width|height|quality|padded|watermark|custom|
 +----------+-----+------+-------+------+---------+------+
 |thumb     |  100|   100|     80|yes   |no       |yes   |
 |teeny     |  250|   200|     80|no    |yes      |no    |
 |small     |  400|   300|     80|no    |yes      |no    |
 |medium    |  500|   400|     80|no    |yes      |no    |
 |large     |  800|   600|     90|no    |yes      |no    |
 |xlarge    | 1300|  1000|     97|no    |yes      |no    |
 |original  |    *|     *|     80|no    |no       |no    |
 |itty-bitty|   10|    10|     80|yes   |no       |yes   |
 +----------+-----+------+-------+------+---------+------+

=item watermark I<text>

This option is used to specify the name of the image file which will 
be used as a watermark overlay on the original image during the creation
of the output images.  The orientation
of the watermark is determined by the B<gravity> option.  
Watermarks also will only be added to specify sizes.  It will
not be added to 'thumb' by default.  You can override this
behavior by customizing the sizes in your xml file ... see the B<sizes> option.  There
is no default watermark.

=back

=head2 Html Option Descriptions

=over 4

=item baseUrl I<URL>

If this argument is given, then the value will be placed in the
C<E<lt>BASE HREF="E<lt>baseUrlE<gt>"E<gt>> tag at the top of each
html page that is created.  

=item bundleDownload I<yes|no>

If this argument is yes, then a link located under the copyright information
on each page will be give to a .tar.gz and a .zip file.  These are pseudo compressed
files that will allow the user to download all the input images used under 
the current node.  The files created are not actually compressed files,
rather they are perl scripts which will dynamically compress and deliver
a stream of compressed data.  The only requirement for this to work
is that in your server configuration you must make the server treat .tar.gz and .zip files
as cgi scripts so the server will execute the file rather than just send it out.
This can be done in the apache httpd.conf file by adding C<AddHandler cgi-script .zip .gz>
to the Location or Directory block for the gallery.  The default is 'no'.  Also in order for
the scripts to successfully execute you will need Archive::Tar and Archive::Zip.

=item defaultSize I<size>

With this option you can override the default of linking the index.html
files to the smallIndex.html file.  The argument should be a valid
size name, one that is returned from 'spider --sizes'.

=item filePath I<path>

The argument to this option should be the path where all the html files will
be saved to.  This directory should be under the document root of your web
server.  The default is '.', the current directory.

=item imageUrl I<URL>

If you have used the B<outputImagePath> option, then you will need to set this 
option also.  The argument to to this option will be used in the html pages
to set the src tag for each image.  This is handy if you want to have your
images on one server, and your html files on another server. Or if you want to
store your images in a completey different directory that the B<filePath>.  If B<outputImagePathType>
is 'fixed' or not defined, then the default is 'images', otherwise the default
is the same as B<baseUrl>.

=item imageTmpl I<path>

The argument to this option should be the full path to the file that will be 
used as the template for all image pages. An image page is a page that the
actual non-thumbnail image is on (ie. it has no subdirectories of images).  The
default is <tmplPath>image.tmpl.

=item groupTmpl I<path>

The argument to this option should be the full path to the file that will be 
used as the template for all group pages. A group page is a page that has a
table of thumbnail images on it. (ie. it has only subdirectories of images).  
The default is <tmplPath>/group.tmpl.

=item tmplPath I<path>

This argument should be the directory where we can find the group.tmpl and
image.tmpl templates.  The default is the installation directory for the
Spidy perl modules.

=item bgColor I<color>

The backgroud color of all of the pages.  Default: black (#000000)

=item fgColor I<color>

The foreground (font) color for all the pages.  Default: white (#FFFFFF)

=item vlinkColor I<color>

The color of a link after is has been clicked on.  Default: purple (#7E26CE)

=item linkColor I<color>

The color of a before it has been clicked on.  Default: blue (#4A4AFF)

=item inputFilePath I<.>

The argument to this will be used for the directory path where to locate
the <comment> files.  If you specify the B<file> attribute in the
<comment> tag, then spider will look in B<inputFilePath> to find the file,
unless the B<file> value has an absolute path.

=item parentUrl I<URL>

Use this argument to specify the "Up One Level" link for the top
level group.  There is no default for this, so unless this option
is set, there will be no parent link for the top level group.

=back

=head2 Template Option Descriptions

Use these options to get a copy of default templates.

=over 4

=item getImageTemplate I<-none->

Use this flag to copy the default image template <image.tmpl> to the
directory specified by B<filePath>.

=item getGroupTemplate I<-none->

Use this flag to copy the default group template <group.tmpl> to the
directory specified by B<filePath>.

=item getTemplates I<-none->

Use this flag to copy all the templates to the directory specified
by B<filePath>

=item getXmlTemlate I<-none->

Use this flag to copy a example xml file to the directory specified by
B<filePath>.

=back

=head2 Database Option Descriptions

Use these options to load, create or drop a database being
used for SpiderEyeballs configuration. The database is to be
used instead of the xml file for faster access.  This allows
for fast dynamically genreated pages from mod_perl or straight
CGI.

=over 4

=item createDB I<-none->

Using this will create the table structres necessary for SpiderEyeballs
in a database you specify.

=item loadDB I<-none->

This will load the speficied xml B<file> into the database. You may need to 
use B<createDB> first.  B<createDB> and B<loadDB> can be spefied at the same
time like: C<spider --file my.xml --createDB --loadDB --type=Pg>

=item dropDB I<-none->

This will drop all the tables in the database that SpiderEyeballs uses.  It
can be used to clear the content of a xml file to load changes, or load a new
file.  I can be used in conjunction with B<createDB> and B<loadDB> to 
reinstall a xml file like: C<spider --dropDB --createDB --loadDB --type=Pg>

=item warnSql I<-none->

This will for all SQL statements being used to be printed to STDERR.  It
can be useful for debugging a problem.

=item server I<hostname>

The name of the server the database is being hosted on.  In most cases
the default is 'localhost' but that depends on the individual database
drivers.  For Pg and Mysql B<server> should be an actual host name, for
Sybase it can be a database alias, like the DSQUERY environment variable.

=item database I<text>

This should be the name of the actual database running on the specifed 
database server.  The default database is "spider".

=item user I<text>

This is the user name that will allow for CREATE/DROP/INSERT statements
into the database.  Default depends on individual datbase drivers.

=item password I<text>

The password for the specified B<user>

=item type I<Pg|Mysql|Sybase>

The database type.  The three currently supported database are
Pg (PostgreSql), Mysql, and Sybase.  It should not be difficult to add more
database support as requested.

=item port I<number>

The port the database server is running on.  The default depends on the
individual database drivers.

=back

=head2 ModPerl Option Descriptions

These options are to be used in the apache httpd.conf to configure 
Spidy::Registry.  You can use modperl using either an xml file or
a database as input.  Most of these options are identical to the 
the B<spider> command line options.  It is currently just a subset
of the B<spider> options.  

=over 4

=item ConfigFile I<path>

See the B<file> option above.

=item ImagePath I<path>

Same as the B<ImageUrl> option above.

=item InputImagePath I<path>

Same as the B<inputImagePath> option above.

=item Sizes I<size>

Same as the B<sizes> option above.

=item ParentUrl I<url>

Same as the B<parentUrl> option above.

=item GroupObject I<perl module>

This is the module (class) that the group objects will be blessed into.  This is only useful
if you are writing a module that inherits from Spidy::Registry.  Spidy::CGI::Group is the
default class.

=item ImageObject I<perl_module>

This is the module (class) that the image objects will be blessed into.  This is only useful
if you are writing a module that inherits from Spidy::Registry.  Spidy::CGI::Image is the
default class.

=item GroupTemplateFile I<path>

Same as the B<groupTmpl> option above.

=item ImageTemplateFile I<path>

Same as the B<imageTmpl> option above.

=item BgColor I<color>

Same as the B<bgColor> option above.

=item FgColor I<color>

Same as the B<fgColor> option above.

=item DatabaseName I<text>

Same as the B<database> option above.

=item DatabaseUser I<text>

Same as the B<user> option above.

=item DatabasePassword I<text>

Same as the B<password> option above.

=item DatabaseServer I<hostname>

Same as the B<server> option above.

=item DatabasePort I<number>

Same as the B<port> option above.

=item DatabaseType I<Pg|Mysql|Sybase>

Same as the B<type> option above.

=item WarningSql I<yes|no>

Same as the B<warnSql> option above.

=back

=head1 XML DOCUMENT

This section describes the tags that can be used in an the xml document
that is specified with the B<file> option.

For those of you not familiar with XML, it is very similar to HTML.  The are a
couple minor distinctions.  First all arguments inside tags must be quoted, so 
<TAG name=mytag> is bad, it should be <TAG name='mytag'>.  Also there can not
be any tag that is not explicitly closed.  So all tags need to be balanced or
end in '/>'.  Example <TAG>text</TAG> or <TAG name='mytag' />.

When you create your own XML document to describe your website there
are items to help.  You can use C<spider --file E<lt>myfile.xmlE<gt> --test>
to find out if the document is well-formed.  If you have errors
be sure to use the --debug option and view the output parse tree.  Make
sure the start and end tags line up appropriately etc.  Generally the error
message produced by the XML::Parser module are fairly accurate.

=head2 SPIDY DTD

Note that this DTD is not actually used to parse the xml document, because
XML::Parser does not use DTD definitions.  Also I am not XML expert, so this
DTD might not be exact.  If you know about these things and see errors here, 
please let me know.

 <!ELEMENT gallery(size+|group)>

 <!ELEMENT size (#PCDATA)>
 <!ATTLIST size name CDATA #REQUIRED>
 <!ATTLIST size max_width CDATA #IMPLIED>
 <!ATTLIST size max_height CDATA #IMPLIED>
 <!ATTLIST size qualith CDATA #IMPLIED>
 <!ATTLIST size padded CDATA #IMPLIED>

 <!ELEMENT group ((group+|image+)
                  |copyright?
                  |link*
                  |title?
                  |comment?
                  |shorttitle?
                  |var*
                  |output_image_path?
                  |input_image_path?
                  |file_path?
                  |html_path?
                  |image_url?)>
 <!ATTLIST group name CDATA #REQUIRED>
 <!ATTLIST group title CDATA #IMPLIED>
 <!ATTLIST group short_title CDATA #IMPLIED>
 <!ATTLIST group columnt_count CDATA #IMPLIED>
 <!ATTLIST group bg_color CDATA #IMPLIED>
 <!ATTLIST group fg_color CDATA #IMPLIED>
 <!ATTLIST group vlink_color CDATA #IMPLIED>
 <!ATTLIST group link_color CDATA #IMPLIED>
 <!ATTLIST group base_url CDATA #IMPLIED>
 <!ATTLIST group image_url CDATA #IMPLIED>
 <!ATTLIST group file_path CDATA #IMPLIED>
 <!ATTLIST group html_path CDATA #IMPLIED>
 <!ATTLIST group output_image_path CDATA #IMPLIED>
 <!ATTLIST group output_image_path_type CDATA #IMPLIED>
 <!ATTLIST group input_image_path CDATA #IMPLIED>
 <!ATTLIST group base_url CDATA #IMPLIED>
 <!ATTLIST group bundle_download CDATA #IMPLIED>
 <!ATTLIST group copyright CDATA #IMPLIED>
 <!ATTLIST group base_url CDATA #IMPLIED>
 <!ATTLIST group isolate CDATA #IMPLIED>

 <!ELEMENT autogroup ((group+|image+)
                      |copyright?
                      |link*
                      |title?
                      |comment?
                      |shorttitle?
                      |var*
                      |output_image_path?
                      |input_image_path?
                      |file_path?
                      |html_path?
                      |image_url?)>
 <!ATTLIST autogroup name CDATA #REQUIRED>
 <!ATTLIST autogroup title CDATA #IMPLIED>
 <!ATTLIST autogroup short_title CDATA #IMPLIED>
 <!ATTLIST autogroup columnt_count CDATA #IMPLIED>
 <!ATTLIST autogroup bg_color CDATA #IMPLIED>
 <!ATTLIST autogroup fg_color CDATA #IMPLIED>
 <!ATTLIST autogroup vlink_color CDATA #IMPLIED>
 <!ATTLIST autogroup link_color CDATA #IMPLIED>
 <!ATTLIST autogroup base_url CDATA #IMPLIED>
 <!ATTLIST autogroup image_url CDATA #IMPLIED>
 <!ATTLIST autogroup file_path CDATA #IMPLIED>
 <!ATTLIST autogroup html_path CDATA #IMPLIED>
 <!ATTLIST autogroup output_image_path CDATA #IMPLIED>
 <!ATTLIST autogroup output_image_path_type CDATA #IMPLIED>
 <!ATTLIST autogroup input_image_path CDATA #IMPLIED>
 <!ATTLIST autogroup base_url CDATA #IMPLIED>
 <!ATTLIST autogroup bundle_download CDATA #IMPLIED>
 <!ATTLIST autogroup copyright CDATA #IMPLIED>
 <!ATTLIST autogroup base_url CDATA #IMPLIED>
 <!ATTLIST autogroup size CDATA #IMPLIED>
 <!ATTLIST autogroup isolate CDATA #IMPLIED>

 <!ELEMENT image (copyright?
                  |link*
                  |title?
                  |comment?
                  |shorttitle?
                  |var*
                  |mouseOver?
                  |output_image_path?
                  |input_image_path?
                  |file_path?
                  |html_path?
                  |image_url?)>
 <!ATTLIST image name CDATA #REQUIRED>
 <!ATTLIST image title CDATA #IMPLIED>
 <!ATTLIST image short_title CDATA #IMPLIED>
 <!ATTLIST image columnt_count CDATA #IMPLIED>
 <!ATTLIST image bg_color CDATA #IMPLIED>
 <!ATTLIST image fg_color CDATA #IMPLIED>
 <!ATTLIST image vlink_color CDATA #IMPLIED>
 <!ATTLIST image link_color CDATA #IMPLIED>
 <!ATTLIST image base_url CDATA #IMPLIED>
 <!ATTLIST image image_url CDATA #IMPLIED>
 <!ATTLIST image file_path CDATA #IMPLIED>
 <!ATTLIST image html_path CDATA #IMPLIED>
 <!ATTLIST image output_image_path CDATA #IMPLIED>
 <!ATTLIST image output_image_path_type CDATA #IMPLIED>
 <!ATTLIST image input_image_path CDATA #IMPLIED>
 <!ATTLIST image base_url CDATA #IMPLIED>
 <!ATTLIST image bundle_download CDATA #IMPLIED>
 <!ATTLIST image copyright CDATA #IMPLIED>
 <!ATTLIST image base_url CDATA #IMPLIED>
 <!ATTLIST image isolate CDATA #IMPLIED>

 <!ELEMENT copyright  (#PCDATA)>
 <!ELEMENT link       (#PCDATA)>
 <!ELEMENT title      (#PCDATA)>
 <!ELEMENT shorttitle (#PCDATA)>

 <!ELEMENT comment    (#PCDATA)>
 <!ATTLIST comment default CDATA #IMPLIED>
 <!ATTLIST comment file CDATA #IMPLIED>
 <!ATTLIST comment prepend CDATA #IMPLIED>

 <!ELEMENT var        (#PCDATA)>
 <!ATTLIST var name  CDATA #REQUIRED>
 <!ATTLIST var value CDATA #IMPLIED>

 <!ELEMENT output_image_path (#PCDATA)>
 <!ATTLIST output_image_path type CDATA #IMPLIED>

 <!ELEMENT input_image_path (#PCDATA)>
 <!ATTLIST input_image_path type CDATA #IMPLIED>

 <!ELEMENT file_path (#PCDATA)>
 <!ATTLIST file_path type CDATA #IMPLIED>

 <!ELEMENT html_path (#PCDATA)>
 <!ATTLIST html_path type CDATA #IMPLIED>

 <!ELEMENT image_url (#PCDATA)>
 <!ATTLIST image_url type CDATA #IMPLIED>

=head2 SAMPLE XML FILE

 <group>
   <comment>These are my pictures of camels</comment>
   <title>Camels are Cool</title>
   <shorttitle>Cool Camel</shorttitle>
   <link>
     <A HREF="http://www.camelgallery.org">More Camels</A>
   </link>
   <copyright>&copy; by Mr. McGee</copyright>
   <group name="fido" column_count="5">
     <var name="food" value="Fido likes watermelon">
     <image name="fido1.jpg">
       <title>Fido</title>
       <comment>&food;</comment>
     </image>
     <image name="pattern:fido[34-56].jpg"/>
   </group>
   <group name='spot'>
     <image name="pattern:spot[1-22].jpg">
       <title>Spot at the races</title>
     </image>
   </group>
 </group>

This will create a website that is 3 levels deep.  The top level
will have links (via thumbnails) to the 2 'childen' groups 'fido' 
and 'spot'.  That page will have a title of "Camel's are Cool" 
and a comment below the thumbnails table saying "These are my 
pictures of camels". Also there will be a link to "More Camels"
on the left under the copyright information.  See B<XML TO HTML LANDSCAPE>
below to see more precisely where the info will be placed.

Each of the children groups will have links (via thumbnails) to each of 
their children images.  The fido group will display all the thumbnail 
images in a table of 5 columns wide.  Spot will get the default of 7 
columns wide.  Both the fido and spot groups will inherit the copyright
information and link information from the parent.  The original images
for fido are fido1.jpg, fido34.jpg, fido35.jpg ... fido56.jpg. Only
the page for fido1.jpg will have a comment of "Fido likes watermelon". Spot
is very similar, it will have pages for the original images of spot1.jpg,
spot2.jpg ... spot22.jpg, and all pages will have the title "Spot at the races".

=head2 TAG DESCRIPTIONS

=over 4

=item WARNING

I have forced a CDATA wrapper around all text type blocks.  So that means
extra XML tags will be inserted into your XML before it gets parsed. 
XML purists will hate this tag, but I find it convenient.  The CDATA
tags will get inserted around all B<title>, B<shorttitle>, B<comment>, B<copyright>,
B<link> and B<var> tags.  This is done to allow users to put in any old
text into the B<comment> and other tags.  Since this is an xml document, which
looks a lot like html, you cannot effectivly put html in xml.  So to get around this
I have automatically escaped everthing inside these tags.  Html will not get parsed
by the xml parser.  To do this I preparse the xml file (ie, I modify the xml data before the XML::Parser
module gets called) and just add in the special 
xml escaping sequence '<![CDATA[' to start and ']]>' to finish.  If you are a xml purist
and want to add in your own CDATA tags, be my guest, B<spider> with work either way.

=item group

The B<group> tag is used to descibe a page which will have a table of thumbnail
images of other groups or images. 

There must be a 'name' paramater, which will be used as directory name under
B<filePath> and will become part of the url.  It should not contain spaces.  
The top most group most likely will have a name of "", but it does not have to.

An optional paramater is 'column_count'.  This will specify the number of 
columns to make the table of icons.  The default is 7.

Between the open and close B<group> tags there can any number of B<group> or B<image>
tags.  But a B<group> should not have both B<group> and B<images> tags simultaneously.
Also inside a B<group> there may be be any (or none) of B<title>, B<shortitle>, B<comment>, 
B<copyright>, B<var> or B<link>.  For most of these they can be specified as arguments
to the open tag also.  Here is an example:

  <group name='foobar'>
    <comment>This is a comment</comment>
    <title>The Title</title>
  </group>
  
  ... This is  the same as ...
  
  <group name='foobar' 
         comment='This is a comment' 
         title='The Title'>

A B<group> or B<image> will inherit B<copyright> and B<link> information from its parent if and only if
you do not specify a B<copyright> or B<link> tag within the current group.  If you 
want to get rid of all parental links or copyrights, and do not want to add 
any either, then you can use '<link/>' or '<copyright/>' to create empty tags.  They will always inherit
B<var> information, however new B<var> tags will the same name will override inherited ones.

By default all groups will link to each other.  This means that if you are on an image page, you can
always click the "Next" icon or text.  The "Next" image does not have to be in the same group as the current
one (or even at the same hierarchical depth), it will automatically link over.  If for some reason
you do not wish to have the groups connect
with the "Next" link you can specify the attribute C<isolate="1">.  B<isolate> is a boolean flag and can
also be added to the B<autogroup> or B<image> tags.  The isolate tag is only use for crosslinking
groups, so that means you cannot isolate two images withing a single group.  If you want to do that, make
sub groups. If you turn on B<isolate> for the first image in a group, it will not link to any previous
groups.  If you turn on B<isolate> for the last image, it will not link to the next group.  If you turn on
B<isolate> at the group, the images will not connect to either the previous or next groups.

=item autogroup

The B<autogroup> is basically identical to the B<group> tag except one major
difference.  B<autogroup> will automatically cut a group into subgroups depending
on how many images are in that group.  The default size it wil cut groups into is
24, however you can customize that with the B<size> attribute on the B<autogroup> 
tag.  Here is an example:

  <autogroup name="foobar" size="16" title="My Pics">
    <image name="pattern:*.jpg"/>
  </autogroup>

So if there are 50 images that match the pattern *.jpg, then the autogroup will
get turned into 4 groups.  There would be 3 groups of 16 images, and the final 
group would only have 2 images in it.  The output html files would be placed in
foobar1, foobar2, etc.  And the group titles would look like "S<My Pics (1 of 4)>",
"S<My Pics (2 of 4)>", etc.  This is a very handy tag.  It will let you group
many pictures together and make a large gallery that is still easy to navigate,
and yet easy to create!  You should definatly read the B<group> section if you have not yet.

=item image

The B<image> tag is used to describe a page that has no children, it is a simple
standalone image.  

There must be a 'name' paramater.  This should be the name of the B<image> and it
should exist under B<inputImagePath>.  It can be a relative path, or a fixed
path.  So if B<inputImagePath> is "/home/images" and name="spot/spot1.jpg" then 
the input image will be /home/images/spot/spot1.jpg.  If you prefix the image
name with 'pattern:' then the image name is assumed to be a regular
expression and not an actual file.  The regular expression will be used to 
find any images that match that pattern in the specified directory, and all
images found will inherit all properties withing the image tag.  So from above 

   <image name="pattern:spot[1-22].jpg">
     <title>spot at the races</title>
   </image>

all 21 images will have the title of 'spot at the races (x of 21)' where x will
be the image position within the set.  Many of you
will notice that spot[1-22].jpg is not a valid regular expression to mean 1, 
2, 3, ... 22.  That is of course correct, but I wanted to simply the syntax 
since I expect this to be a common usage.  In fact this pattern will eventually
get turned into spot(1|2|3|4|5|6|...|21|22).jpg.  Also if spot13.jpg does not
exist in the B<inputImagePath> then it is silently skipped and the titles
will be 'spot at the races (x of 20)', that way you can easily express ranges
even if there are not enough files to complete the range.

Similarly to the name argument you can also have a B<mouseOver> argument.  It should
look something like this:

  <group name="image1.jpg" mouseOver="image2.jpg"/>

This xml will cause there to be a page with the main image having the javascript mouseover
function used.  When a user passes the mouse over the image1.jpg, then the image2.jpg will
show up.  When the mouse leaves the image area, then it will revert back to image1.jpg.  Text
will show up on the page in red font to indicate that the image has the 'mouse over' feature.

Between the open and close B<image> tags to can be any (or none) or B<title>,
B<comment>, B<copyright>, B<link> or B<var>.

A B<image> will inherit B<copyright> and B<link> information from its parent if and only if
you do not specify a B<copyright> or B<link> tag within the current B<image>.  If you 
want to get rid of all parental links or copyrights, and do not want to add 
any either, then you can use '<link/>' or '<copyright/>' to create empty tags.  Also see the section on
B<group> for help on the B<isolate> attribute.

=item gallery

The B<gallery> tag is basically a container tag for wrapping up global tags with
B<group> tags.  You will only need this tag when specifying other tags which are intended
to modify the global behavior of the application.  Currently the only tag like this is 
B<size>.  You would use the B<gallery> tag like this:

 <gallery>
   <size name="thumb" max_height="100" max_width="100"/>
   <group>
      <!-- all your sub groups and images go here -->
   </group>
 </gallery>

=item size

This tag must be used in conjuction with the B<gallery> tag.  It cannot be placed
inside B<group> or B<image> tags.  The B<size> tag is used
to modify the global behavior of image sizes for the application.  You can customize
existing sizes (like by making thumbnails larger, or smaller, etc), or you can create
entirely new sizes.  Here is an example of <size> usage:

 <gallery>
   <size name="thumb" max_width="100" max_height="100"/>
   <size name="itty-bitty" max_width="10" max_height="10" padded="1"/>
   <group>
     ...
   </group>
 </gallery>

Then the if you did something like 
C<spider --file gallery.xml --inputImagePath images --sizes> the output size
table would look like:

 +----------+-----+------+-------+------+------+
 |name      |width|height|quality|padded|custom|
 +----------+-----+------+-------+------+------+
 |thumb     |  100|   100|     80|yes   |yes   |
 |teeny     |  250|   200|     80|no    |no    |
 |small     |  400|   300|     80|no    |no    |
 |medium    |  500|   400|     80|no    |no    |
 |large     |  800|   600|     90|no    |no    |
 |xlarge    | 1300|  1000|     97|no    |no    |
 |original  |    *|     *|     80|no    |no    |
 |itty-bitty|   10|    10|     80|yes   |yes   |
 +----------+-----+------+-------+------+------+

Note that by creating additional sizes, like 'itty-bitty' in the example above, that
does not mean the size will be used.  It will just be defined and is able to be
used if desired.  To actually use non-default sizes you will still have to specify
the --sizes option with the name and order of sizes desired.  So you probably want to use
something like C<spider --sizes itty-bitty,small,large>.

There are five possible attributes for size:

=over 4

=item name

Name is required.  It can either be the name of an existing size, or the name of a
new size to be added.

=item max_height

This is the maximum height to be used for the image size.  The image will be created using
max_height and max_width as a bounding box.  The image will be scaled so it just fits within
the bounding box, it will not be larger.  It will not be stretched to fix the sizes.

=item max_width

This is the maximum width to be used for the image size.  The usage is similar to B<max_height>.

=item quality

This represents the quality (or compression level) of the image.  It should be a value from 0-100.
The default value is 80.

=item padded

This is a boolean value to force the image to be padded.  This means that the difference between the
max_height and the actual height, as well as the max_width and the actual width will be padded
with the B<bg_color> value.  So this pads the output image to be actually be the max_height, and
max_width requardless of the actual image size.

=back

=item copyright

The B<copyright> tag is to be used to specify a copyright notice for the images.
This can be set for every B<image> or B<group> depending on 
circumstances.  Just insert the tags within a B<group> or B<image> tag.  This is
a sample:

  <copyright>&copy; by Mr. McGee</copyright>

Unless overridden B<copyright> is passed down to its children groups and images.

You can specify multiple B<copyright> tags for a B<group> or B<image>, they
will all be printed.

=item link

The B<link> tag is to be used to specify additional links which will be added
to the page.  The links can be set for any B<image> or B<group>.   This is a sample:

   <link>
     <A HREF="http://www.camelgallery.org">More Camels</A>
   </link>

Unless overridden B<link> is passed down to its children groups and images.

You can specify multiple B<link> tags for a B<group> or B<image>, they
will all be printed.

=item title

The B<title> tag is to be used to specify the B<image> or B<group> title. There can
be only one per B<group> or B<image>.  Here is an example:

   <title>Camels are Cool</title>

=item shorttitle

The B<shorttitle> tag is to be used to specify the B<image> or B<group> 'short' title. There can
be only one per B<group> or B<image>.  Here is an example:

   <shorttitle>Cool Camels</shorttitle>

This tag will be used for the names under the thumbnails on the group pages.  It will also be used
for the ancestor hierarchy list on the right hand side.  The value will default to 

=item comment

The B<comment> tag is to be used for comments or descriptions about the image
or group.  Example:

   <image name="fido1.jpg">
     <comment>Fido likes watermelon</comment>
   </image>

You can specify multiple B<comment> tags for a B<group> or B<image>, they
will all be printed together.

The comment tag has three attributes.  The B<default> attribute is a boolean
flag.  When turned on the comment will be inherited by sub groups, unless
another <comment> tag is specified.

The B<file> and B<prepend> attributes work together.  If you specify
the B<file> tag and give it a value of a file name then spider will look
in B<--inputFilePath> for the file named. If the file name has an absolulte
path name, then the B<inputFilePath> will be ignored.  The contents of the file will then
be included as the comment for the page.  By default the data will be appended
to whatever is between the <comment> and </comment> tags.  If you want the data
prepended to the data set B<prepend="1">.  Example:

  <comment file="files/rabies.txt">
    Fido's last Rabies shots were on:<br>
  </comment>

=item var

The B<var> tag is to set variables that can be used for text substitution
in later blocks.  This is useful if you want to have common text spread out
though your xml file.  With a var you can write the text once, then reference
is later as many times as you want.  Here is an examle:

  <var name="foo" value="short value"/>
  <var name="bar">
    This can be a large block of text ...
  </var>
  <comment>The foo variable is: &foo;</comment>
  <image name="fido1.jpg">
    <comment> The foo variable is still: &foo;</comment>
  </image>
  <copyright>The bar text is &bar;</copyright>

You can references the set variables using the &name; syntax where "name" is the
name argument of the B<var> tag.  The variable is scoped.  So if you set a variable
in a B<group>, it will be available inside that B<group> and all children groups. It will
not be available within peer B<group> tags.  Note that you use a tag which is not defined,
it will not do substitution on it and will leave the &name; text in the block.  This way
you can still use normal html variables such as &copy; and others.

=item output_image_path

The B<output_image_path> tag can be used to specify a different directory to place the output
images.  This can be specified in any B<group> or B<image> block.  The value will be inherited
by all children groups or images.  There can be a 'type' argument which should have the value
of 'fixed' or 'relative'.  The default value of 'type' is 'relative'.  A relative type will
cause the B<group> name to be appeneded to the B<output_image_path> value.  Here is an example:

  <group name='kittens'>
    <output_image_path type="fixed">
      /var/tmp/images
    </output_image_path>
    ...
  </group>

The value of B<output_image_path> will override any value specified to the B<spider> tool
with the --outputImagePath option.  So use this xml tag if there is an exceptional case
where all images are not to be put in the same directory structure.

=item input_image_path

The B<input_image_path> tag can be used to specify a different directory to retrieve the input
images from.  This can be specified in any B<group> or B<image> block.  The value will be inherited
by all children groups or images.  There can be a 'type' argument which should have the value
of 'fixed' or 'relative'.  The default value of 'type' is 'fixed'.  A relative type will
cause the B<group> name to be appeneded to the B<input_image_path> value.  Here is an example:

  <group name='kittens'>
    <input_image_path>/home/fiber/kittens</input_image_path>
    ...
  </group>

The value of B<input_image_path> will override any value specified to the B<spider> tool
with the --inputImagePath option.  So use this xml tag if there is an exceptional case
where all input images for the gallery are not in the same directory.

=item file_path

The B<file_path> tag can be used to specify a different directory to place the output
html files.  This can be specified in any B<group> or B<image> block.  The value will be inherited
by all children groups or images.  There can be a 'type' argument which should have the value
of 'fixed' or 'relative'.  The default value of 'type' is 'relative'.  A relative type will
cause the B<group> name to be appeneded to the B<file_path> value.  Here is an example:

  <group name='kittens'>
    <file_path>/home/fiber/kittens/htdocs</file_path>
    ...
  </group>

The value of B<file_path> will override any value specified to the B<spider> tool
with the --filePath option.  So use this xml tag if there is an exceptional case
where all output html files for the gallery are not in the same directory.

=item html_path

The B<html_path> tag can be used to specify a different url paths for the pages to be
referenced by.  I dont expect this feature to be used, but it is in there.  With this tag
you can in theory spread the content over multiply websites.  The implementation of this
however would be difficutly, so I leave that as an exercise to the reader.
B<html_path> can be specified in any B<group> or B<image> block.  The value will be inherited
by all children groups or images.  There can be a 'type' argument which should have the value
of 'fixed' or 'relative'.  The default value of 'type' is 'relative'.  A relative type will
cause the B<group> name to be appeneded to the B<html_path> value.  Here is an example:

  <group name='kittens'>
    <html_path>http://kittens.org/gallery/</html_path>
    ...
  </group>

=item image_url

The B<image_url> tag can be used to specified the URL where the images will be viewable from the web
browser..  This can be specified in any B<group> or B<image> block.  The value will be inherited
by all children groups or images.  There can be a 'type' argument which should have the value
of 'fixed' or 'relative'.  The default value of 'type' is 'relative'.  A relative type will
cause the B<group> name to be appeneded to the B<image_url> value.  Here is an example:

  <group name='kittens'>
    <image_url>http://images.myhost.com/kittens</image_url>
    ...
  </group>

The value of B<image_url> will override any value specified to the B<spider> tool
with the --imageUrl option.  So use this xml tag if there is an exceptional case
where all output html files for the gallery are not in the same directory.

=back

=head2 XML TO HTML LANDSCAPE

These ASCII images below display where the content is placed for each
of the appropriate tags described above.

=over 4

=item group page

                           title

      thumb  thumb  thumb  thumb  thumb  thumb  thumb                   
      
      thumb  thumb  thumb  thumb  thumb  thumb  thumb                   
      
      thumb  thumb  thumb  thumb  thumb  thumb  thumb                   
      
      comment   [left set]  [up]  [right set]  parent links
                                               title
                                               ------------
                                               copyright
                                               link
                                               link

=item image page

       -----------------------------------------------
       |                                             |
       |                                             |
       |                                             |
       |                                             |
       |                    Image                    |
       |                                             |
       |                                             |
       |                                             |
       |                                             |
       |                                             |
       -----------------------------------------------
       
       title    [left img]  [up]  [right img]  parent links
       comment              size               title
                            size               ------------
                [left set]  size  [right set]  copyright
                                               link
                                               link

=back

=head1 CUSTOMIZING THE TEMPLATES

First get a copy of the templates with the options B<getGroupTemplate> or
B<getImageTemplate>.  The general rule of thumb you should follow with these
files is to not modify any tag that starts with "TMPL_" unless you really
know what your are doing.  You should read L<HTML::Template> for further details
on the TMPL_ tags.  Bascially as long as you know html, feel free to tweak the 
files as desired.  To use your newly tweaked templates to create the file use
the B<imageTmpl> or B<groupTmpl> options to the B<spider> program.

=head1 INSTALLATION

=head2 REQUIREMENTS

=over 4

=item Perl Modules

=over 4

=item HTML::Template (Version 1.8)

Install: B<perl -MCPAN -e 'install "HTML::Template"'>

Provides the template page parsing.  Version 1.8 introduced a 'globalVars' 
paramater which is needed.

=item Image::Size

Install: B<perl -MCPAN -e 'install "Image::Size"'>

Provides a very fast utility for finding out the exact pixel height and width
of an image.

=item XML::Parser

Install: B<perl -MCPAN -e 'install "XML::Parser"'>

This module is need to parse the input xml document describing the website.  I
have had difficulties installing this module after verions 2.29 since a required
library 'expat' is no longer include, and I have been unsucessful installing
newer versions of 'expat' on some operating systems.  If you trouble installing
the latest XML::Parser module then try to install Version 2.29 using the
command: C<perl -MCPAN -e 'install "C/CO/COOPERCL/XML-Parser-2.29.tar.gz"'>

=back

=item External Programs

=over 4

=item Image Magick (convert)

The program 'convert' in the Image Magick project is used to create all the
various sized images.  If the program is not already installed you can get
it from http://www.imagemagick.org.

=back

=back

=head2 INSTRUCTIONS

=over 4

=item UNIX

These are the usual commands to install perl modules:

      perl Makefile.PL
      make
      make test
      make install

=item Windows

Special versions of Perl and Image Magic need to be installed for Windows
and a special way to install Spidy and dependent perl modules is needed.

=over 4 

=over 4

=item ActivePerl

You need ActivePerl.  Download and install it from here:
S<http://www.activestate.com/Products/Download/Register.plex?id=ActivePerl>


After ActivePerl is installed start the Perl Package Manager 

 Click "Start" 
  -> then "Run" 
  -> in the "Open:" box enter "ppm"
  -> click "OK"

A dos-like terminal should appear with a "PPM>" prompt.  Enter these commands:

 install Image::Size HTML::Template
 install http://spidereyeballs.com/ppm/Spidy.ppd

=item Image Magick

You need the Image Magick binaries for windows.  You can download 
them from here:  http://www.imagemagick.org/www/QuickStart.html

 -> Go to the "XP, Win2K, WinME, NT, Win98, Win95 Install" Section near the bottom
 and download and install the package.

=back

=back

=back

=head1 BUGS

There are probably a lot, this is still alpha code.  
Please contact me if you find one.

=head1 ACKNOWLEDGEMENTS

I would like the thank all the people who have helped write the required
modules for some very fine work.

=head1 AUTHOR

Spider Eyeballs was written by Cory Bennett <coryb@corybennett.org>

Copyright 2000-2002 Cory Bennett and Julian Cash

The first version of Spider Eyeballs was written and designed
by Julian Cash.  The new version (written by Cory Bennett) is
a complete rewrite which implements XML, templates, cgi and
database support, and more supportable code (in theory).

Cory Bennett's home page is http://corybennett.com

Julian Cash is a programmer and photographer.
To see his photographs, hop on over to http://www.supersnail.com

=head1 SEE ALSO

The official site for this program is http://www.spidereyeballs.com.
We have a SourceForge project page also at 
http://www.sourceforge.net/projects/spidereyeballs.

L<HTML::Template>, L<XML::Parser> and L<Image::Size>

=cut
