Read Me for Mac-ImageMap (v. 1.4 beta 2)

Contents

1. Introduction
2. Quick start - read before the following chapters!
3. More general
4. Miscellaneous notes
   • Problems and bug reports
   • other notes
5. Version history
6. DISCLAIMER - NO WARRANTY

Introduction

If you use the Mac-ImageMap together with WebSTAR you are able to take benefit from a new, unique feature of WebSTAR - the user action concept. Based on this, you are able to avoid running into a difficulty which has been introduced to the WEB by a bug in an older version of the CERN-proxy gateway software (running on UNIX hosts!). Additionally, configuring of Mac-ImageMap will be easier when run as a user action handler. See below for more information on this.

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 mailing costs). Permission for distribution of the program on Shareware CD-ROM volumes is granted.

Mac-ImageMap is a WebSTAR and 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. See below on what information is needed or useful within a bug or problem report. Any reported bug I will try to fix within a future version, if possible.

Quick start - read first!

Important:Within the ACTION statement, the pathname to the imagemap.cgi application must be expressed relative to that folder where the WebSTAR application program resides. Also, the imagemap.cgi application file must reside within the WebSTAR folder hierarchy and the pathname in the ACTION statement must refer to the imagemap.cgi application file, but not to an alias of it. Mac-ImageMap fails to proper work as a user-action handler if these rules are not followed and e.g. instead a full filename-path (starting with your harddisk-name) is entered!

Before trying to make you own clickable maps, please read the MacHTTP or WebSTAR documentation. Especially, you should be already familar with the concept how URLs are handled by your Web-server software. Also, if you are referencing Macintosh file aliases within your URLs, read everything what deals with alias handling in the server software documentation. If the scheme how file aliases are handled, does not seem to be clear to you, please do not use aliases in connection with making your first own clickable map!
To create quickly your own clickable map, follow these steps:

1. Create the map picture.

Create your own map-picture using your favourate drawing utility (for example: the shareware utility GraphicConverter by Thorsten Lemke). 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) Running Mac-ImageMap as a CGI or ACGI:
<A HREF="http://your.host/imagemap/imagemap.cgi$mapname"><IMG SRC="http://your.host/imagemap/your_example/map_picture.gif" ISMAP></A> .
or -
b) when running Mac-ImageMap as a WebSTAR user-action handler:
<A HREF="http://your.host/imagemap/your_example/map_picture.map"><IMG SRC="http://your.host/imagemap/your_example/map_picture.gif" ISMAP></A> .

4. Add your map to the imagemap configuration file.

If you run Mac-ImageMap as a WebSTAR user-action handler, simply skip step 4. If you intent never to run the imagemap.cgi program as a CGI or ACGI, and you don't want to change any general default settings for Mac-ImageMap (more about this below), you may even delete the file "imagemap.config". Otherwise, 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 snippets 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 the subfolder and named it map_picture.gif. Furthermore, you must also have put your generated imagemap-definitions file into the subfolder and have named it map_picture.map .

More general

If you are running WebSTAR as your server, you should prefer running Mac-ImageMap as a user-action handler because, when using this mode of operation, you can avoid that some WEB-users (well, I feel, unfortunately a lot users!) within the world are unable to use from their host your clickable map, due to a bug within a certain, widely used, version of the UNIX CERN-proxy-gateway. If a user sends an URL request which includes a $-sign, as in "imagemap.cgi$mapname", this $-sign will be encoded by the proxy-server to a %24 character replacement. Such, the $-sign and the former path-argument "mapname" are now appended to the filename "imagemap.cgi" and make the new filename "imagemap.cgi$mapname", which of course does not exist on your server. If you run instead Mac-ImageMap as a user-action handler, you don't need to use URLs with your maps which include a $-sign.

Normally the URLs, as shown above, will be generated by a HTML-browser when clicking on a clickable map picture, which is defined for the CGI/ACGI case by HTML-code like this:
<A HREF="http://your.host/imagemap_folder/imagemap.cgi$mapname"><IMG SRC="http://your.host/pictures/map_picture.gif" ISMAP></A>
or, for the user-action handler case by HTML-code like that
<A HREF="http://your.host/your_map_folder/your_map_name.mapsuffix" ><IMG SRC="http://your.host/pictures/map_picture.gif" ISMAP></A> .

