$Id: INSTALL,v 1.22 2001/06/03 01:43:46 clindell Exp $

Note: This package comes with formal documentation.  Peruse this
  INSTALL file first to do the basic install and then read or print
  out the documentation in the 'doc' subdirectory.

WebMagick requires the ImageMagick (at least version 3.8.4) and
PerlMagick (at least version 1.12) packages as well as a recent version
of PERL 5.  You will likely find that certain versions of PerlMagick
are required for certain versions of ImageMagick.  I don't know of
a useful way to find this out.  The easiest solution is to grab both
packages off the distribution site at the same time.  As of ImageMagick
4.0.0, PerlMagick is included with ImageMagick so incompatability should
no longer be an issue.

Obtain PERL version 5 from the Perl Language Home Page at
"http://www.perl.com/perl/index.html".  Install PERL according to its
installation instructions.

Obtain ImageMagick (which includes PerlMagick) from
"http://www.imagemagick.org/".  Install ImageMagick
according to the instructions in its README file.  Consider using the
'configure' configuration method with the --enable-lzw flag to enable
LZW compression for GIF files (otherwise GIF files will be huge!).
Before using this flag however, review your relationship with Unisys
(which holds the patent on LZW compression).

PerlMagick may be installed automatically with ImageMagick through use
of the --enable-perl option to ImageMagick's 'configure' or manually
via 'make install' in ImageMagick's PerlMagick subdirectory.  I
personally configure ImageMagick/PerlMagick via the command:
"./configure --enable-lzw --enable-perl --disable-static" which
enables LZW compression, enables automatic build/install of PerlMagick
at 'make install' time, and skips building static libraries (to
decrease compile time). Read about PerlMagick at the PerlMagick web
page at "http://www.imagemagick.org/www/perl.html".

Execute WebMagick's configure script specifying a --prefix option for a
GNU-style directory heriarchy you would like to install in (e.g.
"./configure --prefix=/opt/tools"). This will generate a base copy of
WebMagick that has been edited to reflect the location of your PERL
interpreter and the X11 RGB database.

The configure script will ask you questions to provide definitions of
$opt_prefixpath, $opt_rootpath, $opt_iconpath, $opt_htimage, and
$opt_maptype in the 'webmagick' script and the sample webmagickrc file.
Read the manual page to learn the details. A few examples are provided
below. The script also provides examples of what the options should look
like.

Then "make install". This will install WebMagick, sample icons, the
WebMagick JavaScript interface, and TexInfo documentation.  The
WebMagick icons must be installed in a directory somewhere under the
same server "root" as the images you want to catalogue.  This root
does not neccessarily have to be the actual server root.  The "root"
may be established via a server path mapping (rather than symlink)
that offsets onto another filesystem.

In order for JavaScript mode to operate correctly, the file
'webmagick.js' must be installed in the location specified by
$opt_iconpath and the server must be updated to associate MIME type
"application/x-javascript" with the extension ".js".  This file
contains the various JavaScript routines that define WebMagick's
JavaScript interface.  See the formal documentation for more on
JavaScript.

                         Protect My Reputation!
                         ======================

If you are operating a site that my mother wouldn't approve of, please
set the $opt_anonymous option to 1 or use the --anonymous option.  This
removes WebMagick copyright info from all generated pages.  In particular,
it removes my email address so I don't get email from confused users
regarding material I would rather not hear about.  :-)

			  Path Configuration
			  ==================

The following .webmagickrc file path variables will configure WebMagick for a Web
server root of "/html" and WebMagick icon path "/html/Images/WebMagick".

$opt_prefixpath = '';		# Path or URL to prepend to root URL
				# Not used if local relative paths used
$opt_rootpath   = '/html';      # Directory Path to top of html tree
				# Needed to determine relative paths to images
$opt_iconpath   = 'Images/WebMagick';
				# Relative path under rootpath / prefixpath

Or, if your images and icons are under your personal HTML directory
(e.g. http://www.bogus.com/~bfriesen/) which is physically
"/home/bfriesen/public_html" and the WebMagick icons are in
"/home/bfriesen/public_html/icons/WebMagick", you can use the
configuration:

$opt_prefixpath = '~bfriesen';
$opt_rootpath   = '/home/bfriesen/public_html';
$opt_iconpath   = 'icons/WebMagick';

			Server Side Imagemaps
			=====================

If you are using a recent NCSA or Apache server that supports server-side
imagemaps using relative URLs, then you can use values similar to the
following:

# Server-side imagemap settings
$opt_htimage='';	# Base URL to server-side imagemap CGI
			# On some systems this is /cgi-bin/imagemap
			# Set to '' to use a ".map" URL with
			# relative URLs (latest NCSA & Apache)
$opt_maptype='ncsa';	# Maptype must be "cern" or "ncsa". If
			# you are using Apache, specify "ncsa".

In order for server-side imagemaps (used by older browsers) to work
properly, some configuration may be required. Options should be set
similar to the following (CERN configuration shown):

# Server-side imagemap settings
$opt_htimage='/cgi-bin/htimage'; # Base URL to server-side imagemap CGI
			# On some systems this is /cgi-bin/imagemap
			# Set to '' to use a ".map" URL with
			# relative URLs (latest NCSA & Apache)
$opt_maptype='cern';	# Maptype must be "cern" or "ncsa". If
			# you are using Apache, specify "ncsa".


			  NOTES AND WARNINGS
			  ==================

Please be careful than when running WebMagick you are in the correct
directory. If you are in the wrong directory (such as in the
server's root), you can do serious damage because WebMagick will
overwrite all your HTML index files.

To ensure that WebMagick never generates HTML index files in a
particular directory you can create a ".webmagickrc" file in that
directory with the line:
    $opt_ignore = 1;  # ignore this directory (though link it in)

If no sub-directories are to be have WebMagick applied (if run with
the option ``-recurse'') you can also add the line:
     $opt_prune = 1;  # prune all sub-directories for recursive runs

If you encounter any difficulties, have suggestions, or accolades,
feel free to send WebMagick's author (Bob Friesenhahn,
bfriesen@simple.dallas.tx.us) or current maintainer (Chris Lindell,
clindell@users.sourceforge.net) an email.