Read Me for Mac-ImageMap (v. 1.3)

Contents

1. Introduction
2. Quick start
3. More general
4. Miscellaneous notes
5. Version history
6. DISCLAIMER - NO WARRANTY

Introduction

Mac-ImageMap is Freeware, but not public domain. This means, that it may be used without paying a fee for it, for non-commercial purposes. All rights to the program remain reserved to me, the author. See also the disclaimer near the end of this file. If you wish to use this program for a for-profit purpose, you are obliged to contact me for usage conditions (see my address at the end of this file). The unmodified program may be freely distributed together with this README-file and the supplied sample files, for no charge - except an optional small handling fee that covers the costs (max. 2,- US$ for a floppy disk plus package and mailing costs). Permission for distribution of the program on Shareware CD-ROM volumes is granted.

Mac-ImageMap is a MacHTTP tool - designed to map clicks on a HTML ISMAP picture to an URL which is specified in an imagemap map-file. The current program version can assign URLs to rectangular regions, circle regions, elliptic regions and arbitrary poly-regions. Additionally, for the remaining picture parts which are not assigned to specific regions, special points may be defined and URLs associated with them - the URL of the nearest of these points to the clicked point will apply.

Mac-ImageMap is a standalone program, which needs no additional scripting language to be used, and such, it does its task quickly and efficiently.

Please report bugs and problems to weimann@zib-berlin.de. Any reported bug or problem I will try to fix within a future version, if possible.

Quick start

1. Create the map picture.

Create your own map-picture using your favourate drawing utility (for example: the shareware utility GraphicConverter by Thorsten Lemke or the commercial program Adobe Photoshop). Save the picture as a GIF file.

2. Create the map-definitions file.

Get the shareware utility WebMap (also available from the /util/comm/ directory of the University Michigan Macintosh archive or from a mirror site). Open your saved GIF file with this utility. Note: You need version 1.0 or later of WebMap to open a GIF picture with this program. If you use an earlier version of WebMap you have to work with a PICT-format copy instead of the GIF-picture. Select rectangular, circle/elliptic and arbitrary polygon regions as you like, using the appropriate tools from the palette, and assign the desired redirect-URLs to the selected regions. Don't forget to define a default URL, using the appropriate menuitem within the EDIT menu. Save your definitions to the picture file, using the SAVE menuitem from the file menu, and create your imagemap-definitions file by selecting the "Export As Text..." menuitem from the file menu, with the NCSA radio buttom clicked.

3. Create the imagemap HTML-page.

Create a HTML-page, which contains an ISMAP IMG tag, referencing to the GIF-copy of your map-picture, like this:
<A HREF="http://your.host/imagemap/imagemap.cgi$mapname"><IMG SRC="http://your.host/imagemap/your_example/map_picture.gif" ISMAP></A> .

4. Add your map to the imagemap configuration file.

Add a line to the imagemap.config file, which tells the program imagemap.cgi the name of the map-definition file that should be used with the given mapname. The line must look like this:
mapname : :your_example:map_picture.map .
For this definition line and the HTML snippet above, it is asumed that you have created a subfolder within the imagemap folder named your_example, and that you have put your GIF-map-picture into this folder and named it map_picture.gif. Furthermore, you must also have put your generated imagemap-definitions file into this folder and have named it map_picture.map .

More general

Note: an imagemap-definition file must not necessary reside within the MacHTTP folder hierarchy, since it needs not to be accessed by MacHTTP.

Now, an explanation of the imagemap-definition file format follows. You should also study the sample map file DemoPicture.map in the demomap folder. The demomap example may look a bit boring, but it demonstrates all features in principle which are provided by Mac-ImageMap. You may run this example by opening the URL
http://your.host/imagemap/demomap/demomap.html
(provided that you have put the Mac-ImageMap distribution files into a subfolder of the MacHTTP folder named "imagemap").

Note: An imagemap-file may be easily created from a picture (PICT format) in a WYSIWYG manner, using the Shareware-Utility WebMap (available from the umich archive).

Like the configuration file, comments - starting with a hashmark "#" in the first column - and blank lines are allowed within such a file. However, if a line contains the character-sequence #$ in columns 1 and 2, these characters are stripped and the remaining line is interpreted as a imagemap definition. Such, you are allowed to include definitions, which are only understood by Mac-ImageMap, as pseudo comments within the file; and you may also use the file together with the NCSA-httpd imagemap program under UNIX, without changing it. (If I am wrong with this statement, please tell me a bit about the httpd imagemap map-file.) Furthermore, longer definitions may run now over multiple lines - a feature which may be especially useful for arbitrary polygon specifications (see below). Mac-ImageMap just checks, if a line begins with a letter (lowercase or uppercase) to identify a line where a new specification begins.

