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

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

DESCRIPTION
    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.

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

  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
     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

  General Option Descriptions
    convert *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.

    config *path*
        The config option allows users to save 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 "spider --config
        myconfig". If you wish use all the options from myconfig, but say,
        only want size 'small', then you can run "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 "spider" or "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.

    debug *-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 file. It will also product various other
        messages as the program goes along.

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

    help *-none-*
        Boolean flag, when set it will display the usage information for
        spider.

    html *yes|no*
        This flag determins whether or not the program will create the html
        files for the website. The default is 'yes'.

    icons *yes|no*
        This flag determins 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.

    images *yes|no*
        This flag determins 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
        forceImages to overwrite existing images.

    test *-none-*
        Use this command to just make sure the xml file specified with the
        file option is a well-formed xml document.

  Image Option Descriptions
    forceImages *-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 spider will not
        overwrite images if they exist.

    gravity *direction*
        This flag is passed to the Image Magick 'composite' utilty during
        creation of watermarks. 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'.

    inputImagePath *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 file option. The default is '.', the
        current directory.

    outputImagePath *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 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 "filePath/images".
        If the 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 filePath. Also see imageUrl and outputImagePathType if
        you use this option.

    outputImageType *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.

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

    sizes *size list*
        With an argument, the sizes option forces 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 "spider --sizes", see above for details. Ex:
        '--sizes small,original'.

    sizes *-none-*
        If this paramater is not given any paramaters, then spider does not
        create any html or images, it simply reports the names of the
        various sizes that 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 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 size xml
        tag below), then it will report the customized sizes. Just run
        spider so it will read in the xml file, something like: "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   |
         +----------+-----+------+-------+------+---------+------+

    watermark *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 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 sizes option. There is no default watermark.

  Html Option Descriptions
    baseUrl *URL*
        If this argument is given, then the value will be placed in the
        "<BASE HREF="<baseUrl>">" tag at the top of each html page that is
        created.

    bundleDownload *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 "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.

    defaultSize *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'.

    filePath *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.

    imageUrl *URL*
        If you have used the 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 filePath. If outputImagePathType is
        'fixed' or not defined, then the default is 'images', otherwise the
        default is the same as baseUrl.

    imageTmpl *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.

    groupTmpl *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.

    tmplPath *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.

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

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

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

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

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

    parentUrl *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.

  Template Option Descriptions
    Use these options to get a copy of default templates.

    getImageTemplate *-none-*
        Use this flag to copy the default image template <image.tmpl> to the
        directory specified by filePath.

    getGroupTemplate *-none-*
        Use this flag to copy the default group template <group.tmpl> to the
        directory specified by filePath.

    getTemplates *-none-*
        Use this flag to copy all the templates to the directory specified
        by filePath

    getXmlTemlate *-none-*
        Use this flag to copy a example xml file to the directory specified
        by filePath.

  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.

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

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

    dropDB *-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
        createDB and loadDB to reinstall a xml file like: "spider --dropDB
        --createDB --loadDB --type=Pg"

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

    server *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 server should be an actual host
        name, for Sybase it can be a database alias, like the DSQUERY
        environment variable.

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

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

    password *text*
        The password for the specified user

    type *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.

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

  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 spider
    command line options. It is currently just a subset of the spider
    options.

    ConfigFile *path*
        See the file option above.

    ImagePath *path*
        Same as the ImageUrl option above.

    InputImagePath *path*
        Same as the inputImagePath option above.

    Sizes *size*
        Same as the sizes option above.

    ParentUrl *url*
        Same as the parentUrl option above.

    GroupObject *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.

    ImageObject *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.

    GroupTemplateFile *path*
        Same as the groupTmpl option above.

    ImageTemplateFile *path*
        Same as the imageTmpl option above.

    BgColor *color*
        Same as the bgColor option above.

    FgColor *color*
        Same as the fgColor option above.

    DatabaseName *text*
        Same as the database option above.

    DatabaseUser *text*
        Same as the user option above.

    DatabasePassword *text*
        Same as the password option above.

    DatabaseServer *hostname*
        Same as the server option above.

    DatabasePort *number*
        Same as the port option above.

    DatabaseType *Pg|Mysql|Sybase*
        Same as the type option above.

    WarningSql *yes|no*
        Same as the warnSql option above.

