<?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 stephane@hillion.org                                               -->
<!-- version $Id$ -->
<!-- ========================================================================= -->

<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd">
<document>
  <header>
    <title>SVG Pretty Printer</title>
  </header>

  <body>
    <p>
      This page describes the features of the SVG pretty printer utility that
      comes with the Batik distribution.  The SVG pretty printer is a utility
      that can format SVG files.  The tool formats an SVG document according to
      the arguments passed on the command line.
    </p>

    <section id="downloading">
      <title>Downloading the pretty printer</title>

      <p>
        Refer to the <a href="site:install">install page</a> and the
        <a href="site:download">download page</a> to find out what to
        download and how to download it. Remember that you can get either the
        source or binary distribution.
      </p>
    </section>

    <section id="using">
      <title>Pretty printing an SVG file</title>

      <p>
        The method for starting the pretty-printer depends on the distribution
        of Batik that you chose to download. The following describes how to
        run the pretty printer for each distribution.
      </p>

      <section id="using-binary">
        <title>Using the binary distribution</title>

        <p>
          If you downloaded the binary distribution of Batik, you should have
          a file called <code>batik-1.6.zip</code> (or similar), and, after
          expanding that file, a jar file called <code>batik-svgpp.jar</code>. 
          To start the pretty printer, open a console, change to the directory
          where you expanded the distribution (and where
          <code>batik-svgpp.jar</code> is located) and simply type the following
          at the command prompt:
        </p>
        <source>java -jar batik-svgpp.jar <em>[OPTIONS] FILES</em></source>
        <p>For example, if you type:</p>
        <p><code>java -jar batik-svgpp.jar samples/batikFX.svg</code></p>
        <p>you will see the indented document written to standard output.</p>

        <p>For the options:</p>
        <dl class="options">
          <dt><strong>-newline cr</strong><em>|</em><strong>cr-lf</strong><em>|</em><strong>lf</strong></dt>
          <dd>
            <p>specifies the newline character(s) generated in the printed
              document, the default being <code>lf</code> (Unix-style
              newlines),</p>
          </dd>
          <dt><strong>-tab-width</strong> <em>number</em></dt>
          <dd>
            <p>specifies the tabulation width, the default being 4,</p>
          </dd>
          <dt><strong>-doc-width</strong> <em>number</em></dt>
          <dd>
            <p>specifies the maximum number of columns for the whole document,
              the default being 80,</p>
          </dd>
          <dt><strong>-no-format</strong></dt>
          <dd>
            <p>specifies that the current indentation should be preserved,
              useful for performing doctype or newline substitutions,</p>
          </dd>
          <dt><strong>-xml-decl</strong> <em>string</em></dt>
          <dd>
            <p>specifies the XML declaration,</p>
          </dd>
          <dt><strong>-doctype change</strong><em>|</em><strong>remove</strong></dt>
          <dd>
            <p>specifies whether the doctype should be changed or removed,</p>
          </dd>
          <dt><strong>-publid-id</strong> <em>string</em></dt>
          <dd>
            <p>specifies the public ID to in the doctype declaration, when
              <code>-doctype change</code> is specified, and</p>
          </dd>
          <dt><strong>-system-id</strong> <em>string</em></dt>
          <dd>
            <p>specifies the system ID to in the doctype declaration, when
              <code>-doctype change</code> is specified.</p>
          </dd>
        </dl>
        <p>For example:</p>
        <source>java -jar batik-svgpp.jar -tab-width 2 -newline cr-lf src.svg dest.svg</source>
        <p>
          will format <code>src.svg</code> and write it to
          <code>dest.svg</code> using a tabulation width of 2 and Windows-style
          newlines, and:
        </p>
        <source>java -jar batik-svgpp.jar -no-format -doctype change -public-id "-//W3C//DTD SVG 1.1//EN" <strong class="cont">\</strong>
     -system-id "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd" src.svg dest.svg</source>
        <p>
          will format <code>src.svg</code> and write it to
          <code>dest.svg</code> unchanged, except for the doctype public and
          system IDs, which will be replaced by those specified.
        </p>
      </section>

      <section id="using-source">
        <title>Using the source distribution</title>

        <p>
          If you downloaded the source distribution of Batik, you will have a
          zip or tar file that expanded into a directory called
          <code>xml-batik</code> or <code>batik-<em>version</em></code>. In that
          directory, you can find build scripts for the platform you are running
          on. For example, there is a <code>build.bat</code> script for users of
          the Windows platform and there is a <code>build.sh</code> script for
          UNIX users.
        </p>
        <p>
          To start the pretty printer you should:
        </p>
        <ul>
          <li>
            <p>Make sure that your <code>JAVA_HOME</code> environment
              variable is set to your JDK installation directory.</p>
          </li>
          <li>
            <p>Open a command line window and go to the <code>xml-batik</code>
              or <code>batik-<em>version</em></code> directory where the Batik
              distribution was expanded.</p>
          </li>
          <li>
            <p>For Windows, type the following at the command prompt:</p>
            <source>build svgpp</source>
            <p>and for Unix:</p>
            <source>./build.sh svgpp</source>
            <p>This will print out a help message for the pretty printer.</p>
          </li>
        </ul>
        <p>You can pass options to the rasterizer as follows, for Windows:</p>
        <source>build svgpp <em>[OPTIONS] FILES</em></source>
        <p>and for Unix:</p>
        <source>./build.sh svgpp <em>[OPTIONS] FILES</em></source>
        <p>Refer to <a href="#using-binary">“Using the binary distribution”</a>
          for an explanation of these options.</p>
      </section>

    </section>
  </body>
</document>
