<?xml version="1.0"?>

<!--

   Licensed to the Apache Software Foundation (ASF) under one or more
   contributor license agreements.  See the NOTICE file distributed with
   this work for additional information regarding copyright ownership.
   The ASF licenses this file to You 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.

-->

<!-- ====================================================================== -->
<!-- author vincent.hardy@eng.sun.com                                       -->
<!-- author cjolif@ilog.fr                                                  -->
<!-- version $Id$ -->
<!-- ====================================================================== -->

<!DOCTYPE faqs PUBLIC "-//APACHE//DTD FAQ V2.0//EN" "http://forrest.apache.org/dtd/faq-v20.dtd">
<faqs>
  <title>Frequently Asked Questions</title>

  <part id="part-general">
    <title>General questions</title>

    <faq id="what-is-batik">
      <question>What is Batik?</question>
      <answer>
        <p>
          Batik is a Java-based toolkit for applications or applets that want
          to use images in the <a href="site:svg11">Scalable
            Vector Graphics (SVG)</a> format for various purposes, such as
          display, generation or manipulation.        
        </p>
      </answer>
    </faq>

    <faq id="what-is-svg">
      <question>What is SVG?</question>
      <answer>
        <p>
          <a href="site:svg11">SVG</a> (Scalable Vector
          Graphics) is an open-standard language for describing 
          two-dimensional (2D) graphics in XML. It is a Recommendation from the 
          <a href="http://www.w3.org/">W3C</a>. SVG lets you describe rich images
          with features such as gradients, transparency, filter effects and animation.
        </p>
        <p>
          SVG has three types of graphic objects: shapes (e.g., paths consisting 
          of straight lines and curves), images and text. Graphical objects can be grouped, 
          styled, transformed and composited (e.g., drawn with transparency). SVG has a 
          large set of static features which includes nested transformations, clipping 
          paths, masking and filter effects.
        </p>
        <p>
          In addition, SVG images can be dynamic and interactive. A rich set of event
          handlers such as for mouse movement and clicks can be assigned to any SVG
          graphical object. These handlers can invoke scripts, which, in response to an
          event, can dynamically modify the SVG graphic through the SVG Document Object Model
          (DOM) API, allowing, for example scripts to change the color or location of graphical 
          elements.
        </p>
        <p>
          SVG graphical elements can be animated through scripting. Alternatively,
          animation sequences can be expressed directly in XML because SVG leverages the
          <a href="site:smil">SMIL Animation</a>
          specification for multimedia, another
          <a href="http://www.w3.org/">W3C</a> specification. 
        </p>
      </answer>
    </faq>

    <faq id="what-can-i-do">
      <question>What can I do with Batik?</question>
      <answer>
        <p>
          Batik contains several <a href="site:architecture">core modules</a>
          which can be used independently or jointly to <strong>generate SVG
            content</strong> (see the <a href="site:generator">SVG Generator</a>
          and <a href="site:dom-api">SVG DOM</a> implementation documentation)
          <strong>view SVG content</strong> (see the <a href="site:swing">JSVGCanvas</a>)
          or <strong>convert to and from the SVG format</strong> (see the 
          <a href="site:transcoder">SVG Transcoder</a> page).
        </p>

        <p>
          In addition, Batik contains
          <a href="using/architecture.html#lowLevelComponents">low level
            modules</a>, such as an object-oriented Graphic Vector Toolkit
          (GVT), a set of low level parsers specific to the SVG syntax and a
          set of <a href="site:extending">extensions</a> to the Java 2D API
          (such as sophisticated fill types and filter effects).
        </p>

        <p>
          Finally, Batik comes with <a href="site:tools">packaged applications</a> to help developers get
          familiar with the code and be quickly able to use the various modules: Squiggle, an
          <a href="site:browser">SVG browser</a> (in the 
          <code>org.apache.batik.apps.svgbrowser</code> package) an 
          <a href="site:rasterizer">SVG rasterizer</a> (in the 
          <code>org.apache.batik.apps.rasterizer</code> package), a
          <a href="site:font-converter">Font converter</a> (in the
          <code>org.apache.batik.apps.ttf2svg package</code>) and an 
          <a href="site:pretty-printer">SVG pretty printer</a> (in the 
          <code>org.apache.batik.apps.svgpp package</code>).</p>
        <p>
          Squiggle, the <a href="site:browser">SVG browser</a> can display SVG
          documents and lets the user zoom, pan and rotate any SVG document,
          view the SVG source, link between SVG documents, view a tree
          representation of the SVG DOM and more. One important component of
          the SVG viewer is the <code>org.apache.batik.swing.JSVGCanvas</code>
          component, which can be plugged in to any Java application or applet
          to provide SVG viewing capability.
        </p>
        <p>
          The <a href="site:rasterizer">SVG rasterizer</a>
          lets the user convert
          SVG files to raster formats such as JPEG, PNG or TIFF . It
          contains an extensible mechanism so that arbitrary raster
          formats can be added. For example, the rasterizer lets you
          create one SVG file with a special effect (e.g., shadows,
          gradients, etc.), turn it into a PNG image, then modify the
          SVG source (e.g., modify a piece of text or a color), and
          generate another PNG image from it. This way, you can easily
          generate a series of images sharing a common theme or look and
          feel to post on a web site. (Note that the rasterizer can also
          be used on a web server to do this conversion automatically).
        </p>
        <p>
          The <a href="site:font-converter">SVG Font Converter</a>
          lets the user easily create
          an <a href="http://www.w3.org/TR/SVG11/fonts.html">SVG
            Font</a> for a set of characters from a TrueType Font
          file. That SVG Font definition can be embedded in a document
          using the characters. This allows users to create SVG
          documents that are self contained and do not rely on system
          fonts, and guarantees that the SVG file will be displayed
          exactly as it was authored on all platforms.
        </p>

        <p>
          The <a href="site:pretty-printer">SVG Pretty Printer</a>
          is a convenience tool to
          pretty print an SVG document, which means that you can
          reformat any existing SVG document to produce a nicely
          formatted and highly legible version.
        </p>
        <p>
          These applications show that Batik can be used client side
          (the browser can be used on any client machine) and server
          side (the rasterizer can be used to serve SVG images to client
          machines that do not have SVG support).
        </p>
      </answer>
    </faq>

    <faq id="why-at-apache">
      <question>Why do we have such a project at Apache?</question>
      <answer>
        <p>
          The <a href="http://xmlgraphics.apache.org/charter.html">mission
            of the Apache XML Graphics Project</a> is to promote the use of
          XML-based graphics by “providing robust, full-featured,
          commercial-quality, and freely available software packages for the
          conversion of XML to graphical output and for related components”.
          Batik as an open source implementation of a key format for today’s
          and tomorrow’s web fits well in this mission.
        </p>
      </answer>
    </faq>

    <faq id="how-does-batik-relate">
      <question>How does Batik relate to other Apache projects?</question>
      <answer>
        <p>
          Batik is used in <a href="http://cocoon.apache.org/">Cocoon</a> 
          for server side rasterization of SVG images. In addition, the Batik is used in the 
          <a href="http://xmlgraphics.apache.org/fop/">FOP</a> project to convert 
          SVG images to PDF format.
        </p>
      </answer>

    </faq>

    <faq id="how-did-it-start">
      <question>How did it start?</question>
      <answer>
        <p>
          Batik started out because several teams doing SVG related projects decided to join 
          efforts with the idea that the whole will be greater than the sum of the parts. The
          following companies or institutions are part of the team that contributed and/or
          created the initial Batik project, during the fall of 2000:
        </p>
        <ul>
          <li><a href="http://www.csiro.au/">CSIRO</a></li>
          <li><a href="http://www.ilog.com/">ILOG</a></li>
          <li><a href="http://koala.ilog.fr/">Koala Team</a></li>
          <li><a href="http://www.kodak.com/">Eastman Kodak Company</a></li>
          <li><a href="http://www.sun.com/">Sun Microsystems, Inc.</a></li>
        </ul>
        <p>
          In addition, the Batik project is supported by <a href="http://www.ibm.com/">IBM</a>.
        </p>
        <p>
          We encourage anyone to participate. As with all ASF projects, all efforts are
          volunteer-based. We are looking for individuals to work with us on
          fulfilling our goals for Batik in the spirit of collaborative open-source
          software development.
        </p>
      </answer>

    </faq>

    <faq id="what-is-next">
      <question>Where is Batik going? What is next?</question>
      <answer>
        <p>
          The SVG implementation is not complete (see the current
          <a href="site:status">status</a>), and there is more work to
          do to achieve a fully functional viewer.
        </p>

        <p>
          Batik 1.1 supports all static SVG features, 
          linking and a limited support for scripting, and the 1.5 release
          completed support for scripting and dynamic documents.
          With Batik 1.6 came many improvements to
          the implementation of SVG DOM functions, bug fixes, performance
          improvements, and the beginning of some SVG 1.2 support.
          Declarative animation and some SVG 1.2 features were introduced
          in Batik 1.7beta1.  The 1.7 release brought mostly bug fixes.
          Completion of remaining SVG 1.1 functionality and the addition
          of Further SVG 1.2 functionality should be supported in the 2.0
          release.
        </p>
        <p>
          The type of applications (e.g., transcoding applications)
          that can or will be added to Batik depends on contributions
          and feedback.
        </p>
      </answer>

    </faq>

    <faq id="how-can-i-create-svg">
      <question>How can I create and author SVG content?</question>
      <answer>
        <p>
          Well, you can always use a plain text editor such as vi or
          xemacs, but there are many graphic authoring packages that can
          export SVG documents and that will let you author SVG content
          visually.
        </p>
        <p>
          You can get a list of tools exporting SVG from the <a
            href="http://www.w3.org/Graphics/SVG/SVG-Implementations#edit">SVG
            implementation</a> section of the SVG Home page on the W3C
          web site. You can also imagine building a tool on top of
          Batik: feel free to contribute!
        </p>
        <p>
          Authoring is one way of creating SVG content, and graphic
          authoring packages are useful for that purpose. However, there
          are many types of graphics which can be generated, such as
          stock quotes, statistical data, etc. For these types of
          graphics, there are many ways to generate SVG content. For
          example, if your data (say stock information) is contained in
          an XML document, you could use XSLT to transform your XML data
          into SVG. If your data comes from a database and you retrieve
          that data in a servlet on a Web server (e.g., using JDBC), you
          could use the Java binding for the DOM API to generate an SVG
          document from the database data. You could also use Batik’s
          SVG generator and use the Java 2D API to generate that
          graphic.
        </p>
        <p>
          The following URLs will be useful to learn more about each of 
          these solutions:
        </p>
        <ul>
          <li><a href="http://xml.apache.org/xalan-j/index.html">Xalan for XSLT</a></li>
          <li><a href="http://xml.apache.org/xerces-j/index.html">Xerces</a> and
            <a href="http://java.sun.com/xml/download.html">Crimson</a> for the DOM API</li>
          <li><a href="site:generator">SVG Generator</a></li>
        </ul>
      </answer>
    </faq>

    <faq id="what-other-svg-products-exist">
      <question>What other SVG products are out there?</question>
      <answer>
        <p>
          There are many companies supporting SVG and you will find a list of 
          available implementations on the
          <a href="http://www.w3.org/Graphics/SVG/SVG-Implementations">W3C’s SVG
            implementation page</a>.
        </p>
      </answer>
    </faq>

    <faq id="svg-spec">
      <question>Where can I find the SVG specification?</question>
      <answer>
        <p>
          The <a href="site:svg11">SVG specification</a> is
          available from the <a href="http://www.w3.org/">W3C web site</a>. 
        </p>
      </answer>
    </faq>

    <faq id="how-much-does-batik-implement">
      <question>How much of SVG does Batik implement?</question>
      <answer>
        <p>
          The <a href="site:status">status page</a> shows how much of the SVG
          specification Batik implements by showing which of the tests in the
          <a href="status.html#beSuiteStatus">SVG Basic Effectivity test
            suite</a> Batik successfully passes.
        </p>
      </answer>
    </faq>

    <faq id="benefits-of-svg-being-xml">
      <question>What are the benefits of SVG being an XML grammar?</question>
      <answer>
        <p>
          Being an XML grammar means SVG can leverage work done around
          XML, and SVG actually leverages other grammars such as
          <a href="http://www.w3.org/TR/2001/REC-xlink-20010627/">XLink</a>,
          for linking and
          <a href="http://www.w3.org/TR/2001/REC-smil-animation-20010904/#AnimationFramework">SMIL</a>
          for the animation.
        </p>
        <p>
          Beyond the use and mix with other XML syntaxes, being an XML grammar
          lets SVG benefit from the plethora of XML tools that make it so easy
          to manipulate, generate, search and edit XML files.
        </p>
      </answer>
    </faq>

    <faq id="what-is-in-a-name">
      <question>Where does the name come from?</question>
      <answer>
        <p>
          Batik is a highly evolved art tradition that developed in Java
          (one of the islands comprising what is now called
          Indonesia). Batik is generally thought of as the quintessentially
          Indonesian textile. Motifs of flowers, twining plants, leaves,
          buds, birds, butterflies, fish, insects and geometric forms are
          rich in symbolic association and variety; there are about three
          thousand recorded batik patterns.
        </p>
        <p>
          We think that Batik gracefully evokes Java, graphics and
          high-quality, terms that constitute the core of the toolkit.
        </p>
        <p>
          <a href="http://www.expat.or.id/info/batik.html">This page</a>
          shows examples of what Batik textures look like.
        </p>
      </answer>
    </faq>
  </part>

  <part id="batik-help">
    <title>Getting started with Apache Batik/SVG</title>

    <faq id="system-requirements">
      <question>What are the system requirements to run Batik?</question>
      <answer>
        <p>
          Batik is written in the Java language and requires a version 1.4
          implementation at this time. 
        </p>
      </answer>
    </faq>

    <faq id="how-to-install">
      <question>How do I install Batik?</question>
      <answer>
        <p>
          You will need a <a href="http://java.sun.com/">JRE/JDK</a> version
          1.4 or above to run Batik.
        </p>
        <p>
          To install Batik you need to <a href="site:download">download</a>
          the binary or source distribution and unzip it on your computer.
        </p>
        <p>
          You can have a look at the <a href="site:install">installation
            instructions</a> for more information.
        </p>
      </answer>
    </faq>

    <faq id="how-can-i-see-demo">
      <question>How can I see a demo?</question>
      <answer>
        <p>
          You can see an online demonstration of Squiggle the SVG
          browser on the <a href="site:demo">demo page</a>. Alternatively, you
          can <a href="site:download">download</a> Batik or see
          <a href="site:browser">screenshots</a> of the Batik SVG viewer,
          images created from the <a href="site:rasterizer">rasterizer</a> and
          an <a href="site:generator">example</a> of how to use the
          <code>SVGGraphics2D</code> generator.
        </p>
      </answer>
    </faq>

    <faq id="what-scripting-languages-batik-supports">
      <question>What scripting languages can I use in my SVG files?</question>
      <answer>
        <p>
          A limited support of scripting in SVG files is provided with
          the current version of Batik (script are executed but dynamic
          update is not supported).
        </p>
        <p>
          Batik can recognize the following scripting languages:
        </p>
        <ul>
          <li>
            ECMAScript thanks to the
            <a href="http://www.mozilla.org/rhino/">Mozilla Rhino</a> JavaScript
            engine included in the distribution,
          </li>
          <li>
            Python for which you need to download the
            <a href="http://www.jython.org">Jython</a> engine, and
          </li>
          <li>
            Tcl for which you need to download the
            <a href="http://dev.scriptics.com/software/java/">Jacl</a> engine.
          </li>
        </ul>
        <p>
          To get more information on how to install optional
          scripting languages you can have a look at the
          <a href="site:install">installation instructions</a>.
        </p>
      </answer>
    </faq>
  </part>

  <part id="batik-error">
    <title>Troubleshooting Apache Batik</title>

    <faq id="NoSuchMethodException">
      <question>
        When I try to run Batik it results in a NoSuchMethodException.  What
        is the problem?
      </question>
      <answer>
        <p>
          There is certainly something wrong with your classpath. Clear your
          <code>CLASSPATH</code> environment variable and be sure to remove
          all the libraries which use the W3C’s DOM bindings from
          <code>jre/lib/ext</code> before running any of the Batik’s
          applications.
        </p>
      </answer>
    </faq>

    <faq id="display-does-not-update">
      <question>
        When I change the document in Java it doesn’t update the
        display, even if I call repaint?
      </question>
      <answer>
        <p>
          There are two common causes for this.  The first is that the
          <a class="class" href="javadoc/org/apache/batik/swing/JSVGCanvas.html">JSVGCanvas</a>
          doesn’t know it’s a dynamic document.  Normally
          Batik detects this by looking for script elements but when you
          modify the document from Java it can’t tell.  So call
        </p>
        <source>myJSVGCanvas.setDocumentState(JSVGCanvas.ALWAYS_DYNAMIC);</source>
        <p>
          before loading the document (with <code>setURI</code>,
          <code>setDocument</code>, <code>setSVGDocument</code>, etc.).
        </p>
        <p>
          The second common reason is that the changes aren’t made in
          the
          <a class="class" href="javadoc/org/apache/batik/bridge/UpdateManager.html">UpdateManager</a>’s
          thread.  You can run code in the <code>UpdateManager</code>’s thread
          with the following:
        </p>
        <source>UpdateManager um = JSVGCanvas.getUpdateManager();
