return to Articles

This page’s PURL is http://purl.org/NET/2008,frankbruder/article/Apache-Batik-install,MSWindows . Please use the PURL whenever you set links to this page.

This text is also available at Google Knol.

Installing Batik on Windows Systems

This document describes how to install the Batik SVG Toolkit on a Microsoft Windows system. After following the instructions you will be able to use the Batik tools and applications from the Windows Explorer menu to

You will also be able to start Batik's SVG browser Squiggle from a shortcut in your Start menu or on your desktop.

I am writing this document for users who are familiar with basic usage of the Microsoft Windows graphical user interface. If you know how to use a web-browser like the Internet Explorer, open files from the Windows Explorer, drag and drop files from one folder to an other, create new folders and files, use menues, buttons, and the like then either you are able to follow the instructions I give here or my instructions need some clarification.

Specifically, it is intended that you can follow this tutorial even when you don't know how to use the command line interface, have never used batch files before, and did never manually change file type settings before. You also don't need to be a Java programmer or even know how to start a Java application.

You will have to do some guessing some times, because I didn't test this on different Windows versions. The exact names of menu entries and buttons and the structure of some dialogs might differ. The screenshots are taken on a German install of Windows 98.

install Java

If the Java Runtime Environment is already installed on your system then you can skip this step. If you're not sure whether you've got a JRE installed then you can also skip this step at first. When attempts to use the batch files we'll create later yield the error message “Bad command or file name” then you need to install Java. You will only need to do the other steps of the Batik installation once, no matter if they are done before or after installing Java. So you can savely skip this step for now.

To install the Java Runtime Environment, visit http://www.java.com/, follow the “download” link you find there, save the installation file to a folder where you'll find it (Desktop is fine), and then open the installation file. Installing Java should be rather easy. If you encounter any problems then refer to the Java home page for support.

install Batik

If you've already got an executable of the Batik SVG toolkit on your computer then you can skip this step. But you might want to check if there's a newer version of Batik available.

Visit http://xmlgraphics.apache.org/batik/download.cgi#Download+a+distribution, and download the binary distribution for JRE 1.4+. If your JRE is version 1.3–but it most probably is a later version–then you'll need to download the binary distribution for JRE 1.3 instead, or upgrade to a newer version of Java.

By the time I'm writing this the current release of Apache Batik is version 1.7.
The file you should download is called batik-1.7.zip, unless a newer release of Batik is available by the time you are reading this, or you need to work with JRE 1.3.

This is a zip archive file. On newer versions of Microsoft Windows you can open it just like it was a folder. But that's of no use. You need to extract the files from the archive. There almost certainly is an archive program installed on your system. When you select an archive file in Windows Explorer, and then select ‘File’ from the menu there should be an entry for the archive program with several sub-entries, among them ‘Extract to…’ . I hope you've found that. Otherwise you should ask someone to help you.

Extract the archive with the Batik binary to your program files folder. For the remainder of this document wherever I write C:\Program Files this is supposed to be read as ‘the folder to which you've extracted the batik archive’ which can be any folder you prefer.

After extracting the archive there should be a new folder C:\Program Files\batik-1.7. I'm assuming that the Batik version you use is 1.7. Wherever I write 1.7 read it as the appropriate version number.

create batch files

When you have installed Java, and downloaded and unpacked the Batik binary then you can use the Batik tools from the command line. But that's unsatisfactory, in my opinion. Now, let's start making the usage of Batik easier.

To do this we first create some batch files. As far as this tutorial goes, batch files are just files containing commands which we wish to use more often. Storing these commands in batch files saves us from the need to enter them to the command line each time.

screenshot, save batch file To create a batch file, start a plain text editor, like the Windows Notepad; write the command or commands you wish to execute; and save the text under a file name ending with the extension ‘.bat’. When saving, be sure to set the file type filter to ‘All files (*.*)’. Otherwise, some text editors would automatically add the extension ‘.txt’ so that the file name would be e.g. ‘svg2png.bat.txt’ and the file is then not recognized as a batch file.

