This is webmagick.info, produced by makeinfo version 4.0 from
webmagick.texinfo.

INFO-DIR-SECTION WebMagick Image Web Generator
START-INFO-DIR-ENTRY
* WebMagick: (webmagick.info).          WebMagick Image Web Generator
END-INFO-DIR-ENTRY

   This file documents WebMagick, a package which supports making image
collections available on the Web. It recurses through directory trees,
building HTML pages, imagemap files, and client-side/server-side maps to
allow the user to navigate through collections of thumbnail images
(somewhat similar to `xv''s Visual Schnauzer) and select the image to
view with a mouse click.

   This work may be used for any purpose, public or private, provided
that this work or derivations thereof are attributed to its original
authors.

   Copyright (C) 1997-2001 Bob Friesenhahn
(bfriesen@simple.dallas.tx.us)


File: webmagick.info,  Node: Top,  Next: Introduction,  Prev: (dir),  Up: (dir)

WebMagick
*********

   WebMagick is a package which supports making image collections
available on the Web. It recurses through directory trees, building
HTML pages, imagemap files, and client-side/server-side maps to allow
the user to navigate through collections of thumbnail images and select
the image to view with a mouse click.

* Menu:

* Introduction::                WebMagick basics
* General::                     Options that control basic processing
* Directory Paths::             Directory path options
* File Names::                  File name options
* Server-Side Imagemaps::       Server-side imagemap options
* Thumbnail Caching::           Thumbnail caching options
* Montage Options::             Montage (thumbnail page) options
* HTML Options::                HTML generation options
* String Customization::		Customizing (localizing) displayed strings
* Authors::                     WebMagick maintainer and friends
* Obtaining WebMagick::         Where to obtain WebMagick and the
                                packages it requires
* Installation::                Installing WebMagick
* Option Index::                Option variable index
* Argument Index::              Command-line argument index
* Concept Index::               Concept index

 --- The Detailed Node Listing ---

General

* Display Help::                List options
* Source Directory::            Specify source directory
* Verbose Output::              Display progress verbosely
* Debug Output::                Display debug messages
* Sub-Directory Processing::    Control sub-directory processing
* Forcing Output::              Override WebMagick's work avoidance
                                algorithms

Sub-Directory Processing

* Recursion::                   Control recursion into sub-directories
* Prune Directory::             Skip sub-directory and its children
* Ignore Directory::            Skip generating output for directory
* Ignore FrontPage::            Ignore FrontPage directories

Forcing Output To Be Generated

* Force Cache::                 Force cached thumbnails to be updated
* Force HTML::                  Force generated HTML to be updated
* Force Montage::               Force thumbnail montages to be updated

Paths

* URL Computation::             Define how URLs are generated

URL Computation

* Server Root Path::            Location of server's root
* Root Prefix::                 URL prefix to server's root
* Icon Location::               Specify offset to WebMagick icons

File Names

* Icon File Names::             Specify icon and background file names
* Index File Base Name::        Specify base name for visible HTML index
* README File Name::            Specify filename for directory README
* Page Index File Name::        Specify base name for per-page HTML
* Directory Title Xref::        Specify filename that contains directory
                                titles

Server-Side Imagemaps

* Imagemap Program::            Specify URL to server-side imagemap program
* Imagemap Type::               Specify server-side imagemap type

Thumbnail Caching

* Caching::                     Enable thumbnail caching
* Cache Directory::             Specify thumbnail cache directory name
* Cache Thumbnail Format::      Specify thumbnail image format
* Cache Thumnail Geometry::     Specify thumbnail image geometry
* Cache Minimum Image Size::    Specify cross-over point before trying JPEG

Montage Options

* Montage Anatomy::             The Anatomy of a montage
* Montage Geometry::            Specify montage geometry
* Montage Format::              Specify montage format
* Montage Colors::              Specify montage colors
* Thumbnail Imaging::           Specify montage thumbnail imaging options
* Thumbnail Label Options::     Specify montage thumbnail label options
* Thumbnail Hooks::             Specify pre/postprocessing options for
                                thumbnails

Montage Geometry

* Columns::                     Specify montage columns
* Rows::                        Specify montage rows

Montage Image Format

* GIF/JPEG Transition Point::   Specify GIF/JPEG size transition point
* Force GIF Format::            Always use GIF format for montages

Montage Colors

* Thumb Foreground Color::      Specify thumbnail foreground color
* Thumb Background Color::      Specify thumbnail background color
* Thumb Trans Color::           Specify thumbnail transparent color
* Thumb Frame Color::           Specify thumbnail frame color
* Border Color::                Specify thumbnail border color
* Netscape Color Cube::         Quantize montage to Netscape 216 color cube

Thumbnail Imaging

* Thumb Frame::                 Enable decorative frames around thumbnails
* Thumb Shadows::               Enable decorative shadows under thumbnails
* Border Width::                Specify thumbnail border width
* Thumb Background Texture::    Specify montage background image
* Thumb Geometry::              Specify thumbnail geometry
* Thumb Gravity::               Specify thumbnail placement
* Composition Algorithm::       Specify thumbnail imaging algorithm
* Zoom Filter::                 Specify zoom filter to use for reductions

Thumbnail Label Options

* Thumbnail Title Xref::        Specify thumbnail titles
* Thumb Label Format::          Specify thumbnail label format
* Thumb Label Width::           Specify thumbnail label truncation width
* Thumb Label Font::            Specify thumbnail label font

Thumbnail Processing Hooks

* Read Fail Hook::              Specify image read-failure hook
* Thumb Post Hook::             Specify thumbnail pre-processing hook
* Thumb Pre Hook::              Specify thumbnail post-processing hook

HTML Options

* HTML Content::                Specify HTML page contents
* Text Colors::                 Specify HTML text colors
* HTML Link Colors::            Specify HTML link colors
* Frame Options::               Specify frame options
* Meta Tags::                   Specify HTML meta tags

HTML Content

* Allow Configuration::         Allow user configuration
* JavaScript Mode::             Enable JavaScript output
* Table Mode::                  Use tables instead of imagemaps
* README File Treatment::       Control README file visibility
* Address Info::                Specify an address field
* Anonymize::                   Protect the author's reputation
* Page Header::                 Specify HTML page header
* Page Title::                  Specify HTML page title
* Stylesheet::                  Specify a URL to a Cascading Style Sheet
* Dir Page Fmt (No Frames)::    Directory page template (unframed)
* Dir Page Fmt (Framed)::       Directory page template (framed)
* Per-Image HTML::

Per-Image HTML

* Enable Per-image HTML::
* Per-image HTML extension::
* Per-image HTML Nav Buttons::
* Per-image Picture Title::
* Per-image Picture Title Start HTML::
* Per-image Picture Title End HTML::
* Default Frame Target::
* Extra Top HTML::
* Extra Bottom HTML::

Text Colors

* Thumb Background::            Specify thumbnail page background color
* Thumb Foreground::            Specify thumbnail page foreground color
* Dir Foreground Color::        Specify directory page foreground color
* Dir Background Color::        Specify directory page background color

HTML Link Colors

* Thumb Active Link Color::     Specify thumbnail page active link color
* Thumb Un-visited Color::      Specify thumbnail page un-visited link color
* Thumb Visited Color::         Specify thumbnail page visited link color
* Dir Active Color::            Specify directory page active link color
* Dir Un-Visited Color::        Specify directory page un-visited link color
* Dir Visited Color::           Specify directory page visited link color

Frame Options

* Frames::                      Enable frames
* Frame Borders::               Enable frame borders
* Frame Border Thickness::      Specify frame border thickness
* Frame Margin Height::         Specify frame margin height
* Frame Margin Width::          Specify frame margin width
* Frame Style::                 Specify frame style (layout)

HTML Meta Tags

* Meta Author::                 Specify AUTHOR meta-tag
* Meta Charset::                Specify CHARSET meta-tag
* Meta Classification::         Specify CLASSIFICATION meta-tag
* Meta Description::            Specify DESCRIPTION meta-tag
* Meta Expires::                Specify EXPIRES meta-tag
* Meta Key-Words::              Specify KEYWORDS meta-tag


Installing WebMagick

* Basic Installation::
* Installation Names::


File: webmagick.info,  Node: Introduction,  Next: General,  Prev: Top,  Up: Top

Introduction
************

   WebMagick creates HTML index files and imagemaps corresponding to a
directory of image files. WebMagick is ideal for making large image
collections available on the net or for just using your Web browser for
browsing images.

   Configuration options are derived from either the command line
(options prefixed with '-', '-', or '+'), configuration file ($opt_
options), or internal defaults ($opt_ options). Some arguments (like
X11 font specifications) seem to confuse PERL's getopt function. When
this happens, try using the syntax `--option=arg' to avoid any confusion
caused by a space.

   The default configuration file name is `.webmagickrc'.
Configuration files are written in PERL syntax and are sourced via
PERL's eval statement. When WebMagick is executed, it first reads files
listed in the @global_option_files array (`/etc/webmagickrc' and
`$HOME/.webmagickrc' by default). When a directory is processed,
WebMagick will process any `.webmagickrc' files found in the path from
the server's root directory (specified by `$opt_rootpath' (*note Server
Root Path::)) to the directory being processed. All configuration
options are additive.


