xdocs/faq.xml

<?xml version="1.0"?>
<!-- ========================================================================= -->
<!-- Copyright (C) The Apache Software Foundation. All rights reserved.        -->
<!--                                                                           -->
<!-- This software is published under the terms of the Apache Software License -->
<!-- version 1.1, a copy of which has been included with this distribution in  -->
<!-- the LICENSE file.                                                         -->
<!-- ========================================================================= -->

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

<!DOCTYPE faqs SYSTEM "./dtd/faq-v10.dtd">

<faqs title="Frequently Asked Questions">

<faq>
    <question>What is Batik?</question>
    <answer>
        <p>        <img src="images/batikUses.jpg" alt="Batik use cases" />
        Batik is a Java(tm) technology
        based toolkit for applications that want to use images in the
        <link href="http://www.w3.org/TR/SVG/">Scalable Vector
        Graphics (SVG)</link> format for various purposes, such as
        viewing, generation or manipulation.        
        </p>
        <p>
        The project's ambition is to give developers a set of core modules which can be used together 
        or individually to support specific SVG solutions. Examples of modules are an
        <link href="glossary.html#SVGParser">SVG parser</link>, an 
        <link href="glossary.html#SVGGenerator">SVG generator</link>
        and an <link href="glossary.html#SVGDOM">SVG DOM </link>
        implementations. Another ambition of the Batik project is to make 
        it highly extensible (for example, Batik allows the developer to handle custom SVG tags).
        Even though the goal of the project is to provide a set 
        of core modules, one of the deliveries is a full fledged SVG Browser implementation which 
        validates the various modules and their inter-operability. 
        </p>
        <p>
        In a nutshell, Batik provides building blocks that developers can assemble in 
        various ways in their Java technology applications to generate, 
        parse, view or convert SVG contents. For example, Batik contains
        a Swing component that can add SVG viewing capability to all Java
        technology applications. Batik can also be used to generate SVG on
        a client or on a server, and Batik can convert SVG content into
        other formats such as JPEG or PNG. Batik's goal is to make it easy
        for application developers to handle SVG content for various 
        purposes, client-side or server-side, as illustrated in the 
        diagram.
        </p>
    </answer>

</faq>

<faq>
    <question>What is SVG?</question>
    <answer>
        <p>
        SVG (Scalable Vector Graphics) is an open-standard language for describing 
        two-dimensional (2D) graphics in XML. It is a Recommendation from the 
        <link href="http://www.w3.org">W3C</link>. 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 'onmouseover' and 'onclick' 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 in reaction to events. </p>
        <p>SVG graphical elements can be animated through scripting. Alternatively,
        animation sequences can be expressed directly in XML because SVG leverages the
        <link href="http://www.w3.org/AudioVideo/">SMIL</link> specification for multimedia,
        another <link href="http://www.w3.org">W3C</link> specification. 
        </p>
    </answer>
</faq>

<faq>
    <question>What can I do with Batik?</question>
    <answer>
        <p>
        Batik contains several core modules which can be used independently or jointly to 
        <strong>generate SVG content</strong> (see the <link href="svggen.html">SVG Generator</link>, an 
        <link href="domapi.html">SVG DOM</link> implementation documentation)
        <strong>view SVG content</strong> (see the <link href="jsvgcanvas.html">JSVGCanvas</link>)
        or <strong>convert to and from the SVG format</strong> (see the 
        <link href="rasterizerTutorial.html">SVG Transcoders</link> tutorial).
        </p>
        
        <p>
        In addition, Batik contains low level modules such as
        an object oriented Graphic Vector Toolkit (<link href="glossary.html#GVT">GVT</link>),
        a set of low level parsers specific to the SVG syntax and
        a set of extensions to the Java 2D API (such as sophisticated fill types and 
        filter effects).
        </p>

        <p>
        Finally, Batik comes with packaged applications to help developers get
        familiar with the code and be quickly able to use the various modules: an 
        <link href="svgviewer.html">SVG browser</link> (in the 
        <code>org.apache.batik.apps.svgbrowser</code> package) an 
        <link href="svgrasterizer.html">SVG rasterizer</link> (in the 
        <code>org.apache.batik.apps.rasterizer</code> package), a
        <link href="ttf2svg.html">Font converter</link> (in the
        <code>org.apache.batik.apps.ttf2svg package</code>) and an 
        <link href="svgpp.html">SVG pretty printer</link> (in the 
        <code>org.apache.batik.apps.svgpp package</code>).</p>
        <p>
        The <strong>SVG browser</strong> 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 any Java application to provide SVG viewing capability.
        </p>
        <p>
        The <strong>SVG rasterizer</strong> lets the user convert SVG files to raster formats such
        as JPEG and PNG. 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 an 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 <strong>SVG Font Converter</strong> lets the user easily create
        an SVG Font for a set of characters from a True Type 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 <strong>SVG Pretty Printer</strong> is a convenience tool to 
        pretty print an SVG document, which means that you can reformat any
        existing SVG document to produce a properly formatted and highly legible 
        version.</p>

        <!-- <p>The SVG Generator 
        (in the <code>org.apache.batik.util.awt.svg</code> package) that allows
        all Java applications to export their graphics to the SVG format. 
        
        The SVG generator lets all Java application export their graphics
        as SVG, using the same code used for drawing to the screen or for
        printing. For example, an application that displays a pie chart in
        a window, can use the SVG generator to easily export the sequence
        of Java2D drawing calls for the pie chart to a SVG format.
        </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>
        <p>
        The SVG viewer and the rasterizer are only examples of the type of 
        applications Batik allows. Its architecture allows the different modules to
        be used in different ways and other applications are possible, such as 
        transcoders (to other vector formats, such as PDF, for example). Furthermore,
        the Graphic Vector Toolkit could be used to render other graphic formats
        such as XHTML.
        </p>
    </answer>