um.getUpdateRunnableQueue().invokeLater(Runnable);</source>
        <p>
          <strong>NOTE:</strong> The update manager only becomes
          available after the first rendering completes.  You can
          be notified when this happens by registering a 
          <code>GVTTreeRendererListener</code>.
        </p>
      </answer>
    </faq>
    <faq id="must-mouseover-to-change">
      <question>
        When I change the document in Java it only updates if I
        move the mouse over the canvas?
      </question>
      <answer>
        <p>
          The most common causes for this, is that the changes are not made in
          the <code>UpdateManager</code>’s thread.  See previous FAQ for
          example code to run code in the Update Manager’s thread.  Moving the
          mouse works because it delivers the mouse move events in the update
          thread, and after a runnable completes in the
          <code>UpdateManager</code>’s thread it checks if the canvas needs
          repainting.
        </p>
      </answer>
    </faq>
    <faq id="changes-are-not-rendered">
      <question>
        When I create new SVG elements or modify some SVG attributes through
        the DOM API, from ECMAScript, nothing happens, the changes are not
        rendered. Why not?
      </question>
      <answer>
        <p>
          A common problem is that script contain the wrong DOM calls
          to create elements or modify attributes.
        </p>
        <p>
          SVG elements need to be created in the SVG namespace. For example,
          to create a <code>rect</code> element, you should use
        </p>
        <source>document.createElementNS(svgNS, "rect");</source>
        <p>
          (where <code>svgNS</code> is equal to
          <code>"http://www.w3.org/2000/svg"</code>), which appropriately
          creates the <code>rect</code> element in the SVG namespace. A call to
        </p>
        <source>document.createElement("rect")</source>
        <p>
          creates an element with the name <code>rect</code> but which does not
          belong to the SVG namespace. As such, it is ignored by Batik.
        </p>
        <p>
          Most SVG attributes belong to what is called the “per element type 
          partition namespace” (see the
          <a href="http://www.w3.org/TR/REC-xml-names">Namespaces in XML</a>
          specification). The appropriate way to set attributes on an SVG
          element is a call to <code>setAttributeNS</code> with a namespace
          value of <code>null</code>, for example:
        </p>
        <source>elt.setAttributeNS(null, "width", "40");</source>
        <p>
          In the Batik SVG DOM implementation, you can also use a call to
          <code>setAttribute</code> and you can write
        </p>
        <source>elt.setAttribute("width", "40")</source>
        <p>
          However, it is important to know that some implementations make a
          difference between <code>setAttribute(x, y)</code> and
          <code>setAttributeNS(null, x, y)</code>, so it is goo practice
          to use <code>setAttributeNS</code> which is the only guaranteed
          interoperable way of setting attributes in a namespace aware DOM
          implementation.
        </p>
        <p>
          Finally, for attributes which belong to a specific namespace, like the 
          the <code>href</code> attribute on the <code>image</code> element,
          you have to use the <code>setAttributeNS</code> method with the
          XLink namespace.  For example, assuming <code>img</code> references an 
          <code>image</code> DOM <code>Element</code>, you can modify the 
          href as follows:
        </p>
        <source>img.setAttributeNS(xlinkNS, "xlink:href", "myImage.jpg");</source>
        <p>
          where <code>xlinkNS</code> is equal to
          <code>"http://www.w3.org/1999/xlink"</code>.
        </p>
        <p>
          For more information on common authoring pitfalls, see Jonathan Watt’s 
          <a href="http://jwatt.org/svg/authoring/">SVG Authoring
            Guidelines</a>.
        </p>
      </answer>
    </faq>

    <faq id="null-updatemanager">
      <question>
        When I get the UpdateManager from the canvas sometimes
        it is null, why?
      </question>
      <answer>
        <p>
          The <code>JSVGCanvas</code> is highly asynchronous so when you call
          <code>setURI</code>, <code>setDocument</code> or
          <code>setSVGDocument</code> they return essentially immediately.
          Behind the scenes, the canvas creates the rendering tree and does a
          first rendering after dispatching the document <code>SVGLoad</code>
          event.  Only after this first rendering does the
          <code>UpdateManger</code> become available.
        </p>
      </answer>
    </faq>

    <faq id="why-updatemanager">
      <question>
        Why do I have to go through the UpdateManager to
        run my code? Can’t you just synchronize the DOM?
      </question>
      <answer>
        <p>
          It would be possible to synchronize individual calls to
          the DOM, however in general this is almost useless for the
          way DOM works.  For example creating a single rectangle
          element takes approximately 6 individual DOM calls.  So
          higher level synchronization is needed.
        </p>
        <p>
          The use of a
          <a class="class" href="http://java.sun.com/j2se/1.5.0/docs/api/java/lang/Runnable.html">Runnable</a>
          is a common way of accomplishing synchronization for a block of code.
          This is essentially the approach that Swing takes (all Swing
          modification should take place in the Swing thread).  It was
          considered to use the Swing event thread, but this would lock the
          user interface while scripts were working.
        </p>
      </answer>
    </faq>

    <faq id="extension-tags-work-with-source-not-binary">
      <question>
        I can use the Batik extension tags with the source distribution
        but not with the binary distribution.  What am I missing?
      </question>
      <answer>
        <p>
          When running from the source distribution you automatically get the
          service provider entries for the Batik extension elements
          (such as <code>regularPolygon</code> and <code>star</code>).
          We chose not to include these by default in the
          binary distribution for the Batik applications.
        </p>
        <p>
          There is a subdirectory called <code>extensions</code> that has jar
          files that enable the extended elements from Batik.
        </p>
      </answer>
    </faq>

    <faq id="red-circles">
      <question>
        Why do I get red circles when I view the samples/extensions files?
      </question>
      <answer>
        <p>
          You are using the binary distribution. This distribution does not
          include support for our example extensions (they are just examples
          and other people can do more sophisticated things).
        </p>
        <p>
          If you want to view these examples you need to use the extension
          enabled versions of the applications in the <code>extensions</code>
          subdirectory.
        </p>
      </answer>
    </faq>

    <faq id="dom-modifications-do-not-display">
      <question>
        I am modifying the DOM after displaying it in the JSVGCanvas,
        but my changes aren’t shown (even if I call repaint).
      </question>
      <answer>
        <p>
          For efficiency, if Batik loads a static document it doesn’t
          set up any dynamic support.  Batik normally decides whether a
          document is dynamic by checking if it contains any
          <code>script</code> elements or event handler attributes.  However,
          if your Java application is modifying the DOM directly there may be
          no script elements.  In this case you need to tell Batik to set up
          dynamic support regardless.
        </p>
        <p>
          You can inform the <code>JSVGCanvas</code> that a document should
          be handled dynamically by calling the <code>setDocumentState</code>
          method, just before loading the document:
        </p>
        <source>JSVGCanvas myCanvas = ...;