Evaluation order (inverse of precedence) is as follows :

  1. Files listed in @global_option_files

     (default `/etc/webmagickrc' and `$HOME/.webmagickrc')

  2. Command line options

  3. Per directory .webmagickrc files.

     Webmagickrc files are evaluated in path order from server root to
     current directory. This allows sub-directories to "inherit" the
     configuration of parent directories.

Each directory is processed with items 1 & 2 already complete.


   In general, WebMagick's defaults produce nice output. However, the
options `$opt_prefixpath' (*note Root Prefix::), `$opt_rootpath' (*note
Server Root Path::), `$opt_iconpath' (*note Icon Location::),
`$opt_htimage' (*note Imagemap Program::), and `$opt_maptype' (*note
Imagemap Type::) must be configured on a per-site basis so please read
the documentation on these options and perform the required
configuration before executing the program.

   A key configuration/installation issue is that WebMagick depends on
the image files being on the same filesystem as the icons. The reason
for this limitation is that this allows WebMagick to determine the
mapping between the physical disk and the server's URLs. If someone
knows a better algorithm than this one, please let the author know.

   By default the output files of WebMagick for the first page are as
follows (second page replace '1' with '2', etc.):

`index.html'
     Main (default server index) HTML index file.

`indexjs.html'
     Javascript master index file (name currently hard-coded).

`.cache'
     Thumbnail cache directory

`.indexdir.html'
     HTML page that displays directory frame

`.indexjs.html'
     HTML file to load JavaScript source into browser.

`.index.pl'
     WebMagick status file (in PERL format). Re-generated per run. May
     be used by other programs to produce additional HTML output.

`.index.js'
     JavaScript variables file (similar to status file but in
     JavaScript).

`.index1.html'
     HTML page that displays thumbnail frame

`.index1.gif'
     Montaged images (thumbnails) in GIF format

`.index1.jpg'
     Montaged images (thumbnails) in JPEG format

