NAME

SYNOPSIS

DESCRIPTION

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 ``.gifmaprc''. Configuration files are written in PERL syntax and are sourced via PERL's eval statement. When gifmap is executed, it first reads a ``.gifmaprc'' file in the user's home directory (if present). When a directory is processed, gifmap will process any ``.gifmaprc'' files found in the path from the server's root directory (specified by $opt_rootpath) to the directory being processed. All configuration options are additive.

Evaluation order (inverse of precedence) is as follows :

1. $HOME/.gifmaprc

2. Command line options

3. Per directory .gifmaprc files.

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

   Note: For performance reasons, icon image sizes are only obtained one time. This means that if the list of icons to use is modified in a sub-directory, the original (possibly incorrect) sizes will be used. This limitation should go away sometime in the future.

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

C< index.html Main (default server index) HTML index file .index1.html HTML page that displays thumbnail frame .indexdir.html HTML page that displays directory 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 .index1.stat Gifmap status file. Re-generated on each run. .index1_map.shtml ImageMagick-generated imagemap file. Saved in case the .index1.html or .index1.map needs to be generated and we don't want to re-run 'montage'. >

PROGRAM OPTIONS

General:

$opt_debug=1 (--debug)

Print debugging messages.

$opt_forcehtml=1 (--forcehtml)

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

$opt_forcemontage=1 (--forcemontage)

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

$opt_help=1 (--help)

Display usage message.

$opt_ignore=1

If $opt_ignore is set in a directory's ``<.gifmaprc>'' file (default off), then that directory will not be processed. If recursion is enabled, then recursion will continue into any sub-directories. See also $opt_indexname.

$opt_prune=1

If $opt_prune is set in a directory's ``.gifmaprc'' file (default off), then no sub-directories below that directory will be processed by gifmap when operating in the recursive mode. See also $opt_indexname.

