


GIFMAP(1)		  User Commands			GIFMAP(1)



NAME
     gifmap - web-based	image index builder

SYNOPSIS
     gifmap [ --address	string]
	    [ --coloralink colorspec ]
	    [ --colorback colorspec ]
	    [ --colorlink colorspec ]
	    [ --colortrans colorspec ]
	    [ --colorvlink colorspec ]
	    [ --columns	number ]
	    [ --debug ]
	    [ --dircoloralink colorspec	]
	    [ --dircolorback colorspec ]
	    [ --dircolorlink colorspec ]
	    [ --dircolorvlink colorspec	]
	    [ --dirindexname filename ]
	    [ --forcegif ]
	    [ --forcehtml ]
	    [ --forcemontage ]
	    [ --header string ]
	    [ --help ]
	    [ --htimage	path ]
	    [ --iconpath path ]
	    [ --indexname filename ]
	    [ --maptype	cern|ncsa ]
	    [ --maxgif number ]
	    [ --montageflags string ]
	    [ --pageindexname string ]
	    [ --prefixpath path	]
	    [ --readme filename	]
	    [ --recurse	]
	    [ --relative ]
	    [ --rootpath path ]
	    [ --rows number ]
	    [ --srcdir path ]
	    [ --thumbborder borderwidth	]
	    [ --thumbcompose operation ]
	    [ --thumbfont fontspec ]
	    [ --thumbframe geometry ]
	    [ --thumbgeom widthxheight ]
	    [ --thumbgravity direction ]
	    [ --thumblabel format ]
	    [ --thumbshadow ]
	    [ --title string ]
	    [ --verbose	]

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



15/Mar/97		Last change: 1.51			1






GIFMAP(1)		  User Commands			GIFMAP(1)



     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.

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

     In	general, gifmap's defaults produce nice	output.	 However,
     the options $opt_prefixpath, $opt_rootpath, $opt_iconpath,
     $opt_htimage, and $opt_maptype 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.

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

     index.html	       Main (default server index) HTML	index
     file
		  Saved	in case	the .index1.html or .index1.map
		  needs	to be generated	and we don't want to



15/Mar/97		Last change: 1.51			2






GIFMAP(1)		  User Commands			GIFMAP(1)



		  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



15/Mar/97		Last change: 1.51			3






GIFMAP(1)		  User Commands			GIFMAP(1)



	 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.

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



15/Mar/97		Last change: 1.51			4






GIFMAP(1)		  User Commands			GIFMAP(1)



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

	 # # .gifmaprc -- Gifmap 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 gifmap image	indexes	$opt_prune
	 = 1;	      #	Don't recurse into sub-directories


     $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



15/Mar/97		Last change: 1.51			5






GIFMAP(1)		  User Commands			GIFMAP(1)



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


	 =item B<$opt_dirindexname>=I<filename>	 (B<--dirindexname> I<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



15/Mar/97		Last change: 1.51			6






GIFMAP(1)		  User Commands			GIFMAP(1)



	 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)
	 Please	 Note:	this  option  is depricated and	will be
	 removed in a future Gifmap release since the intention
	 is to support all useful Montage options via Gifmap
	 options.

	 Extra 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



15/Mar/97		Last change: 1.51			7






GIFMAP(1)		  User Commands			GIFMAP(1)



	 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



15/Mar/97		Last change: 1.51			8






GIFMAP(1)		  User Commands			GIFMAP(1)



	 "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



15/Mar/97		Last change: 1.51			9






GIFMAP(1)		  User Commands			GIFMAP(1)



	 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
     Gifmap is written and maintained by Bob Friesenhahn
     (bfriesen@simple.dallas.tx.us) with copious input from
     Anthony Thyssen (anthony@cit.gu.edu.au). Anthony's	diligent
     assistance	as the first alpha tester is very much
     appreciated.





























15/Mar/97		Last change: 1.51		       10