`.index1.map'
     Server-side imagemap (clickable map) file


File: webmagick.info,  Node: General,  Next: Directory Paths,  Prev: Introduction,  Up: Top

General
*******

* Menu:

* Display Help::                List options
* Source Directory::            Specify source directory
* Verbose Output::              Display progress verbosely
* Debug Output::                Display debug messages
* Sub-Directory Processing::    Control sub-directory processing
* Forcing Output::              Override WebMagick's work avoidance
                                algorithms


File: webmagick.info,  Node: Display Help,  Next: Source Directory,  Prev: General,  Up: General

Display Help
============

`Variable:'
     `$opt_help=1'

`Argument:'
     `--help'

   Display usage message.


File: webmagick.info,  Node: Source Directory,  Next: Verbose Output,  Prev: Display Help,  Up: General

Specify Source Directory
========================

`Variable:'
     $opt_srcdir=path

`Argument:'
     -srcdir path

   Image directory to process or start recursion at (default current
directory). Specify this option (usually on the command line) if the
directory you want to process is not the current directory.  This simply
causes WebMagick to change directories before starting processing.


File: webmagick.info,  Node: Verbose Output,  Next: Debug Output,  Prev: Source Directory,  Up: General

Enable Verbose Output
=====================

`Variable:'
     $opt_verbose=1

`Argument:'
     -verbose

   Normally WebMagick prints only the directory names for directories
it processes. Selecting the verbose option displays the number of
images and sub-directories in the directory as well as the number of
pages to be generated, and the current page number.  It will also show
the current image index WebMagick is currently creating as a progress
report.


File: webmagick.info,  Node: Debug Output,  Next: Sub-Directory Processing,  Prev: Verbose Output,  Up: General

Enable Debug Output
===================

`Variable:'
     $opt_debug=1

`Argument:'
     -debug

   Print debugging messages.


File: webmagick.info,  Node: Sub-Directory Processing,  Next: Forcing Output,  Prev: Debug Output,  Up: General

Sub-Directory Processing
========================

* Menu:

* Recursion::                   Control recursion into sub-directories
* Prune Directory::             Skip sub-directory and its children
* Ignore Directory::            Skip generating output for directory
* Ignore FrontPage::            Ignore FrontPage directories


File: webmagick.info,  Node: Recursion,  Next: Prune Directory,  Prev: Sub-Directory Processing,  Up: Sub-Directory Processing

Recurse Sub-Directories
-----------------------

`Variable:'
     $opt_recurse=1

`Argument:'
     -recurse

   Recurse directory tree (default off). The default is to only process
the current directory, generating appropriate links for sub-directories
and the parent directory. Selecting this option causes WebMagick to
recurse through sub-directories as well.


File: webmagick.info,  Node: Prune Directory,  Next: Ignore Directory,  Prev: Recursion,  Up: Sub-Directory Processing

Prune Directory
---------------

`Variable:'
     $opt_prune=1

   If `$opt_prune' is set in a directory's `.webmagickrc' file (default
off), then sub-directories below that directory will not be processed by
WebMagick when operating in the recursive mode.  *Note $opt_ignore:
Ignore Directory, for details on how to skip a directory rather than
prune it.


File: webmagick.info,  Node: Ignore Directory,  Next: Ignore FrontPage,  Prev: Prune Directory,  Up: Sub-Directory Processing

Ignore Directory
----------------

`Variable:'
     $opt_ignore=1

   If `$opt_ignore' is set in a directory's `.webmagickrc' file (default
off), then that directory will not be processed (but will still be
linked to). If recursion is enabled, then recursion will continue into
any sub-directories. This provides support for subdirectories with HTML
files which are generated by other means.  also `$opt_indexname'.


File: webmagick.info,  Node: Ignore FrontPage,  Prev: Ignore Directory,  Up: Sub-Directory Processing

Ignore FrontPage
----------------

`Variable:'
     $opt_ignorefp=1

`Argument:'
     -ignorefp

   If `$opt_ignorefp' is used, sub-directories with names like _vti_bin
will be ignored. MS FrontPage creates these directories which begin with
an underscore followed by a lowercased letter (_[a-z]).


File: webmagick.info,  Node: Forcing Output,  Prev: Sub-Directory Processing,  Up: General

Forcing Output To Be Generated
==============================

   WebMagick uses algorithms similar in concept to those used by `make'
to try to only do required processing.  Occasionally due to
modification of a parameter that WebMagick doesn't track or due to
external modification of file modification times, WebMagick will skip
doing an update that it should have done. In these cases, options are
provided to force WebMagick to perform a task.

* Menu:

* Force Cache::                 Force cached thumbnails to be updated
* Force HTML::                  Force generated HTML to be updated
* Force Montage::               Force thumbnail montages to be updated


File: webmagick.info,  Node: Force Cache,  Next: Force HTML,  Prev: Forcing Output,  Up: Forcing Output

Force Generation Of Thumbnail Cache
-----------------------------------

`Variable:'
     $opt_forcecache=1

`Argument:'
     -forcecache

   Force cache files to be generated (default off).  Without this
option, WebMagick will only re-generate cache files if the source file
is newer.  In order for this option to take effect, a montage must be
generated and `$opt_cache' must be set to a non-zero value.  The
-forcemontage option be used to force montages.


File: webmagick.info,  Node: Force HTML,  Next: Force Montage,  Prev: Force Cache,  Up: Forcing Output

Force Generation Of HTML Files
------------------------------

`Variable:'
     $opt_forcehtml=1

`Argument:'
     -forcehtml

   Force HTML files to be generated (default off).  Without this option,
WebMagick will only re-generate HTML files as required.


File: webmagick.info,  Node: Force Montage,  Prev: Force HTML,  Up: Forcing Output

Force Generation Of Montage
---------------------------

`Variable:'
     $opt_forcemontage=1