I will assume that you create a new folder named ‘Batch’ in C:\Program Files and save your batch files to C:\Program Files\Batch. If you save them to a different location then read later references to the Batch folder accordingly.

One advantage of having a folder for batch files is that you can add that folder to the Windows search path to make using the batch files from the command line interface easier. But using the command line is not what this tutorial is about. Let me just note that adding a folder to the search path requires changing a file named AutoExec.bat and is not more complicated than what is explained in this tutorial. But if you break the Autoexec.bat that's no fun, so I'd rather not give a half-baked explanation here.


Below are some suggested file names and corresponding commands which I consider useful. You can select a text (if Javascript is enabled in your browser then clicking at any of the text areas is sufficient to select the text therein), copy it by pressing Ctrl + ‘C’ or Ctrl + Ins, and paste it into your text editor by pressing Ctrl + ‘V’ or Shift + Ins.

Depending on which Batik version you use and which folder you've unpacked it to you might need to change the paths given in the batch files. Using absolute paths–not paths pointing to the .jar files relative to the location of the batch file–is necessary, at least in those batch files which contain a ‘%1’.

I suppose you get the basic idea of how this works. Let me just explain the parts with the percent signs. ‘%ProgramFiles%’ is a reference to an environment variable which stores the default program files location. For a Windows installation in English language this usually is ‘C:\Program Files’. In this case the commands will be interpreted as if we'd write ‘C:\Program Files’ instead of ‘%ProgramFiles%’.

With the ‘%1’ we use an argument which would be given to the batch file. When you enter

"C:\Program Files\Batch\svg2png.bat" example.svg

on the command line then the batch file will be executed as if ‘example.svg’ would be in place of ‘%1’. If a file named example.svg exists in the current directory, this will result in creating a rasterized PNG image based on example.svg. But we're going to use these batch files with actions later, so we won't need the command line at all.

When you've created the batch files then open the folder in which you have saved them in Windows Explorer and double-click at batikHelp.bat. This will create three text files in the same folder, named rasterizerOptions.txt, prettyPrinterOptions.txt and fontConverterOptions.txt. These files contain lists of the command line options you can use with the respective tools.

One obstacle here is that in these files line breaks are saved in a different way than what Windows applications usually use. Maybe you'll have to change the line breaks manually in order to have a well arranged overview of the options. Also the Batik font converter writes it's usage instructions not to the standard output stream but to a stream for error messages. The syntax I've used to redirect that error stream to the text file does not work on older Windows versions. And I have not tested it on a Windows system on which it does work, so maybe it's not really the correct syntax for newer versions either.

You can also find explanations of the command line options at the pages linked at http://xmlgraphics.apache.org/batik/tools/index.html. You'll need these options when you wish to customize the batch files.

()





create a shortcut to Squiggle

When you're done creating the batch files you can start Batik's SVG browser Squiggle by double-clicking Squiggle.bat. When in Windows Explorer you select the batch file and choose “File”, “Create shortcut” from the menu then you create a link to that batch file. It will appear in the same folder and run by the name of ‘Shortcut to Squiggle.bat’. You can rename it to ‘Squiggle’ and move it via drag and drop to the Start menu or the desktop or wherever you'd like to have it.

You can also create multiple shortcuts to the same file. If you later change the batch file, for example to set the font-size option, then using each shortcut will start Squiggle with the same options you've added to the batch file.

creating the file type SVG Document