$opt_recurse=1 (--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 gifmap to recurse through sub-directories as well.

$opt_srcdir=path (--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 Gifmap to change directories before starting processing.

$opt_verbose=1 (--verbose)

Normally gifmap 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 gifmap is currently creating as a progress report.

Paths:

$opt_rootpath=path (--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 gifmap will be processing in. If this value is specified incorrectly, gifmap will generate incorrect URLs.

$opt_prefixpath=path (--prefixpath path)

The URL to prepend to specify the WWW location of $opt_rootpath. For directories under the WWW server's root directory this is a empty string (``''). For a user's home pages this is the URL path to their home pages (usally ``/~username'', but may be different on your server). This is only used for figuring out the URLs of the gifmap icon images.

If $opt_relative is enabled then this option is not actually used. It however must be used if the gifmap icon images are not in the same logical WWW directory tree as the directories gifmap is processing. (See the next option).

$opt_relative=1 (--relative)

Specify URLs for gifmap icon images as relative paths from the directory gifmap is processing. The images must be in the same WWW directory tree otherwise fully-qualified paths (i.e. non-relative) will be substituted.

If the gifmap icons are not in the same directory tree, then this option should be turned off and $opt_prefixpath and $opt_iconpath used to locate the gifmap icon images using absolute URL paths.

$opt_iconpath=path (--iconpath path)

This is the relative path from the top of the WWW directory tree specified in $opt_rootpath. If this value is specified incorrectly then gifmap will generate incorrect URLs for its icons.

%opt_icon=( 'id', 'filename', .... );

This is a hash table of all the icon images used by gifmap and located in the $opt_iconpath directory. The elments are pairs of icon ids and the filename of the image. The ids currently used gifmap are :- prev, next, next_grey, up, help, and ball.

Other images can also be defined in the hash table and gifmap 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.

WARNING: currently icon information should only be set in the global gifmaprc file (usally ``~/.gifmaprc'', as unexpected results can happen if modified in per-directory rc files. This is because icon sizes are currently only evaluated according to the initial settings.

Filenames:

$opt_indexname=filename (--indexname filename)

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

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

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

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

$opt_readme=filename (--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.

$opt_pageindexname=string (--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).

$opt_dirindexname=filename (--dirindexname filename)

Directory-name to title cross-reference for sub-directories (default ``.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 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.

Server-side imagemaps:

$opt_htimage=path (--htimage path)

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.

$opt_maptype=maptype (--maptype maptype)

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

Image Map Options:

$opt_colortrans=colorspec (--colortrans colorspec)

Transparent color to use in montage. Usally the same as the background color $opt_colorback 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.

$opt_columns=number (--columns number)

Montage columns (max). This is the maximum number of thumbnail columns allowed per thumbnail row (default 6).

$opt_forcegif=1 (--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.

$opt_maxgif=number (--maxgif number)

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.

$opt_montageflags=string (--montageflags string)

IExtra flags to ImageMagick montage (default none). The montage program is used to generate the thumbnail images used by gifmap. Read the the montage manpage manual page for details.

$opt_rows=number (--rows number)

Montage rows (max). This is the maximum number of thumbnail rows allowed per page (default 5).

$opt_thumbborder=borderwidth (--thumbborder borderwidth)

The border (in pixels) to place between a thumbnail and its surrounding frame (default 5). If frames are disabled (the default) then this option is ignored.

$opt_thumbcompose=operation (--thumbcompose operation)

Image composition option 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.

$opt_thumbfont=fontspec (--thumbfont fontspec)

Thumbnail title font. This is the X11 font used to title thumbnails (default 5x8). PERL's newgetopt module seems to have difficulties with the dashes in most X11 font specifications. If getopt prints the usage message rather than doing what you want to, then try using the command line syntax --thumbfont=fontspec and you should have better luck.

$opt_thumbframe=geometry (--thumbframe geometry)

Geometry specification for frame to place around thumbnail. If no frame is desired then ``false'' should be specified. The default is no frame.

$opt_thumbgeom=geometry (--thumbgeom geometry)

Thumbnail geometry (widthxheight). This defines the size of thumbnail images (default 106x80).

$opt_thumbgravity=direction (--thumbgravity direction)

Positioning of thumbnail within the specified geometry ($opt_thumbgeom 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 South so that any thumbnail label is even with the bottom of the montage grid.

$opt_thumblabel=format (--thumblabel format)

Specifies the format of thumbnail labels. The image filename, type, width, height, or scene number may be included in the label by embedding special format characters. Embed %f for filename, %m for magick (image type), %w for width, %h for height, %s for scene number, %b for file size in kilobytes, or \n for newline. For example,

-label '%m:%f %wx%h'

produces an image label of MIFF:bird.miff 512x480 for an image titled bird.miff and whose width is 512 and height is 480. (This explanation borrowed from montage manual page). If a label is not desired, then use the argument ``label'' to turn off this feature.

The default format is '%f\n%wx%h %bKb' which displays the filename over the image geometry and size in K bytes.

$opt_thumbshadow=boolean (--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''.

Colors & Appearance:

$opt_address=string (--address string)

Additional information to place in <ADDRESS></ADDRESS> tags in page frame. Gifmap copyright and support information is placed on all generated pages.

$opt_coloralink=colorspec (--coloralink colorspec)

Link (active) color for page frame (default '#FF0000').

$opt_colorback=colorspec (--colorback colorspec)

Background color for page frame (default 'peach puff').

$opt_colorlink=colorspec (--colorlink colorspec)

Link (unvisited) color for page frame (default '#0000EE').

$opt_colorvlink=colorspec (--colorvlink colorspec)

Link (visited) color for page frame (default '#551A8B').

$opt_dircoloralink=colorspec (--dircoloralink colorspec)

Link (active) color for directory frame. Defaults to value of $opt_coloralink if not explicitly set.

$opt_dircolorback=colorspec (--dircolorback colorspec)

Background color for directory frame. Defaults to value of $opt_colorback if not explicitly set (default 'light sky blue').

$opt_dircolorlink=colorspec (--dircolorlink colorspec)

Link (unvisited) color for directory frame. Defaults to value of $opt_colorlink if not explicitly set.

$opt_dircolorvlink=colorspec (--dircolorvlink colorspec)

Link (visited) color for directory frame. Defaults to value of $opt_colorvlink if not explicitly set.

opt_frameddirfmt=string

Template (written in PERL) that represents the format used to generate the framed (left frame) directory navigation page. This format will be seen by browsers that support frames. This is a guru-level option that may require reading gifmap code.

opt_dirfmt=string

Template (written in PERL) that represents the format used to generate the frame-less directory navigation page. This format will be seen by browsers that do not support frames. This is a guru-level option that may require reading gifmap code.

$opt_header=string (--header string)

Text to add to page header in page frame (a short term hack). This option is subject to change and will be eliminated if the page frame is templatized.

$opt_title=string (--title string)

Page title. If this option is not specified, then gifmap will generate its own title in the form 'Index of directory ``subdirectory name'''.

AUTHORS