If you are using Mac-ImageMap as a user-action handler, you must have configured for your WebSTAR server an ACTION and a SUFFIX mapping, like this:
ACTION <any name> <relative path to the "imagemap.cgi " application>
SUFFIX <any name> .mapsuffix TEXT * text/html
When running the imagemap.cgi program with one WebSTAR server, you don't need the file "imagemap.config ", if you follow these rules: Place the "imagemap.cgi " application inside the WebSTAR folder hierarchy and refer to it within the WebSTAR ACTION specification using the relative expressed file-path with respect that folder wherein the WebSTAR application program is located. The file-path must be written in the usual Macintosh file-path notation, e.g. using colons as foldername (directoryname) separators. The file-path must refer to the application file and not to an alias of it.
If you wish to use the program with multiple WebSTAR servers which run on the same machine, but on different ports, then use the $ServerPath-specification (see below) in the "imagemap.config"-file to specify the Macintosh file-pathes to the root (e.g. application program) directories of those servers where the "imagemap.cgi" does not reside within the folder hierarchy.
The $ServerPath specification is a line in the "imagemap.config"-file like this
$ServerPath : <file-path> <portnumber>
where <file-path> is the Macintosh-style file-path to that folder where the WebSTAR application resides in which runs on port <portnumber>.
Note that, if you identify a WebSTAR server to Mac-ImageMap by a $ServerPath-line, the path-file reference within this servers ACTION specification for Mac-ImageMap must not follow any of the rules which are outlined above for the case of one WebSTAR server and no "imagemap.config"-file.

If you are using Mac-ImageMap as a CGI or ACGI, you must have defined the suffix-mapping of the CGI program type to MacHTTP in the MacHTTP.config file by a suffix-definition line like this:
CGI .CGI APPL * text/html,
or ACGI .ACGI APPL * text/html.
Note: If you want to run "imagemap.cgi" as an ACGI, you may simply rename it to "imagemap.acgi", and change the links within your HTML clickable map pages accordingly.
Further, if Mac-ImageMap is run as a CGI or ACGI, it needs to read a configuration file, which must reside within the same folder as the program, and the configuration file must be named imagemap.config. Within this file, each name of a clickable map must be associated with an imagemap-definition file. This is done by including lines like this:
mapname1 : :subfolder_of_imagemap:map1.map - or -
mapname2 : MyHardDisk:maps:map2.map .
The blanks before and behind the colon ":" , which seperates the mapname and the filename, are essential. "mapname1" and "mapname2" are sample names by which the map-definitions-files are referenced in the HTML code - the appropriate one of these names must appear after the $-sign, for example in a partial URL like "imagemap.cgi$mapname1" . Notice, again, that the filenames of the maps must appear in the usual Macintosh filename notation - compare above.

If instead Mac-ImageMap is run as a WebSTAR user-action handler, the configuration file is optional, for changing general defaults of the "imagemap.cgi" program. For getting the best performance when running the "imagemap.cgi" exclusively as a user-action handler you should remove the "imagemap.config" file.

Within this configuration file the WWW-Server administrators e-mail address can be specified in a line
$ServerAdmin : administrators e-mail address .
Mac-ImageMap uses this address within some possible HTML error messages.

Furthermore, if you wish to let Mac-ImageMap immediately quit when it has done its work for the moment, instead of letting it stay open, you may add a line
$StayOpen : -1
to the configuration file to make the program behave such.

Finally comment lines, which may be included within the file, start with a hashmark sign "#" in the first column. For even more readability, also blank lines are permitted within the file. However, if a line starts with the character sequence #$, these two characters are deleted from this line and the remaining characters in the line will be read as some specification. Review the sample imagemap.config file for details.

Note: When running Mac-ImageMap as a CGI or ACGI, an imagemap-definition file must not necessary reside within your WEB-servers folder hierarchy, since it needs not to be accessed by your server.
However, if you are running the program as a WebSTAR user-action handler, the URL directly identifies your map-definition file to your WebSTAR server and such it must reside within your servers folder hierarchy.

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. Note, that a partial URL always starts with a slash "/" .
Additionally, you may use the special URL $RefURL as a redirect_url. Mac-ImageMap substitutes "$RefURL" by the URL of this page, where the user clicked on the map. Note, that this only works with HTML-browsers which are supplying this URL in a "X-Referer:" line within their HTTP-request. If you want to use the same clickable map on several different HTML-pages, and you want to have a region within the picture that just lets you stay at the page where you are, the $RefURL extension supplies you a way to realize this map behaviour - using for all maps the same unique map-definition file.

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