</faq>

<faq>
    <question>How can I see a demo?</question>
    <answer>
        <p>
        You can see an online demonstration of the Batik SVG browser
        on the <link href="batikDemo.html">demo page</link>. Alternatively,
        you can <link href="dist">download</link>
        Batik or see 
        <link href="svgviewer.html">screenshots</link> 
        of the Batik SVG viewer, images created from the 
        <link href="svgrasterizer.html">rasterizer</link>
        and an <link href="svggen.html">example</link>
        of how to use the SVG Graphics2D generator.
        </p>
    </answer>

</faq>

<faq>
    <question>Why do we have such a project at Apache?</question>
    <answer>
        <p>
        Apache's mission is to allow the web to be an open environment and
        to remain an open environment. Batik is an open source implementation of
        a key format for today and tomorrow's web and fits well in Apache's mission.
        </p>
    </answer>

</faq>

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

</faq>

<faq>
    <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><link href="http://www.csiro.au/">CSIRO</link></li>
            <li><link href="http://www.ilog.com/">ILOG</link></li>
            <li><link href="http://www.inria.fr/koala/">Koala Team</link></li>
            <li><link href="http://www.kodak.com/">Eastman Kodak Company</link></li>
            <li><link href="http://www.sun.com">Sun Microsystems, Inc.</link></li>
        </ul>
        <p>
        In addition, the Batik project is supported by <link href="http://www.ibm.com">IBM</link>.
        </p>
        <p>
        We encourage anyone to participate. As with all ASF project, 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>
    <question>How can I contribute?</question>
    <answer>
        <p>
        The Batik Project is an open volunteer project in the 
        spirit of the <link href="http://www.apache.org">Apache
        Software Foundation</link> (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 <link
        href="http://jakarta.apache.org/guidelines/index.html">Jakarta</link>
        web site.
        </p>
        <p>
        For direct participation, we suggest you to subscribe to the
        <link href="http://xml.apache.org/mail.html">Batik mailing
        list</link> (follow the link for information on how to
        subscribe and to access the mail list archives), and to
        checkout the <link
        href="http://cvs.apache.org/viewcvs.cgi/xml-batik/">latest
        code</link>.
        </p>
    </answer>

</faq>

<faq>
    <question>Where is Batik going? What is next?</question>
    <answer>
        <p>The SVG implementation is not complete, and there is more work to do to 
        achieve a fully functional viewer.</p>
        <p>Batik 1.1 supports all the static SVG features, linking and a limited
        support for scripting. Design work has 
        started on dynamic features (scripting and SMIL animation) support.
        </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>
    <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 
        <link href="http://www.w3.org/Graphics/SVG/SVG-Implementations#edit">implementation</link>
        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 
        data base 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><link href="http://xml.apache.org/xalan-j/index.html">Xalan for XSLT</link></li>
            <li><link href="http://xml.apache.org/xerces-j/index.html">Xerces</link> and
                <link href="http://java.sun.com/xml/download.html">Crimson</link> for the DOM API</li>
            <li><link href="svggen.html">SVG Generator</link></li>
        </ul>
    </answer>
</faq>

<faq>
    <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 <link href="http://www.w3.org/Graphics/SVG/SVG-Implementations">
        W3C's SVG implementation page</link>
        </p>
    </answer>

</faq>

<faq>

    <question>Where can I find the SVG specification?</question>
    <answer>
        <p>
        The SVG specification is available from the 
        <link href="http://www.w3.org/TR/SVG/">W3C Web site</link> 
        </p>
    </answer>

</faq>

<faq>
    <question>How much of SVG does Batik implement?</question>
    <answer>
        <p>
        The following <link href="status.html">status page</link>
        shows how much of the SVG specification Batik implements by showing which 
        of the tests in the SVG Basic Effectivity test suite Batik successfully passes.
        </p>
    </answer>

</faq>

<faq>

    <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 XLink for linking and SMIL
        for the animation.
        </p>
        <p>
        Beyond the use and mix with other XML syntaxes, being an XML grammar
        lets SVG benefit from the pletora of XML tools that make it so easy
        to manipulate, generate, search and edit SVG files.
        </p>
    </answer>

</faq>


<faq>
    <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>
        The following <link href="http://www.culturalbridge.com/idgallbk1.htm">
        page</link> shows examples of what Batik textures look like.</p>
    </answer>

</faq>

<faq>
    <question>What are the System Requirements to run Batik?</question>
    <answer>
        <p>
        Batik is written in the Java language and requires a version 1.3
        implementation at this time. 
        </p>
    </answer>

</faq>

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

</faq>

<faq>
    <question>How do I submit patches or bug fixes?</question>
    <answer>
        <p>
        You can submit bug fixes and patches to the 
        <link href="mailto:batik-dev@xml.apache.org">Batik developers</link>
        mailing list and you can enter bugs in <link href="http://nagoya.apache.org/bugzilla/">Bugzilla</link>.
        </p>
    </answer>

</faq>

<faq>
    <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 <link href="http://www.mozilla.org/rhino">Mozilla Rhino</link> JavaScript engine included in the distribution.
	        </li>
	        <li>Python for which you need to download the <link href="http://www.jpython.org">JPython</link> engine.
	        </li>
	        <li>Tcl for which you need to download the <link href="http://dev.scriptics.com/software/java/">Jacl</link> engine.
	        </li>
	    </ul>
	    <p>
	    To get more information on how to install optional scripting languages
	    you can have a look at the <link href="install.html">installation instructions</link>.
	    </p>
    </answer>
</faq>
<faq>
    <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
            CLASSPATH environment variable and be sure to remove all the libraries
            which use the W3C's DOM bindings from jre/lib/ext before running
            any of the Batik's applications.</p></answer>
</faq>

<faq>
    <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 tags
    (regularPolygon, and star for example).  We chose not to include
    these by default in the binary distribution for the Batik
    applications.
    </p>
    <p> 
    You can make the Batik extension tags available by putting the
    'lib/batik-extensions.jar' file on the java class path.
    </p></answer>
</faq>

<faq>
    <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 add lib/batik-extensions.jar to 
    your class path.
    </p></answer>
</faq>

<faq>
    <question>
    I am trying to use Batik and FOP together but Batik does not work and
    fails on the org.w3c.xxx packages. What is happening?
    </question>

    <answer>
        <p>Both FOP and Batik use the <code>org.w3c.xxx packages</code>. 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 w3c.jar file FOP 
        uses. However, if the w3c.jar file which 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 get a 
        failure.</p>
        <p>The solution is to either repackage the w3c.jar file with the 
        classes in the Batik distribution (you will need the Batik source
        distrib to do that), or you will need to make sure the Batik jars are
        loaded before the w3c.jar, for example by putting them before the
        w3c.jar file in your classpath. If you are copying your jar files to
        ..jre/lib/ext, you can simply remove the FOP w3c.jar file from that
        directory.</p>
    </answer>
</faq>
<faq>
    <question>
    How do I checkout the latest CVS version of Batik?
    </question> 
    <answer>
      <p>You just have to follow the instructions posted on the
      <link href="http://xml.apache.org/cvs.html">XML Apache CVS page</link>.
      </p>
    </answer>
</faq>
<faq>
    <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 appear to be problems in the
      Apple implementation of the Java 2D API's. The true source of 
      these problems and/or work arounds have yet to be identified (although 
      the problems appear to be closely tied to a 'gstack underflow' error 
      messages from the Apple JVM). We are interested in finding the source 
      of these problems and reasonable work arounds, 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 (I've never seen a pure raster SVG 
      document 'mess up').  The use of the 'filterRes' attribute on the 
      'filter' element seems especially problematic.  The bug isn't 100% 
      reproducible, so while some content has the problem a lot if you play 
      with the document enough it will often 'fix' it's self for a while, 
      then after a while it will go back to being broken (this makes me
      think the problem may be some sort of race condition in the JVM).</p>
    </answer>
</faq>
</faqs>