The SVG file type is most probably registered with your system already. When your system does not know the file type SVG yet then SVGs will be represented by some general icon (on my system it's a white sheet with the Windows symbol on it), in the file properties the type is given as ‘File SVG’, and the most accurate indicator is that the “File” menu offers “Open with…” instead of “Open”.

If your system does not know the file type SVG then my advice is to go to http://www.adobe.com/svg/viewer/install/ to download and install the Adobe SVG Viewer. The installation program will create the filetype ‘SVG Document’ with the MIME type ‘image/svg+xml’, associate it with the extensions ‘.svg’ and ‘.svgz’ and create the “Open” action for it.

You can also create the file type manually. Instructions for doing so might get added to later versions of this document. Also there is a number of other applications which would register the file file type on installation. Some people will disagree, but I think that installing the Adobe SVG Viewer is the most convinient solution currently. I suspect that it's the way the file type was introduced to most Windows systems on which it exists.

create actions

Now we will create actions for the file type ‘SVG Document’ and also one action for the file type ‘True Type Font’. Actions are the options appearing on top of the “File” menu of Windows Explorer when one file is selected and also on top of the pop-up menu appearing when you right-click one file. What happens when you double-click a file is the default action for that file type–in most cases it's ‘open’. Actions are often created automatically while you install new programs. For Batik we need to create the actions manually.

I will assume here that the file type associated with the extensions ‘.svg’ and ‘.svgz’ is named ‘SVG Document’. That's how it is named when created by the ASV installer. On your system the name might be different (for example ‘IrfanView SVG File’).

Let's first create the action “create PNG”.

screenshot, Folder Options

Open Windows Explorer and select “Tools”, “Folder Options…” to display the ‘Folder Options’ dialog box. (Or maybe it's “View”, “Folder Options…” on your system. Just search for “Folder Options…”.)

In the ‘Folder Options’ dialog box select the tab ‘File Types’. There you see a list of registered file types, ordered alphabetically. Select “SVG Document” from the list. To find it you can press ‘T’ on your keyboard to jump directly to the first file type starting with the letter ‘T’ and search from there upward. If the file type for SVG has a different name on your system, not starting with ‘SVG’, then remember that you'll have to find that name in the list.

When you've selected the file type you wish to edit then click the “Advanced” (or maybe it's “Edit” on your system) button to open the ‘Edit File Type’ dialog box.


screenshot, Edit File Type In this dialog we're interested in the ‘Actions’ associated with the file type. Click “New…” to open the ‘New Action’ dialog.

screenshot, New Action

In the ‘New Action’ dialog box enter “create PNG” in the ‘Action’ text box and “"C:\Program Files\Batch\svg2png.bat"” (with quotation marks) in the ‘Application Used to Perform Action’ text box. I'm assuming here that is the path to which you've saved the batch files. Otherwise you will need to adapt the path accordingly.

Click “OK”. Now the action “create PNG” should appear in the ‘Edit File Type’ dialog box.

In the same way you've created the action “create PNG” you can now create an action named “create PDF” referencing the batch file ‘svg2pdf.bat’ and an action named “pretty print” referencing the batch file ‘svgpp.bat’.

After creating the actions click “OK” to close the ‘Edit File Type’ dialog. Then click “Close” (or maybe it's “OK” again) to close the ‘Folder Options’ dialog.

Before you go testing your new actions, one word of caution: Read the section about the problem of DOS 8.3 filenames below. You won't run into trouble if you start experimenting with the files in C:\Program Files\batik-1.7\samples. But when you start processing SVG files you might have stored somewhere on your disk then it is at least possible that you accidently overwrite files when you're not aware of the pitfalls I explain below.

And now there's one more action to create. Open “Folder Options”, “File Types” again. This time select the file type ‘True Type font’. Open the “Edit File Type” dialogue. Click “New…” to create a new action. This action we call “create SVG Font file” and make it reference our ttf2svg.bat file. Now we can convert True Type fonts to SVG fonts.

Problems

the problem of DOS 8.3 filenames

Let's assume we have a folder in which there is an SVG file named ‘page1_figure1.svg’ and also a PNG file named ‘page1_figure2.png’. If in the command line interface we change the current directory to that folder and then enter

"C:\Program Files\Batch\svg2png.bat" page1_figure1.svg

then the Batik rasterizer will create a file ‘page1_figure1.png’ in that directory. We would assume that we can do the same by using the “create PNG” action we have created for that purpose. But that's not absolutely true, because when we call an action on one file then Windows will give the DOS 8.3 filename of that file as a parameter to the application for that action.

File names in MS-DOS consist of a base name of not more that eight characters and an extension (the part after the last period) of not more than three characters. Although modern versions of Microsoft Windows support longer filenames, 8.3 filenames are still used internally to support older programs. You can look at “File”, “Properties” to see a file's 8.3 filename.

In our example the SVG document would have the MS-DOS filename ‘PAGE1_~1.SVG’. Actually that depends on what other files starting with ‘PAGE1_’ exist or have existed in the folder before, but chances are that this is the 8.3 name of that file. Now when that filename is given to the Batik rasterizer it will be able to open the file. Both the long filename and the 8.3 filename can be used to access that same file.

The problem with this is that the rasterizer will derive the filename for the output file from the filename given to it. In this case it will write to ‘PAGE1_~1.png’. That's not so beautiful, but in most cases won't cause any trouble. In this case however we have assumed that there also is a file named ‘page1_figure2.png’ in the same folder. Can you guess what that file's 8.3 name probably is? The correct answer is ‘PAGE1_~1.PNG’. (Not ‘PAGE1_~2.PNG’ which you might also have guessed.)

So when you use the action to create a PNG the rasterizer will overwrite the existing PNG file of a different filename in the same folder.

To avoid such problems it's wise to take care that filenames differ in their first six characters. There surely are more advanced ways to get around this problem. But I haven't found one yet.

With the font converter and the pretty printer things work a bit different. Both do by default not write to files but to the standard output stream. So I have to derive a filename for the output file myself.

In batch programming there seems to be no simple way to extract the base name from a filename. The way I helped myself here is that when, for example, you convert a True Type font with the 8.3 filename ‘HELVET~1.TTF’ to an SVG font then the output will be written to ‘HELVET~1.TTF.svg’. This is not a legal 8.3 filename and it is also improbable that it is the long filename of any existing file. So you won't overwrite files with the font converter, except for previous attempts of the same conversion.

The pretty printer does actually write only to the standard output. You may find that overwriting the source SVG with the pretty printed version of the same SVG would be okay for your purposes. But this would need a bit more knowledge of batch programming than I can offer, because before you overwrite the source file you would want to check that the pretty printer did not throw an exception.

empty SVG Fonts

I've had the problem that with some True Type fonts the font converter did create SVG documents with no glyph tags. I found that this problem was solved by explicitly specifying the range of characters to be converted, by using the -l and -h options. I did not include these options in the batch files listed above, since I'm not sure what would be reasonable values for a general font conversion command.

License

This Document is licensed under the Apache License, Version 2.0. (The same license which is applied to Batik. I guess this is convenient. At least it doesn't require you to read one more license.) Let me try to give you an idea of what this means. What follows now is just an informal description and is not even intended to be fully exact. Only the actual text of the License is legally binding, and reading the explanation below does not release you from the obligation to read the License.

The License grants you permission to distribute copies of this document. My intention, of course, is that when you distribute copies of Batik you should be allowed to include this tutorial. Especially for offline copies just including a link to the online version of this tutorial might be insufficient.

The License also permits you to make changes to this document and redistribute the changed version. But you must apply the same license to any modified version which you distribute. You are not allowed to remove copyright notices (or patent, trademark, or attribution notices.) And you must add a notice stating that you have changed the file. Modifications are not only allowed, but definitely welcomed. In fact I've compiled some ideas for improvements in the file propositions.txt.

This document was actually created from a PHP document. So if you intend to modify it I ask that you download the archive file batikinstall_doc_win.tgz which contains the PHP source. (Although the source file has the extension ‘.html’ and also works as an HTML file for local use.) The archive file also contains propositions.txt and a copy of the Apache License, Version 2.0.

The archive file batikinstall_doc_win.tgz would also be convenient if you don't plan to do modifications. It contains ready-made batch files.

This file was downloaded from http://frabru.de:80/batikinstall_doc_win/batikinstall.php?r=%2Fc.php%2Farticle%2F&rt=Articles

Copyright 2008-2010 Frank Bruder

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.

home page of the Apache Batik Project
top of this page
return to Articles