Problems and Bug Reports

• The version of Mac-ImageMap which you are running,
• The Web-servers name and version which you are running,
• The System version and language-localization,
• The Macintosh model name where you run the software,
• If a crash occured:
  • at least the system error code,
    better will be a MacsBug application stack listing (commands "sc6" and "sc7"),
  • the "imagemap.config"-file,
  • the map-definition-file which has been accessed,
  • the click-coordinates.
• If you get a HTML error message:
  • The HTML output and/or the returned URL,
  • a verbose WebSTAR or MacHTTP messages listing,
  • the map-definition-file which has been accessed.
• If the imagemap.cgi pops up an error-dialog box:
  • The displayed error message text.

Other 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.biap.com/,
or from the Sumex Macintosh ftp-archive, in the directory /comm/tcp/ . Note that this is subject to change soon, since MacHTTP licensing requests are now (since 2th May 1995) handled by StarNine Technologies, Inc..
To get information on WebSTAR, look at the StarNine Technologies, Inc. pages or send e-mail to info@starnine.com.

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 and WebSTAR WWW-server software, for creating MacHTTP and WebSTAR, 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

Added support for running Mac-ImageMap as an ACTION-handler with multiple WebSTAR servers by the implementation of the $ServerPath configuration file specification.

95/05/18 : version 1.4 beta2

Added a proper HTML-error message for the case that the file-path name of the map-file cannot be build, because the necessary rules how to express the ACTION-path in the ACTION statement were not followed.

Added to the documentation the hint that the ACTION-path must not reference a file alias.

95/05/16 : version 1.4beta1

New features:

Support added for running "imagemap.cgi" as a user-action handler with the commercial WebSTAR server, instead of a CGI. This allows you to direct reference the map-definition file within the ISMAP HTML, instead of indirectly referencing by the path argument of the CGI "imagemap.cgi" . Such, you avoid that users, who connect to you server through a certain older version CERN-proxy gateway, cannot use your map because the URL sent is mistakely changed by the proxy-gateway.

If the imagemap.cgi is *exclusively* run as a user-action handler, the imagemap.config file is no longer necessarily needed.

"$StayOpen : 0" is now the default option, e.g. imagemap.cgi remains be opened after once launched. You can still make imagemap.cgi immediately quitting by including "$StayOpen : -1" in the imagemap.config file.

HostName (or IP address) and portnumber are no longer obtained from the config file, but instead from the MacHTTP or WebSTAR application AppleEvent. This makes it now easier to use Mac-ImageMap with multiple MacHTTP or WebSTAR servers running on the same Macintosh.

$RefURL introduced as a special URL which can be specified in any place in a map where an URL is a valid parameter.
$RefURL is substituted by the X-Referer-URL, e.g. the URL of the HTML-page where the clickable map has been invoked.

If a diagnostic or error HTML page is returned, the Server: HTTP-header line reflects whether imagemap.cgi runs with MacHTTP or WebSTAR.

Bug fixes and miscellaneous small enhancements:

imagemap.config parsing bug fixed, which caused in rare situations a crash or endless loop.

Increased the Finders memory size of the "imagemap.cgi" application to 250K to prevent casually crashes of the program on PowerMacs due to memory shortage.

Mapfile parsing bug fixed, such that now multiple blanks are allowed as parameter seperators in (hopefully!) any context.

Negative numbers are now accepted in coordinate pairs.

TestMode output heading changed to make clear that diagnostic output results from testmode flag setting or, alternatively, a missing default URL.

A small bug in the text of the"Invalid input ..." HTML error message has been fixed.

94/12/07 : version 1.3

Included support for the required AppleEvent Quit.

Improved error handling. Mostly all error dialogs (except those which display when unusual AppleEvent errors show up) are now replaced by HTML-error messages which are sent to the Web-client.

Fixed a bug which caused Mac-ImageMap hang in an endless loop, if called with a map-name which has not been defined within the config-file, or caused to do not find a map which was defined near the end of the config-file.

94/12/01 : version 1.2.2 (Maintenance release)

Fixed a bug that caused Mac-ImageMap run into an endless loop of error dialogs when a map-specification file contains invalid lines. The error dialog now only shows up once, and processing of the map-file continues with the next specification.

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 carriage-return 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