Installing JackSVG - Getting it to run on your machine

If you don't want to go to the trouble of downloading and installing JackSVG, you can use the online service with a Web browser. It doesn't support some of the more advanced functions, so if you want to use them you must install it.

These are the five steps that need to be covered when installing JackSVG.

First you need Perl on your system. Perl is available for many platforms and can be downloaded for free. Follow the particular installation instructions that came with the distribution you use.

JackSVG uses some third party modules (i.e. libraries) to perform some special function. The XML::Parser module is mandatory - however, it comes with ActiveState Perl, but you may need to install it separately if you use another distribution of Perl.

The other modules are optional, JackSVG will use them if they are present but will run without them. Image::Size is used to determine the size of external images; if you don't have it, all references to external images must have their width and height explicitly declared. The Font::AFM module is used to process Adobe Font Metrics files. The Font::TTF::Font module is used to process font metric information in TrueType font files. Note that there seems to be bugs with the Font::TTF::Font module, and it might not work properly with all TrueType fonts.

All these modules are available from CPAN <http://www.cpan.org/>. However, there are simpler ways to install them than to manually download them - see the documentation that came with your Perl distribution.

JackSVG is supplied as a standard Perl module. You should use the standard procedure to install them. Common mechanisms for Unix and Windows are briefly described below, but see your local Perl documentation for more details.

When a stylesheet uses a certain font, it needs to know its dimensions so it can determine line breaks and layout the text. This information is conveyed in font metrics files.

JackSVG can use font metrics found in Adobe AFM files, TrueType font files and SVG font files.

The AFM files (type "afm") usually come with PostScript fonts. You will need the Font::AFM Perl module to use them. The Font::AFM also comes with font metrics for Times, Helvetica, and Courier - so if you have the module, you can immediately use these fonts without having any font metrics files. Note: Courier doesn't seem to look very good under the Adobe SVG viewer, you should use Courier New instead.

TrueType font files (type "truetype") contain both information on how to draw the characters and the font metrics. You will need the Font::TTF::Font module to use them. An example metrics mapping file (FM-winxp.xml) is supplied that allows you to use some installed TrueType fonts under Windows XP. If you use some other version of Microsoft Windows, the location of the font files might be different. Note: the Font::TTF::Font module doesn't work properly with all TrueType fonts. You will also get lots of warning messages, but they can be ignored.

JackSVG can also use metric information in SVG files that contain an SVG font (type "image/svg+xml"). The file must contain only a single font, and there are other restrictions on the format of the file. This is the prefered metrics format to use, because ATM doesn't support Unicode and the TrueType processing is unreliable. Included is a sample metrics mapping file (FM-svg.xml) and the SVG font files it references. Since we only need the metrics information, these supplied SVG font files only contain the metric information. They do not contain any information on how to draw the font (especially since that information is copyrighted so we can't distribute it). One way to create your own SVG font file is to use the TrueType conversion tool that comes with Batik.

The standard installation mechanism does not install the documentation or examples. If you want these, you will need to install them manually. This is easily done by copying the docs and examples directories.

Under the examples directory, you'll find example presentations, stylesheets, and font metrics mapping files. There are XML Schema and DTD files describing the JackSVG file formats. There are XSLT scripts that convert presentation source files into HTML and XSL-FO, which are useful for printing your presentation. There are also the files associated with the stylesheet tutorial.

Under Unix, the standard way to install a Perl module is to unpack it and run the above commands. The "make test" is optional. It is useful for telling you if some of the optional modules are missing - those tests will be skipped if the modules are not present.

If you do not want to install it in the standard Perl location (or cannot because you don't have the required permissions), you can install it in a local directory by supplying the PREFIX argument when building the Makefile.

For some stylesheets that use special fonts (e.g. blackboard.xml) you will need to specify the font metrics file. Add -fontmetrics examples/fontmetrics/FM-svg.xml to the arguments to pres2svg. Alternatively (though less preferable), you can just specify the -Force flag to tell it to ignore missing font metrics. However, the layout and positioning will not look very good (so don't use -Force unless you have to).

There are several different distributions of Perl for Microsoft Windows. These instructions will be for ActiveState's ActivePerl distribution. For other distributions, consult the documentation which came with it about how to install Perl modules.

ActiveState's ActivePerl is very easy to install. Just download it and follow the installation wizard's instructions. It is recommended that you get the latest version (5.8.0 at the time of writing).

Note: these installation instructions are for ActivePerl version 5.8.0. The procedure for earlier versions is slightly different (you run ppm3 instead of ppm and that program runs slightly different) - see the instructions that came with ActivePerl for details on how to run the earlier ppm program. Also, note that the installer files for JackSVG is different for the different version of ActivePerl. The install files for ActivePerl 5.8.0 cannot be used on older versions, and installer files for older versions cannot be used with ActivePerl 5.8.0 - please download the correct JackSVG install files.

ActivePerl comes with an installation program called Programmer's Package Manager (PPM). Normally PPM contacts a remote repository to download and install packages. However, in these instructions it is assumed that you have manually downloaded the JackSVG package (the ZIP file version) and will be installing that local copy. JackSVG is currently not up on any repository, so you will have to do it this way!

Unzip its contents. Start a command prompt (All Programs -> Accessories -> Command Prompt), go to the directory containing the unzipped files, and start the ppm program.

If you are behind a firewall, before you start ppm you will need to set the http_proxy environment variable to point to your proxy machine. If a user name and password is required to use the proxy, also set the http_proxy_user and http_proxy_pass environment variables.

set http_proxy=http://proxy.example.com:80

In ppm, you need to instruct it to search the local directory for packages. Then you instruct it to install the JackSVG package. Below is an example installation session:

ppm> rep
Repositories:
[1] ActiveState PPM2 Repository
[2] ActiveState Package Repository
ppm> rep add localdir .
[1] ActiveState PPM2 Repository
[2] ActiveState Package Repository
[3] localdir
ppm> search jacksvg
Searching in Active Repositories
  1. JackSVG      [1.1] SVG slide presentation maker
ppm> install 1
====================
Install 'File-Spec' version 0.82 in ActivePerl 5.8.0.804
 ...
 ...
 ...
Successfuly installed jacksvg version 1.1 in ActivePerl 5.8.0.804.
ppm> quit

Note that the installer will automatically find and download dependent modules. With a new install of ActivePerl, it should automatically install Image-Size and File-Spec before installing JackSVG.

To uninstall JackSVG, run ppm and enter the command remove JackSVG.

You'll find that ActivePerl already comes with most of the other Perl modules you require to run JackSVG (or it will automatically install them for you during the installation step). However, if you need a module that isn't installed, run ppm and type in the above instructions. The querystring can be a substring found in the name of the module (e.g. "ttf"). The modulename has to be the full name of the module, as returned by the search command (e.g. "Font-TTF").

For some stylesheets that use special fonts (e.g. blackboard.xml) you will need to specify the font metrics file. Add -fontmetrics examples\fontmetrics\FM-svg.xml to the arguments to pres2svg. Alternatively (though less preferable), you can just specify the -Force flag to tell it to ignore missing font metrics. However, the layout and positioning will not look very good (so don't use -Force unless you have to).

If you are running Cygwin under Windows, you'll have to use the command pres2svg.bat instead of pres2svg. Additionally, you'll need to run ppm under a DOS command prompt (and not under the Cygwin bash shell). Also, be aware that under bash the Cygwin installation of Perl will probably be in your PATH rather than the ActiveState installation.