myCanvas.setDocumentState(JSVGCanvas.ALWAYS_DYNAMIC);
myCanvas.setURI("myFile.svg");</source>
      </answer>
    </faq>

    <faq id="batik-fails-with-fop-on-org.w3c.xxx">
      <question>
        I am trying to use Batik and FOP together but Batik does not work and
        fails on the <code>org.w3c.</code>* packages. What is happening?
      </question>
      <answer>
        <p>
          Both FOP and Batik use the <code>org.w3c.</code>* packages.
          Depending on the version of FOP and Batik, Batik has been using a
          version of these packages which is more recent than the one in the
          <code>xml-apis.jar</code> file FOP uses. However, if the
          <code>xml-apis.jar</code> file that comes with the FOP distribution
          is loaded before the Batik jar files, then the version coming with
          FOP takes precedence (i.e., that is the version the Java Virtual
          Machine loads). Because that version is incompatible with Batik, you
          encounter this problem.
        </p>
        <p>
          The solution is to either repackage the <code>xml-apis.jar</code> file
          with the classes in the Batik distribution (you will need the Batik
          source distribution to do that), or you will need to make sure the
          Batik jars are loaded before FOP’s <code>xml-apis.jar</code>, for
          example by putting Batik’s jar file before FOP’s in your classpath.
          If you are copying your jar files to <code>.../jre/lib/ext</code>,
          you can simply remove the FOP <code>xml-apis.jar</code> file from
          that directory.
        </p>
      </answer>
    </faq>

    <faq id="how-to-checkout-latest-batik-via-svn">
      <question>
        How do I checkout the latest SVN version of Batik?
      </question> 
      <answer>
        <p>
          You just have to follow the instructions on the
          <a href="site:download">download page</a>.
        </p>
      </answer>
    </faq>

    <faq id="mac-os-x-messed-up-svg-files">
      <question>
        I’m using Mac OS X, and some of the SVG files I view are messed up
        (things appear clipped or out of place).  What do I need to do to fix
        this?
      </question> 
      <answer>
        <p>
          As of Mac OS X release 10.1.1 there still appears to be
          problems in the Apple implementation of the Java 2D APIs. The
          true source of these problems and/or workarounds have yet to be
          identified (although the problems appear to be closely tied to a
          “gstack underflow” error message from the Apple JVM). We are
          interested in finding the source of these problems and
          reasonable workarounds, so if you know what causes these errors
          the Batik team would be very interested in hearing from you
          (either directly or through the user/developer mailing lists).
        </p>
        <p>
          Other things to be aware of on Mac OS X, due to fixes for
          other problems with Java 2D under Mac OS X, you may find that
          some filtering operations take significantly more memory than on
          other platforms.  This will be especially true for deeply nested
          filter trees (where the result of one filtering operation is
          filtered by another filtering operation).
        </p>
        <p>
          Finally a few hints on avoiding problems under Mac OS X. The
          bugs seems to be triggered by filters, and pure raster SVG documents
          have not been found to cause problems.  The use of the
          <code>filterRes</code> attribute on the <code>filter</code> element
          seems especially problematic.  The bug isn’t 100% reproducible, so
          while some content exhibits the problem, if you play with the
          document enough it will often “fix” itself for a while, then later
          it will go back to being broken (which indicates that the problem may
          be some sort of race condition in the JVM).
        </p>
      </answer>
    </faq>

    <faq id="mac-os-x-batik-demo-crash">
      <question>
        I cannot run the Batik demo on Mac OS X (10.1.1). The Batik splash
        screen hangs.  What is happening?
      </question>
      <answer>
        <p>
          The Batik <a href="site:demo">demo</a> uses Java Web Start. Java Web
          Start (under the <code>Applications/Utilities</code> folder), lets
          you start a Java application from a web browser. You can see the
          debug traces by enabling the Java console for Java Web Start. If you
          do, you will see that there is a
          <code>java.lang.NoSuchMethodError</code> exception thrown.
        </p>
        <p>
          This is happening because the Java Web Start jar file
          (<code>javaws.jar</code> in <code>/Applications/Utilities/Java Web
            Start/Content/MacOS</code>) contains an older version of the DOM
          bindings.
        </p>
        <p>
          One work around is to manually patch the <code>javaws.jar</code>
          file to remove the DOM bindings so that they do not take precedence
          over the Batik ones.
        </p>
      </answer>
    </faq>
  </part>

  <part id="batik-dev">
    <title>How do I contribute to Batik Development?</title>

    <faq id="how-can-i-contribute">
      <question>How can I contribute to Apache Batik development?</question>
      <answer>
        <p>
          The Batik Project is an open volunteer project in the 
          spirit of the <a href="http://www.apache.org">Apache
            Software Foundation</a> (ASF).  This means that there are
          many ways to contribute to the project, either with direct
          participation (coding, documenting, answering questions,
          proposing ideas, reporting bugs, suggesting bug-fixes, etc.)
          or by resource donation (publicity, hardware, software,
          conference presentations, speeches, etc.). Applications that
          use the Batik modules, such as tools or extensions, are of special 
          interest to the project.
        </p>
        <p>
          The process for contributing to Batik is the same as for other
          Java projects at Apache. A formal description of that process
          can be found on the <a href="http://jakarta.apache.org/guidelines/index.html">Jakarta</a>
          web site.  You can also view a list of
          <a href="site:contributors">who has contributed to Batik</a>.
        </p>
        <p>
          For direct participation, we suggest that you subscribe to the
          <a href="site:mailing-lists">Batik mailing lists</a> and to
          checkout the
          <a href="http://svn.apache.org/viewcvs.cgi/xmlgraphics/batik/">latest
            code</a>.
        </p>
      </answer>
    </faq>

    <faq id="submit-patches">
      <question>How do I submit patches or bug fixes?</question>
      <answer>
        <p>
          You can submit bug fixes and patches to the
          <a href="mailto:batik-dev@xmlgraphics.apache.org">Batik developers</a>
          mailing list and you can enter bugs in
          <a href="site:bugs">Bugzilla</a>.
        </p>
      </answer>
    </faq>
  </part>
</faqs>