`Argument:'
     -forcemontage

   Force montage (default false).  Without this option, WebMagick will
only re-generate montages as required.


File: webmagick.info,  Node: Directory Paths,  Next: File Names,  Prev: General,  Up: Top

Paths
*****

* Menu:

* URL Computation::             Define how URLs are generated


File: webmagick.info,  Node: URL Computation,  Prev: Directory Paths,  Up: Directory Paths

URL Computation
===============

* Menu:

* Server Root Path::            Location of server's root
* Root Prefix::                 URL prefix to server's root
* Icon Location::               Specify offset to WebMagick icons


File: webmagick.info,  Node: Server Root Path,  Next: Root Prefix,  Prev: URL Computation,  Up: URL Computation

Specify Server Root Path
------------------------

`Variable:'
     $opt_rootpath=path

`Argument:'
     -rootpath path

   Absolute path to server root directory (NCSA/Apache DocumentRoot) or
the users Home page directory. This must be an absolute path (starting
with `/') to the top of the WWW directory tree WebMagick will be
processing in.  If this value is specified incorrectly, WebMagick will
generate incorrect URLs.


File: webmagick.info,  Node: Root Prefix,  Next: Icon Location,  Prev: Server Root Path,  Up: URL Computation

Specifying Root Prefix
----------------------

`Variable:'
     $opt_prefixpath=path

`Argument:'
     -prefixpath path

   The prefix to prepend to all URLs to specify the WWW location of
`$opt_rootpath' (*note Server Root Path::).  For directories under the
WWW server's root directory (`/') this is a empty string (""). For a
user's personal pages this is the URL path to their home pages (usually
`/~username' equating to `~/public_html', but may be configured
differently on your server).

   If a relative URL can be computed then this option is not actually
used. It however must be used if the WebMagick icon images are not in
the same logical WWW directory tree as the directories WebMagick is
processing. (See the next option).


File: webmagick.info,  Node: Icon Location,  Prev: Root Prefix,  Up: URL Computation

Specifying WebMagick Icon Location
----------------------------------

`Variable:'
     $opt_iconpath=path

`Argument:'
     -iconpath path

   This is the relative path from the top of the WWW directory tree