Now a description of all specification types which are supported within a map-file follows. Throughout this description the term redirect_url may either be replaced by a full URL (which can start with http:, ftp:, gopher:, file:, news:, telnet:, or mailto:) or by a partial URL - this means an URL on your server without the http://your.host part. Mac-ImageMap supports the following definitions:

testmode

runs Mac-ImageMap in testmode: Instead of returning a redirect URL HTTP-header, debug info in HTML format will be returned to the WWW-Client.

default redirect-url (NCSA-imagemap and WebMap compatible)

defines the url which should be returned, if the click within the map-picture does not match any of the regions which have been defined below.

point redirect_url x_pt,y_pt (NCSA-imagemap compatible)

assignes the redirect_url to the single point x_pt,y_pt. If one or more point specifications appear within a map-file and the clicked point does not lie within any specified region, then that URL applies which is assigned to the nearest point with respect to the clicked point - instead of an URL which has been assigned in a default specification.

rect redirect_url x_left,y_up x_right,y_low (NCSA-imagemap and WebMap compatible)

defines a rectangular region with the upper-left corner pixel coordinates (x_left,y_up) and lower-right pixel-coordinates (x_right,y_low). Mac-ImageMap also allows the definition of a rectangle by the two other two rectangle corners, which lie diagonally opposite. Also, the ordering of the defining corners is not mandatory.

circle redirect_url x_center,y_center x_margin,y_margin (NCSA-imagemap compatible)

defines a circle region by its middle point coordinates (x_center,y_center) (-pixel coordinates) and any point (x_margin,y_margin) of the circles margin.

circ redirect_url x_left,y_up x_right,y_low (WebMap compatible)

defines an elliptic (or circle) region by specifying the pixel coordinates of two diagonal opposite corners of the smallest enfolding rectangle. See also the rect definition above.

circrad redirect_url x_center,y_center radius

defines a circle region by its middle point (x_center,y_center ) (-pixel coordinates) and its radius. This definition-type is neither generated by the WebMap utility or NCSA-imagemap standard and will be no longer supported within future versions.

poly redirect_url xp_1,yp_1 xp_2,yp_2 ... xp_n,yp_n (NCSA-imagemap and WebMap compatible)

defines a polygonal area with the n corner points (xp_1,yp_1),...,(xp_n,yp_n). The last point may match the first one, but this is not necessary required. In any case, Mac-ImageMap internally connects the first and the last point (virtually) with a line to define properly an area. Mac-ImageMap can handle polygon definition with up to 2000 points. Note about compatibility: NCSA-imagemap allows only 100 points.

Miscellaneous notes

You may get the latest version of Mac-ImageMap from the Mac-ImageMap homepage http://weyl.zib-berlin.de/imagemap/Mac-ImageMap.html .
The latest Version of MacHTTP is available from the MacHTTP homepage, URL:
http://www.uth.tmc.edu/mac_info/machttp_info.html .

Mac-ImageMap has been written in an extended Fortran 77 language, and compiled and linked under MPW, using the Language Systems Fortran 3.3 Compiler. Therefore, the binary program carries the Language Systems Corp. copyright note, which must be left intact in all copies of the program:

Copyright 1988, 1989 Language Systems Corp. Certain portions of this software are copyrighted by Language Systems Corp.

Thanks to Chuck Shotton, the author of the MacHTTP WWW-server software, for providing MacHTTP, and the search-example C-source code, which clearly demonstrates how to implement the WWWOmegasdoc-AppleEvent handling.
Thanks also to D.L. Meyer, whose REXX routine for handling the WWW Imagemap processing under the OS/2 gopher server has given me a first idea to the Fortran implementation of the imagemap-module.

Version history

94/11/16 : version 1.2.1 (Maintenance release)
Fixed a bug that might cause to crash Mac-ImageMap if the config-file or the map-file is missing (or couldn't be opened due to some other reason).
Further tuned memory usage such that the program now runs with a Finder size of 195K.
Speed improved slightly.

94/11/14 : version 1.2
Added support for partial URLs.
Added support for nearest POINT specification.
The CIRCLE specification is now compatible with the NCSA-imagemap program (while CIRC remains compatible with the WebMap output)
Internal string handling has been optimized to speed up the program and to save storage.
The InSide-polygon check is no longer based on Quickdraw toolbox routines.

94/10/28 : version 1.1:
Added support for arbitrary poly-regions.
Region specifications may now run over multiple lines.
Added an option to let Mac-ImageMap stay open until manually terminated.

94/09/26 : version 1.0, bug fix level 1:
Appended two sequences to the "HTTP/1.0 302 Found" redirect header to match the strict http-standard.

94/09/16 : version 1.0, bug fix level 0:
First public release.

DISCLAIMER - NO WARRANTY