XML DOCUMENT
    This section describes the tags that can be used in an the xml document
    that is specified with the 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 "spider --file <myfile.xml> --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.

  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>

  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 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".

  TAG DESCRIPTIONS
    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 title, shorttitle,
        comment, copyright, link and var tags. This is done to allow users
        to put in any old text into the 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, spider with work either way.

    group
        The 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 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 group tags there can any number of group
        or image tags. But a group should not have both group and images
        tags simultaneously. Also inside a group there may be be any (or
        none) of title, shortitle, comment, copyright, var or 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 group or image will inherit copyright and link information from
        its parent if and only if you do not specify a copyright or 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 var information, however new 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 "isolate="1"". isolate is a boolean flag and can also be
        added to the autogroup or 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 isolate for the first image in a group, it will not link
        to any previous groups. If you turn on isolate for the last image,
        it will not link to the next group. If you turn on isolate at the
        group, the images will not connect to either the previous or next
        groups.

    autogroup
        The autogroup is basically identical to the group tag except one
        major difference. 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 size attribute on the 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 "My Pics (1 of 4)", "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 group section
        if you have not yet.

    image
        The 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
        image and it should exist under inputImagePath. It can be a relative
        path, or a fixed path. So if 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 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 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 image tags to can be any (or none) or
        title, comment, copyright, link or var.

        A image will inherit copyright and link information from its parent
        if and only if you do not specify a copyright or link tag within the
        current 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 group for help on the isolate attribute.

    gallery
        The gallery tag is basically a container tag for wrapping up global
        tags with 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 size. You would use
        the 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>

    size
        This tag must be used in conjuction with the gallery tag. It cannot
        be placed inside group or image tags. The 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 "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 "spider --sizes itty-bitty,small,large".

        There are five possible attributes for size:

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

        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.

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

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

        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 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.

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

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

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

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

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

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

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

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

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

           <title>Camels are Cool</title>

    shorttitle
        The shorttitle tag is to be used to specify the image or group
        'short' title. There can be only one per group or 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

    comment
        The 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 comment tags for a group or image, they
        will all be printed together.

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

        The file and prepend attributes work together. If you specify the
        file tag and give it a value of a file name then spider will look in
        --inputFilePath for the file named. If the file name has an
        absolulte path name, then the 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 prepend="1". Example:

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

    var The 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 var tag. The variable is scoped.
        So if you set a variable in a group, it will be available inside
        that group and all children groups. It will not be available within
        peer 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.

    output_image_path
        The output_image_path tag can be used to specify a different
        directory to place the output images. This can be specified in any
        group or 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 group name to be
        appeneded to the 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 output_image_path will override any value specified to
        the 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.

    input_image_path
        The input_image_path tag can be used to specify a different
        directory to retrieve the input images from. This can be specified
        in any group or 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 group name to be
        appeneded to the input_image_path value. Here is an example:

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

        The value of input_image_path will override any value specified to
        the 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.

    file_path
        The file_path tag can be used to specify a different directory to
        place the output html files. This can be specified in any group or
        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 group name to be appeneded to the
        file_path value. Here is an example:

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

        The value of file_path will override any value specified to the
        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.

    html_path
        The 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.
        html_path can be specified in any group or 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 group name to be appeneded to the html_path
        value. Here is an example:

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

    image_url
        The 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
        group or 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 group name to be
        appeneded to the image_url value. Here is an example:

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

        The value of image_url will override any value specified to the
        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.

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

    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

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

CUSTOMIZING THE TEMPLATES
    First get a copy of the templates with the options getGroupTemplate or
    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 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 imageTmpl or groupTmpl options to
    the spider program.

INSTALLATION
  REQUIREMENTS
    Perl Modules

        HTML::Template (Version 1.8)
            Install: perl -MCPAN -e 'install "HTML::Template"'

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

        Image::Size
            Install: perl -MCPAN -e 'install "Image::Size"'

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

        XML::Parser
            Install: 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: "perl -MCPAN -e 'install
            "C/CO/COOPERCL/XML-Parser-2.29.tar.gz"'"

    External Programs

        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.

  INSTRUCTIONS
    UNIX
        These are the usual commands to install perl modules:

              perl Makefile.PL
              make
              make test
              make install

    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.

            ActivePerl
                You need ActivePerl. Download and install it from here:
                http://www.activestate.com/Products/Download/Register.plex?i
                d=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

            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.

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

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

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

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.

    HTML::Template, XML::Parser and Image::Size