specified in `$opt_rootpath' (*note Server Root Path::). If this value
is specified incorrectly then WebMagick will generate incorrect URLs
for its icons.


File: webmagick.info,  Node: File Names,  Next: Server-Side Imagemaps,  Prev: Directory Paths,  Up: Top

File Names
**********

* Menu:

* Icon File Names::             Specify icon and background file names
* Index File Base Name::        Specify base name for visible HTML index
* README File Name::            Specify filename for directory README
* Page Index File Name::        Specify base name for per-page HTML
* Directory Title Xref::        Specify filename that contains directory
                                titles


File: webmagick.info,  Node: Icon File Names,  Next: Index File Base Name,  Prev: File Names,  Up: File Names

Specifying Icon File Names
==========================

`Variable:'
     %opt_icons=(  'id', 'filename', .... ;

   This is a hash table of all the images used directly by WebMagick
and located in the `$opt_iconpath' (*note Icon Location::) directory.
The elments are pairs of icon `id's and the filename of the image. The
`id's currently used internally by `WebMagick' are :- `background',
`dirbackground', `prev', `next', `next_grey', `up', `help', and `ball'.
These IDs are used as follows:

`background'
     thumbnail frame background image

`dirbackground'
     directory frame background image

`prev'
     link to previous page

`next'
     link to next page

`next_gray'
     link to next page (when there isn't one)

`up'
     link to parent directory up

`help'
     link to help Readme File (if it exists)

`ball'
     a decorative ball.  If no definition exists (array element is left
     undefined) then the ball is not displayed in preference to
     unadorned text.

   By default the `background' and `dirbackground' options are
undefined which results in no background images being defined.

   Other images can also be defined in the hash table and WebMagick
will automatically process those images along with the images it uses,
to generate the icon URL and size infomation. This information can then
be used in the various special formating options to add extra, or
special purpose links.

   An alternative way to define entries (particularly useful in
directory .webmagickrc files) is to define (or undefine) individual
hash table entries.

   Use syntax similar to

     $opt_icons{'background'} = 'background.gif';

   to add a background image to the thumbnail page or override an
existing definition.

   Use syntax similar to

     undef $opt_icons{'background'};

   to undefine an existing definition for the image corresponding to
`background'.  This can be useful if the default is to display a
background image but you want to turn off the background image for a
particular sub-directory tree.


File: webmagick.info,  Node: Index File Base Name,  Next: README File Name,  Prev: Icon File Names,  Up: File Names

Index File Base Name
====================

`Variable:'
     $opt_indexname=filename

`Argument:'
     -indexname filename

   Base name of the master index files (default server index), usually
set to `index.html'. This is also the filename WebMagick will look for
in sub-directories and parent directory `.webmagickrc' files as the
document to make links to.

   EG: If a directory is not processed by WebMagick, by either never
running WebMagick on that directory, or the option `$opt_ignore' has
been set, then setting `$opt_indexname' will specify the document
WebMagick created index files of OTHER directories should link to.

   If you do not want WebMagick to ever link to this directory then
setting the option, `$opt_indexname', to "NOLINK" will will prevent
WebMagick index files in other directories from linking to this
directory.

   If you want WebMagick to entirely ignore a particular directory tree,
even during recursion of the surrounding directories, then you can use
the following options in its "`.webmagickrc'" file:

     #
     # .webmagickrc -- WebMagick is not to process or even link
     # to this directory tree
     #
     $opt_indexname = 'NOLINK'; # Do not link to this directory
     $opt_ignore    = 1;        # Do not generate WebMagick image indexes
     $opt_prune     = 1;        # Don't recurse into sub-directories


File: webmagick.info,  Node: README File Name,  Next: Page Index File Name,  Prev: Index File Base Name,  Up: File Names

Specifying README File Name
===========================

`Variable:'
     $opt_readme=filename

`Argument:'
     -readme filename

   Name of directory information file (default `README.html'). If this
file exists in the directory, then it will be displayed in preference
to the first page of images and a link will appear in the directory
frame which links to the image index. Typically the contents of this
file describe the images to be viewed.


File: webmagick.info,  Node: Page Index File Name,  Next: Directory Title Xref,  Prev: README File Name,  Up: File Names

Page Index File Name
====================

`Variable:'
     $opt_pageindexname=string

`Argument:'
     -pageindexname string

   Base name of page-related index files (default `.index'). This name
is used as the prefix for all generated files except for the main index
file. The default naming creates these as hidden files (UNIX
convention).


File: webmagick.info,  Node: Directory Title Xref,  Prev: Page Index File Name,  Up: File Names

Specifying Sub-Directory Titles
===============================

`Variable:'
     $opt_dirindexname=filename

`Argument:'
     -dirindexname filename

   Specify the file name to contain the directory-name to title
cross-reference for naming sub-directories (default file name
`.dirindex'). If this file exists, then _dirtext_ will replace
`dirname' if `dirname' is found in the file. This provides the ability
to use user-specified text rather than actual sub-directory names. The
order specified by this file is used to sort directory names.  If an
entry for a directory is not in this file, then that directory name is
sorted alphbetically with relation to the other directory names.

   The format of the file is:

     dirname  dirtext

   With _dirname_ representing the directory name and _dirtext_
representing the replacement link text.

   It is wise to limit the length of _dirtext_ to fit within the
limitations of the directory frame.


File: webmagick.info,  Node: Server-Side Imagemaps,  Next: Thumbnail Caching,  Prev: File Names,  Up: Top

Server-Side Imagemaps
*********************

* Menu:

* Imagemap Program::            Specify URL to server-side imagemap program
* Imagemap Type::               Specify server-side imagemap type


File: webmagick.info,  Node: Imagemap Program,  Next: Imagemap Type,  Prev: Server-Side Imagemaps,  Up: Server-Side Imagemaps

Imagemap Program
================

`Variable:'
     $opt_htimage=path

`Argument:'
     -htimage path

   Specify imagemap CGI program URL (set to " for none). Older servers
(e.g. CERN and old NCSA) require an external program to handle
server-side imagemaps. These programs are usually supplied with a full
URL to the referenced file. Newer servers have server-side imagemap
support built-in and can accept URLs relative to the current directory.
If you have a modern server, then specify this value as a null string
(just hit <RETURN> when running the configure script).


File: webmagick.info,  Node: Imagemap Type,  Prev: Imagemap Program,  Up: Server-Side Imagemaps

Imagemap Type
=============

`Variable:'
     $opt_maptype=maptype

`Argument:'
     -maptype maptype

   Specify server-side map type (set to "ncsa" or "cern"). NCSA and
Apache servers require "ncsa". CERN requires "cern".  Phttpd can use
either format.

   NCSA format looks similar to:

     default .index1.html
     rect scooby1.gif 440,0 549,128

   while CERN format looks similar to:

     default .index1.html
     rect (440,0) (549,128) scooby1.gif


File: webmagick.info,  Node: Thumbnail Caching,  Next: Montage Options,  Prev: Server-Side Imagemaps,  Up: Top

Thumbnail Caching
*****************

* Menu:

* Caching::                     Enable thumbnail caching
* Cache Directory::             Specify thumbnail cache directory name
* Cache Thumbnail Format::      Specify thumbnail image format
* Cache Thumnail Geometry::     Specify thumbnail image geometry
* Cache Minimum Image Size::    Specify cross-over point before trying JPEG


File: webmagick.info,  Node: Caching,  Next: Cache Directory,  Prev: Thumbnail Caching,  Up: Thumbnail Caching

Enable Caching
==============

`Variable:'
     $opt_cache

`Argument:'
     -cache

   Enable thumbnail caching. This is good for a 5X reduction in
processing time when a single image is added or removed from a
directory since thumbnails are cached in reduced form.

   As an added benefit, WebMagick can share its cache with John
Bradley's `xv' image manipulation program (Visual Schnauzer feature) if
configuration values are set as follows:

     $opt_cacheformat= 'P7';
     $opt_cachegeom  = 80x60;
     $opt_cachedir   = '.xvpics';

   Sharing the cache with `xv' is only feasable if all of the images
being cached are compatable with `xv' (ImageMagick supports many more
formats than `xv'). A further drawback of sharing the cache with `xv'
is that `xv' is limited to thumbnails with a geometry of 80x60 which
may be small for your tastes (I prefer larger).


File: webmagick.info,  Node: Cache Directory,  Next: Cache Thumbnail Format,  Prev: Caching,  Up: Thumbnail Caching

Cache Directory
===============

`Variable:'
     $opt_cachedir=dirspec

`Argument:'
     -cachedir dirspec

   Specify subdirectory name to cache thumbnails in (default `.cache').


File: webmagick.info,  Node: Cache Thumbnail Format,  Next: Cache Thumnail Geometry,  Prev: Cache Directory,  Up: Thumbnail Caching

Cache Thumbnail Format
======================

`Variable:'
     $opt_cacheformat=imageformat

`Argument:'
     -cacheformat imageformat

   Specify the format that cached thumbnails are saved in. Can be any
format that ImageMagick knows how to read and write. The default is
'JPEG' which works well for photorealistic images.


File: webmagick.info,  Node: Cache Thumnail Geometry,  Next: Cache Minimum Image Size,  Prev: Cache Thumbnail Format,  Up: Thumbnail Caching

Cache Thumbnail Geometry
========================

`Variable:'
     $opt_cachegeom=geometry

`Argument:'
     -cachegeom geometry

   Specifies the geometry specification for cached thumbnails.  The
default is to use the value specified by `$opt_thumbgeometry' (*note
Thumb Geometry::).  If a smaller value is used, there will be more
unused space around the montaged thumbnails. Use of a larger value than
the thubnail geometry is to be avoided because the cached thumbnail
will still have to be reduced for the montage, costing both time and
thumbnail quality.


File: webmagick.info,  Node: Cache Minimum Image Size,  Prev: Cache Thumnail Geometry,  Up: Thumbnail Caching

Cache Minimum Image Size
========================

`Variable:'
     $opt_cachemin=minsize

`Argument:'
     -cachemin minsize

   Specifies the original Image size (in total pixels) over which
caching will be used. For images smaller than this size, WebMagick will
use the original image in the Montage and no thumbnail will be cached.
The default value is 60,000 which is equivalent to a 300 x 200 image.

   Selecting a value for this option is a judgement call based on space
vs time.  If a small value is selected, the initial run will be slower
and more disk space will be consumed by thumbnails.  However, subsequent
updates should be faster since more thumbnails are already reduced.  If
a large value is selected, then less disk space will be consumed, the
first pass will be faster, and subsequent passes will be slower.


File: webmagick.info,  Node: Montage Options,  Next: HTML Options,  Prev: Thumbnail Caching,  Up: Top

Montage Options
***************

* Menu:

* Montage Anatomy::             The Anatomy of a montage
* Montage Geometry::            Specify montage geometry
* Montage Format::              Specify montage format
* Montage Colors::              Specify montage colors
* Thumbnail Imaging::           Specify montage thumbnail imaging options
* Thumbnail Label Options::     Specify montage thumbnail label options
* Thumbnail Hooks::             Specify pre/postprocessing options for
                                thumbnails


File: webmagick.info,  Node: Montage Anatomy,  Next: Montage Geometry,  Prev: Montage Options,  Up: Montage Options

The Anatomy Of A Montage
========================

Montage Layout
--------------

   A montage is a single image which is composed of thumbnail images
layed out in a grid.  The size of the montage image is determined by
the size of the individual thumbnails and the number of rows and
columns in the grid.

   The following figure shows a montage consisting of three columns and
two rows of thumbnails:

[ Please see printed or HTML version for this figure ]

The Anatomy Of A Thumbnail
--------------------------

Un-Framed Thumbnails
....................

   Un-framed thumbnails consist of four components: the thumbnail image,
the thumbnail border, an optional thumbnail shadow, and an optional
thumbnail label area.

[ Please see printed or HTML version for this figure ]

Framed Thumbnails
.................

   Framed thumbnails consist of four components: the thumbnail image,
the thumbnail frame, the thumbnail border, an optional thumbnail
shadow, and an optional thumbnail label area.

[ Please see printed or HTML version for this figure ]


File: webmagick.info,  Node: Montage Geometry,  Next: Montage Format,  Prev: Montage Anatomy,  Up: Montage Options

Montage Geometry
================

   The montage geometry specifies the size in rows and columns of the
generated thumbnail grid. Since a single montage is displayed per HTML
page, after the montage grid is full, a new page is started.  The
montage geometry combined with the thumbnail geometry determines the
total size of the montage image and therefore the size that the user's
web browser must be set to in order to view the entire montage.

   Setting the rows to a very large value (large enough that rows x
columns exceeds the number of images) results in a single HTML page
being generated.  The user can then use the browser's vertical scroll
bar to peruse the thumbnails.

* Menu:

* Columns::                     Specify montage columns
* Rows::                        Specify montage rows


File: webmagick.info,  Node: Columns,  Next: Rows,  Prev: Montage Geometry,  Up: Montage Geometry

Columns
-------

`Variable:'
     $opt_columns=number

`Argument:'
     -columns number

   Specify the montage columns (max). This is the maximum number of
thumbnail columns allowed per thumbnail row.


File: webmagick.info,  Node: Rows,  Prev: Columns,  Up: Montage Geometry

Rows
----

`Variable:'
     $opt_rows=number

`Argument:'
     -rows number

   Specify the montage rows (max). This is the maximum number of
thumbnail rows allowed per page.


File: webmagick.info,  Node: Montage Format,  Next: Montage Colors,  Prev: Montage Geometry,  Up: Montage Options

Montage Image Format
====================

* Menu:

* GIF/JPEG Transition Point::   Specify GIF/JPEG size transition point
* Force GIF Format::            Always use GIF format for montages


File: webmagick.info,  Node: GIF/JPEG Transition Point,  Next: Force GIF Format,  Prev: Montage Format,  Up: Montage Format

GIF/JPEG Transition Point
-------------------------

`Variable:'
     $opt_maxgif=number

`Argument:'
     -maxgif number

   Specify the maximum size of GIF imagemap before trying JPEG (default
30000).  This is an optimization which tries to avoid the JPEG
conversion step. When indexing true or deep-color images, JPEG usually
leads to a smaller montage imagemap file.

   Even if a JPEG image is generated, the smaller of the two images is
selected for use and the larger one is deleted to save disk space.


File: webmagick.info,  Node: Force GIF Format,  Prev: GIF/JPEG Transition Point,  Up: Montage Format

Force GIF Format
----------------

`Variable:'
     $opt_forcegif=1

`Argument:'
     -forcegif

   Force GIF imagemaps to be generated (default off). This avoids the
possible generation of JPEG format imagemaps when the GIF file is large
(over 30K). The primary reason for using this option is because GIF
supports image transparancy while JPEG does not, leading to a possibly
more attractive display when using GIF format imagmaps. The drawbacks of
forcing GIF format are larger imagemap files (often two or three times
the size of JPEG when montaging true or deep-color images) and the
limited color depth (256 colors) of the GIF format.


File: webmagick.info,  Node: Montage Colors,  Next: Thumbnail Imaging,  Prev: Montage Format,  Up: Montage Options

Montage Colors
==============

* Menu:

* Thumb Foreground Color::      Specify thumbnail foreground color
* Thumb Background Color::      Specify thumbnail background color
* Thumb Trans Color::           Specify thumbnail transparent color
* Thumb Frame Color::           Specify thumbnail frame color
* Border Color::                Specify thumbnail border color
* Netscape Color Cube::         Quantize montage to Netscape 216 color cube


File: webmagick.info,  Node: Thumb Foreground Color,  Next: Thumb Background Color,  Prev: Montage Colors,  Up: Montage Colors

Thumbnail Foreground Color
--------------------------

`Variable:'
     $opt_thumbforeground=colorspec

`Argument:'
     -thumbforeground colorspec

   Specify the montage foreground color.  This color is used as the
color for thumbnail label text.


File: webmagick.info,  Node: Thumb Background Color,  Next: Thumb Trans Color,  Prev: Thumb Foreground Color,  Up: Montage Colors

Thumbnail Background Color
--------------------------

`Variable:'
     $opt_thumbbackground=colorspec

`Argument:'
     -thumbbackground colorspec

   Specifies the background color that thumbnails are imaged upon.


File: webmagick.info,  Node: Thumb Trans Color,  Next: Thumb Frame Color,  Prev: Thumb Background Color,  Up: Montage Colors

Thumbnail Transparent Color
---------------------------

`Variable:'
     $opt_thumbtransparent=colorspec

`Argument:'
     -thumbtransparent colorspec

   Specify a montage color to set transparent. Usually should be set the
same as the background color `$opt_colorback' (*note Thumb Background
Color::) of the imagemap page. GIF format imagemaps use the transparent
color directly while JPEG format imagemaps may approximate
"transparency" by setting the imagemap background color to the same
color used as the background for HTML pages. This approximation becomes
less useful for clients with shallow colormaps.


File: webmagick.info,  Node: Thumb Frame Color,  Next: Border Color,  Prev: Thumb Trans Color,  Up: Montage Colors

Thumbnail Frame Color
---------------------

`Variable:'
     $opt_thumbframecolor=colorspec

`Argument:'
     -thumbframecolor colorspec

   Specify the thumbnail frame color (only applicable if frames are
enabled).


File: webmagick.info,  Node: Border Color,  Next: Netscape Color Cube,  Prev: Thumb Frame Color,  Up: Montage Colors

Thumbnail Frame Border Color
----------------------------

`Variable:'
     $opt_thumbframebgcolor=colorspec

`Argument:'
     -thumbframebgcolor colorspec

   Specifies the background color within the thumbnail frame.  Ignored
if there is no frame.


File: webmagick.info,  Node: Netscape Color Cube,  Prev: Border Color,  Up: Montage Colors

Quantize To Netscape Color Cube
-------------------------------

`Variable:'
     $opt_mapnetscape

`Argument:'
     -mapnetscape

   Re-map the montage colors to the Netscape 216-color cube. Netscape
maps colors to a fixed 216-color cube on PseudoColor color displays.
Using this option allows you to ensure that Netscape doesn't dither or
re-map your colors when used with common PseudoColor displays and the
images may be smaller. The drawback to using this option is that the
color quality will be significantly decreased on True and DirectColor
displays or when using browsers that don't use the 216-color cube
technique.

   When using image transparency, make sure that the transparent color
is selected from one of the 216 "standard" colors or transparency won't
work.


File: webmagick.info,  Node: Thumbnail Imaging,  Next: Thumbnail Label Options,  Prev: Montage Colors,  Up: Montage Options

Thumbnail Imaging
=================

* Menu:

* Thumb Frame::                 Enable decorative frames around thumbnails
* Thumb Shadows::               Enable decorative shadows under thumbnails
* Border Width::                Specify thumbnail border width
* Thumb Background Texture::    Specify montage background image
* Thumb Geometry::              Specify thumbnail geometry
* Thumb Gravity::               Specify thumbnail placement
* Composition Algorithm::       Specify thumbnail imaging algorithm
* Zoom Filter::                 Specify zoom filter to use for reductions


File: webmagick.info,  Node: Thumb Frame,  Next: Thumb Shadows,  Prev: Thumbnail Imaging,  Up: Thumbnail Imaging

Enable Thumbnail Frame
----------------------

`Variable:'
     $opt_thumbframe=geometry

`Argument:'
     -thumbframe geometry

   Specify the geometry specification for frame to place around
thumbnail. If no frame is desired then the string "false" should be
specified. The specified geometry values are in _addition_ to the
thumbnail geometry. For example, a frame geometry of '8x8' places an 8
pixel frame around the image.


File: webmagick.info,  Node: Thumb Shadows,  Next: Border Width,  Prev: Thumb Frame,  Up: Thumbnail Imaging

Enable Thumbnail Shadows
------------------------

`Variable:'
     $opt_thumbshadow=boolean

`Argument:'
     -thumbshadow boolean

   Set to string "true" or "false" to control the use of decorative
shadows around image thumbnails (or frames if enabled). The default is
"false".


File: webmagick.info,  Node: Border Width,  Next: Thumb Background Texture,  Prev: Thumb Shadows,  Up: Thumbnail Imaging

Thumbnail Frame Border Width
----------------------------

`Variable:'
     $opt_thumbborderwidth=borderwidth

   Specify the border (in pixels) to place between a thumbnail and its
surrounding frame.  This option only takes effect if thumbnail frames
are enabled and the thumbnail geometry specification doesn't also
specify the thumbnail border width.


File: webmagick.info,  Node: Thumb Background Texture,  Next: Thumb Geometry,  Prev: Border Width,  Up: Thumbnail Imaging

Thumbnail Background Texture
----------------------------

`Variable:'
     $opt_thumbtexture=texturespec

`Argument:'
     -thumbtexture texturespec

   Specify a texture to use as montage background.  The built-in
textures "granite:" and "plasma:" are available.  A texture is the same
aas a background image. For example:

   Granite texture:

     $opt_thumbtexture='granite:';

   Plasma texture:

     $opt_thumbtexture='plasma:blue-yellow';

   Image file texture:

     $opt_thumbtexture='vibrant.gif';


File: webmagick.info,  Node: Thumb Geometry,  Next: Thumb Gravity,  Prev: Thumb Background Texture,  Up: Thumbnail Imaging

Thumbnail Geometry
------------------

`Variable:'
     $opt_thumbgeometry=geometry

`Argument:'
     -thumbgeometry geometry

   Specify image thumbnail geometry. Thumbnail geometry is specifed in
the form:

      <width>x<height>+<borderwidth>+<borderheight>{!}{<}{>}

   Specify the size and scaling options for thumbnail images (default
'106x80+2+2>').

   The following description is extracted verbatim from the montage
manual page regarding the treatment of this option:

   By default, the width and height are maximum values.  That is, the
image is expanded or contracted to fit the width and height value while
maintaining the aspect ratio of the image.  Append an exclamation point
to the geometry to force the image size to exactly the size you specify.
For example, if you specify 640x480! the image width is set to 640
pixels and height to 480.  If only one factor is specified, both the
width and height assume the value.

   Use > to change the dimensions of the image only if its size exceeds
the geometry specification.  Use < to resize the image only if its
dimensions is less than the geometry specification.  For example, if
you specify 640x480> and the image size is 512x512, the image size does
not change.  However, if the image is 1024x1024, it is resized to
640x480.

   Each image is surrounded by a border whose size in pixels is
specified as <border width> and <border height> and whose color is the
background color.


File: webmagick.info,  Node: Thumb Gravity,  Next: Composition Algorithm,  Prev: Thumb Geometry,  Up: Thumbnail Imaging

Thumbnail Gravity
-----------------

`Variable:'
     $opt_thumbgravity=direction

`Argument:'
     -thumbgravity direction

   Specify the thumbnail positioning within the specified geometry
(`$opt_thumbgeometry' area. If the thumbnail is smaller in any
dimension than the geometry, then it will be placed according to this
specification. Available options are `NorthWest', `North', `NorthEast',
`West', `Center', `East' `SouthWest', `South', and `SouthEast'. Just as
with a map (at least those in the northern hemisphere) `North' is up
and `West' is left. The default is `Center' so that thumbnails are
centered in their grid.


File: webmagick.info,  Node: Composition Algorithm,  Next: Zoom Filter,  Prev: Thumb Gravity,  Up: Thumbnail Imaging

Thumbnail Composition Algorithm
-------------------------------

`Variable:'
     $opt_thumbcompose=operation

`Argument:'
     -thumbcompose operation

   Specify the image composition algorithm for thumbnails. This controls
the algorithm by which the thumbnail image is placed on the background.
Available options are (default `Replace'): `Over', `In', `Out', `Atop',
`Xor', `Plus', `Minus', `Add', `Subtract', `Difference', `Bumpmap',
`Replace', `MatteReplace', `Mask', `Blend', and `Displace'. Use of
`Over' is recommended for use with images that have transparency. This
option may have negative side-effects for images without transparency.


File: webmagick.info,  Node: Zoom Filter,  Prev: Composition Algorithm,  Up: Thumbnail Imaging

Thumbnail Zoom Filter
---------------------

`Variable:'
     $opt_zoomfilter=filtertype

`Argument:'
     -zoomfilter filtertype

   Select the filter algorithm to use for image zooms (reductions &
enlargements). The available values are `Box', `Triangle', and
`Mitchell'. The algorithms have a significant effect on processing time
and may have a perceptible effect on image quality. Images zoomed via
the `Box' algorithm will have the lowest quality (unsuitable for
further processing) and will zoom the fastest.  Images zoomed via the
`Triangle' algorithm usually have sufficient quality that it takes
careful inspection to detect differences from the best algorithm.

   The `Triangle' algorithm is almost as fast as the `Box' algorithm so
there is little need to use the `Box' algorithm. The `Mitchell'
algorithm produces the best possible results (preserving fine details)
but with a 40% (or so) speed penalty overall as compared with the
`Triangle' algorithm. If speed is not important for your application,
and end-users are likely to be using deep-color displays, then by all
means choose the `Mitchell' algorithm because if you choose a lesser
agorithm, you will never know what you are missing.


File: webmagick.info,  Node: Thumbnail Label Options,  Next: Thumbnail Hooks,  Prev: Thumbnail Imaging,  Up: Montage Options

Thumbnail Label Options
=======================

* Menu:

* Thumbnail Title Xref::        Specify thumbnail titles
* Thumb Label Format::          Specify thumbnail label format
* Thumb Label Width::           Specify thumbnail label truncation width
* Thumb Label Font::            Specify thumbnail label font

