fop/src/documentation/content/xdocs/faq.xml

<?xml version="1.0" encoding="ISO-8859-1"?>
<!--
  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.
-->
<!-- $Id$ -->
<!DOCTYPE faqs PUBLIC "-//APACHE//DTD FAQ V1.1//EN" "http://forrest.apache.org/dtd/faq-v12.dtd">

<faqs title="FOP FAQ">
  <part id="part-general">
    <title>General questions</title>
    <faq id="fop-general">
      <question>What is FOP?</question>
      <answer>
      <p>
        FOP is a print formatter for <link href="#XSLFO">XSL formatting
        objects</link>.
      </p>
      <p>
        It can be used to render an XML file containing XSL formatting objects
        into a page layout. The main target is PDF but other rendering targets
        are supported, such as AWT, PCL, text and direct printing.
      </p>
      </answer>
    </faq>
    <faq id="fop-functions">
      <question>What can I do with FOP?</question>
      <answer>
        <p>
          FOP provides both an application and a library that converts an XSL FO
          document into paginated output.
        </p>
        <p>
          The FOP command line application can be directly used to transform XML
          into PDF, PostScript, PCL and other formats, there is also an AWT
          based viewer integrated.
        </p>
        <p>
          The library can be used in servlets and other Java applications.
        </p>
      </answer>
    </faq>
    <faq id="fop-acronym">
      <question>What does "FOP" stand for?</question>
      <answer>
        <p>
          FOP is an acronym for <strong>F</strong>ormatting
          <strong>O</strong>bject <strong>P</strong>rocessor
        </p>
      </answer>
    </faq>
    <faq id="fop-other-apache">
      <question>How does FOP interact with other Apache Projects?</question>
      <answer>
        <p>
          FOP is distributed with <link
          href="http://xml.apache.org/cocoon">Cocoon</link> as a PDF serializer
          for XSL (FO) documents.
        </p>
        <p>
          <link href="http://xml.apache.org/batik">Batik</link> can be used with
          FOP to <link
          href="http://xml.apache.org/batik/svgrasterizer.html">transcode an SVG
          image</link> into a PDF document.
        </p>
      </answer>
    </faq>
    <faq id="xsl-def">
      <question>What is XSL?</question>
      <answer>
        <p>
          XSL is a W3C standard concerned with publishing XML documents. It
          consists of two parts: <link href="#XSLT">XSLT</link> and <link
          href="#XSLFO">XSLFO</link>. The acronym expands to
          e<strong>X</strong>tensible <strong>S</strong>tylesheet
          <strong>L</strong>anguage.
        </p>
      </answer>
    </faq>
    <faq id="xslfo">
      <question>What is XSL-FO?</question>
      <answer>
        <p>
          XSLFO (aka XSL-FO) is an XML vocabulary that is used to specify a pagination and
          other styling for page layout output. The acronym &#8220;FO&#8221;
          stands for
          <strong>F</strong>ormatting <strong>O</strong>bjects. XSLFO can be
          used in conjunction with <link href="#XSLT">XSLT</link> to convert
          from any XML format into a paginated layout ready for printing or
          displaying.
        </p>
        <p>
          XSLFO defines a set of elements in XML that describes the way pages
          are set up. The contents of the pages are filled from flows. There can
          be static flows that appear on every page (for headers and footers)
          and the main flow which fills the body of the page.
        </p>
        <p>
          Synonyms: XSL FO, XSL (FO), XSL:FO, XSL-FO, Formatting Objects
        </p>
      </answer>
    </faq>
    <faq id="XSLT">
      <question>What is XSLT?</question>
      <answer>
        <p>
          XSLT describes the transformation of arbitrary XML input into other
          XML (like XSLFO), HTML or plain text. The &#8220;T&#8221; comes from
          <strong>T</strong>ransformation. For historical reasons, a
          transformation is often also called a &#8220;style sheet&#8221;.
        </p>
        <p>
          Synonyms: XSL transformation, XSL:T, XSL style sheet.
        </p>
      </answer>
    </faq>
    <faq id="when">
      <question>When will feature X be implemented?</question>
      <answer>
        <p>The short answer is "Don't ask." For more details, see <link href="gethelp.html#limitations">Understand FOP's Limitations</link>.</p>
      </answer>
    </faq>
    <faq id="next-release">
      <question>When is the next released planned?</question>
      <answer>
        <p>
          When it's ready and the committers have enough time to go through 
          the time-consuming process of creating a release. We
          released version 0.93 on 9 January 2007, and intend to
          release version 1.0 later in 2007. If you
        	want to speed up the process, consider to
        	<link href="dev/index.html#involved">contribute</link> to FOP.</p>
      </answer>
    </faq>
    <faq id="redesign">
      <question>Why did you redesign FOP?</question>
      <answer>
        <p>The code redesign of FOP was necessary in order to be able to adress following issues:</p>
        <ul>
          <li>Keeps and Breaks</li>
          <li>XSL-FO Compliance in general</li>
          <li>Process Files of Arbitrary Size</li>
          <li>Minimize Memory Use</li>
          <li>Table Layout</li>
        </ul>
      </answer>
    </faq>
    <faq id="contribute">
      <question>How can I contribute?</question>
      <answer>
        <p>
          There are numerous ways that you can help. They are outlined in the <link href="dev/index.html">Developer's Introduction</link> page.
        </p>
      </answer>
    </faq>
  </part>
  <part id="part-running">
    <title>Problems running FOP</title>
    <faq id="no-page-master">
      <question>I get the error: [ERROR]: 'master-reference' for
      'fo:page-sequence'matches no 'simple-page-master' or
      'page-sequence-master'</question>
      <answer>
        <p>
          FOP was changed to be in accordance with the latest standard (see
          <link href="resources.html#w3-xsl">XSL standard</link>).The page
          master for a fo:page-sequence is now refereced by the
          master-reference attribute. Replace the master-name attributes of
          your fo:page-sequence elements by master-reference attributes. You
          have to do this also for fo:single-page-master-reference,
          fo:repeatable-page-master-reference and
          fo:conditional-page-master-reference elements in you page master
          definitions.
        </p>
        <p>
          Update your FO documents and style sheets.
        </p>
      </answer>
    </faq>
    <faq id="NoClassDefFound">
      <question>I get a NoClassDefFound exception.</question>
      <answer>
        <p>This is typically a problem with your classpath.</p>
        <p>If you are running FOP from the command line:</p>
        <ul>
          <li>
            Use the <code>fop.bat</code>, <code>fop</code> or <code>fop.sh</code> command file from the FOP
            distribution. If you have a FOP version older than 0.20.5,
            ensure the directory where FOP and these files have been
            installed is the current working directory.
          </li>
          <li>
            If this doesn't help, check whether still all the jar files
            mentioned in the classpath in the <code>fop.bat</code> file are in their
            respective places.
          </li>
        </ul>
        <p>
          If you run FOP embedded in your servlet, web application or
          other Java application, check the classpath of the
          application. Check the also the information pertaining to <link
          href="0.93/servlets.html#servlet-engine">servlet engines</link>
          for further hints.
        </p>
        <p>
          If you downloaded the source distribution, or a snapshop
          from the repository, remember you have to build the FOP jars
          first.
        </p>
      </answer>
    </faq>
    <faq id="NoSuchMethodException">
      <question>I get a NoSuchMethodException or a NoSuchFieldException
      exception.</question>
      <answer>
        <p>
          This is usually caused by an older version of one of the FOP jars or
          old XML tools in the classpath. Check in particular for parser.jar,
          jaxp.jar, xml4j.jar or lotusxsl.jar.
        </p>
        <p>
          Incompatible versions of Batik may also cause this problem. Use the
          version of Batik that comes with FOP. It is not always possible to
          use a more recent version of Batik.
        </p>
      </answer>
    </faq>
    <faq id="OutOfMemoryException">
      <question>I get an OutOfMemoryException.</question>
      <answer>
        <p>
          See <link href="0.93/running.html#memory">FOP Memory</link>.
        </p>
      </answer>
    </faq>
    <faq id="MalformedURLException">
      <question>I get a MalformedURLException.</question>
      <answer>
        <anchor id="MalformedURL"/>
        <p>
          What you probably think of as "file names" are usually URLs, in
          particular the <code>src</code> attribute of fo:external-graphic.
        </p>
        <p>
          Because usage of URLs is growing, you should make yourself familiar
          with it. The relevant specification is <link
          href="http://www.rfc-editor.org/rfc/rfc2396.txt">RFC 2396</link>.
        </p>
        <p>
          In a nutshell, the correct syntax for an absolute file URL is
          <code>file:///some/path/file.ext</code> on Unix and
          <code>file:///z:/some/path/file.ext</code> on Windows systems. Note
          the triple slash, and also that only forward slashes are used, even on
          windows.
        </p>
        <p>
          A relative file URL starts with anything but a slash, and doesn't have
          the <code>file:</code> prefix, for example <code>file.ext</code>,
          <code>path/file.ext</code> or <code>../file.ext</code>. The string
          <code>file:path/file.ext</code> is <em>not</em> a relative URL,
          in fact, it isn't a valid URL at all. A relative URL is subject to a
          resolving process, which transforms it into an absolute
          URL.
        </p>
        <!--p>
          See Understanding URIs and URLs and Understanding
          URL resolving.
        </p-->
      </answer>
    </faq>
    <faq id="NullPointerException">
      <question>I get an "[ERROR]: null", or a NullPointerException.</question>
      <answer>
        <p>
          This is often caused by an invalid FO document. Currently only very
          common errors are intercepted and produce a comprehensible error
          message. If you forgot container elements like <code>fo:page-sequence</code> or
          <code>fo:flow</code> and put blocks and inline elements directly as children of
          <code>fo:root</code> or <code>fo:page-sequence</code>, you'll only get a
          NullPointerException. Check whether your FO file has a proper
          structure. In some cases there are mandatory properties, like the
          master-reference in <code>fo:conditional-page-master-reference</code>, check also
          whether you got them right.
        </p>
        <p>
          You may find it helpful to use the <link href="#FO-validate">validation tools</link> to validate your
          FO document. This will catch most problems, but should not be
          relied upon to catch all.
        </p>
        <p>
          If you use XSLT, problems in your style sheet and in your
          source XML also can produce a NullPointerException. <link
          href="0.93/running.html#check-input">Run the transformation
          separately</link> to check for this, usually you'll get a
          detailed error message from the XSLT processor.
        </p>
        <p>
          If you turn on debugging with the "<code>-d</code>" option you may be able to
          see more detailed information.
        </p>
      </answer>
    </faq>
    <faq id="not-implemented">
      <question>FOP returns the message "[ERROR] <em>object|property - 'x'</em> is not implemented yet." When will it be implemented?</question>
      <answer>
        <p>See FOP's Standards <link href="compliance.html">Compliance</link> page.</p>
      </answer>
    </faq>
    <faq id="fop-hangs">
      <question>FOP hangs. FOP does not exit.</question>
      <answer>
        <p>
          The most likely reason is a known problem with the Java run time
          environment which is triggered by rendering SVGs. Suns JDK 1.4 does
          not have this problem. See also <link href="#svghangs">FOP does not
          exit if a SVG is included</link>.
        </p>
        <p>
          Another possibility is that FOP went into a non terminating
          loop. Usually this is indicated by lots of log messages of the form
          "[INFO]: [NNNN]" which indicate a new page has been started or <link
          href="#boxoverflow">box overflows</link>. After some time, FOP will
          crash with an OutOfMemoryException.
        </p>
        <p>
          If you called the FOP command line application from some other
          programm, for example from Java using Runtime.exec(), it may hang
          while trying to write log entries to the output pipe. You have to read
          the FOP output regularly to empty the pipe buffer. It is best to avoid
          exec'ing FOP, use the library interface instead.
        </p>
      </answer>
    </faq>
    <faq id="boxoverflow">
      <question>FOP runs forever, writing lots of "&gt;" to the log.</question>
      <answer>
        <p>
          There is something too large to fit into the intended place, usually a
          large image, a table whose rows are kept together or a block with a
          space-before or space-after larger than the page size. Catch the first
          page showing this phenomenon and check it. If it is not obvious which
          element causes the trouble, remove stuff until the problem goes
          away. Decrease the dimensions of the offending element or property, or
          increase the dimension of the enclosing element or container, or
          remove keep-with-* properties.
        </p>
      </answer>
    </faq>
    <faq id="cannot-find-external-graphics">
      <question>FOP cannot find a file for fo:external-graphics.</question>
      <answer>
        <p>The src attribute of the <code>fo:external-graphics</code> element requires a URI, not a file name. See <link href="fo.html#external-resources">External Resources</link> for more information about specifying URIs.</p>
      </answer>
    </faq>
    <faq id="fonts-not-found">
      <question>FOP does not find my fonts.</question>
      <answer>
        <p>
          Did you get: &#171;Failed to read font metrics file C:\foo\arial.xml
          : File "C:\foo\arial.xml" not found&#187;? The value for the
          metrics-file attribute in the user config file is actually an URL, not
          a file name. Use "file:///C:/foo/arial.xml" instead.
        </p>
        <p>
          If you used a relative URL, make sure your application has the working
          directory you expect. Currently FOP does not use the baseDir for
          resolving relative URLs pointing to font metric files.
        </p>
        <p>
          Try also setting the <link
          href="0.93/configuration.html#general-elements">font-base
          configuration</link>.
        </p>
      </answer>
    </faq>
  </part>
  <part id="part-output">
    <title>Problems with FOP output</title>
    <faq id="leader-expansion">
      <question>Leaders don't work anymore in 0.93. Instead of
      filling the line, only three dots or a short ruler is
      output.</question>
      <answer>
        <p>
          Leaders still work, in fact they work better than ever
          before. You'll just have to add <code>text-align="justify"</code> and/or
          <code>text-align-last="justify"</code> to the block with the leader. Be
          sure you haven't accidentally overridden the
          <code>leader-length.maximum="100%"</code> default value.
        </p>
        <p>
          Earlier versions of FOP used to expand a leader to fill the
          rest of the line unconditionally, anything following it,
          like page numbers in a TOC, was actually shifted beyong the
          right margin.
        </p>
        <p>
          The new implementation uses leader-length.optimum to
          determine where to break the line, and expands the leader
          only further if the line should be filled, as indicated by
          the text-aling and text-align-last properties.
        </p>
        <p>
          Actually due to the fuzzyness of the specification both the
          old and the new method are conformant (although adding text
          after the expanded leader in the old variant never was).
        </p>
        <p>
          If you want to have a longer ruler or space in a
          non-justified line, you have to increase the
          leader-length.optimum property.
        </p>
      </answer>
    </faq>
    <faq id="blank-page-between-page-sequences">
      <question>Why does FOP insert a blank page between my page sequences?</question>
      <answer>
        <p>
          This is because spec conformance has been improved.
        </p>
        <p>
          The <link
          href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice7.html#force-page-count">force-page-count
          property</link> controls how a FO processor pads page sequences in
          order to get certain page counts or last page numbers. The default is
          "<code>auto</code>". With this setting, if the next page sequence
          begins with an odd page number because you set the
          initial-page-number, and the current page sequence also ends with an
          odd page number, the processor inserts a blank page to keep odd and
          even page numbers alternating (similar for the case the current page
          sequence ends with an even page number and the next page sequence
          starts with an even page number.
        </p>
        <p>
          If you don't want to have this blank page, use
          <code>force-page-count="no-force"</code>.
        </p>
      </answer>
    </faq>
    <faq id="graphic-not-displayed">
      <question>Why is my graphic not rendered?</question>
      <answer>
        <p>Most commonly, the external file is not being found by FOP.
Check the following:</p>
        <ul>
          <li>Empty or wrong baseDir setting.</li>
          <li>Spelling errors in the file name (including using the wrong case).</li>
          <li>Security Problems (i.e. the image could not be accessed
          because FOP is not allowed to read the file). This is
          especially a problem if the external file is retrieved over
          HTTP. Possible issues include security settings on the
          server, server configuration, and missing cookies or other
          authorization information. Any easy way to check this is to
          cut&amp;paste the source URL from the fo:external-graphic
          into the Location field of a browser <strong>on the machine
          where the FOP process will be running</strong>.</li>
        </ul>
        <p>Other possibilities:</p>
        <ul>
          <li>The image format is not supported or not supported completely.
          See <link href="0.93/graphics.html">FOP Graphics Formats</link> for a
          list of supported formats and related issues.</li>
          <li>The graphic may be too large to fit into the intended space.</li>
          <li>There may be something (static content) that is obscuring the
          graphic. (This is very rare).
          </li>
        </ul>
      </answer>
    </faq>
    <faq id="png-fails">
      <question>My graphical images do not work properly.</question>
      <answer>
        <p>See <link href="0.93/graphics.html">FOP Graphics Formats</link> for a
        list of supported graphics formats and related issues.</p>
      </answer>
    </faq>
    <faq id="graphic-resolution">
      <question>Why is my graphic rendered at a different resolution than it was created?</question>
      <answer>
        <p>See <link href="0.93/graphics.html#resolution">Graphics Resolution</link>.</p>
      </answer>
    </faq>
    <faq id="keep-with">
      <question>Keep-with-next, keep-with-previous, keep-together
      don't work.</question>
      <answer>
        <p>
          These properties are not implemented on version 0.20.5 and earlier, except on table rows. In
          order to take advantage of them, you have to nest stuff to be
          kept together in a table.
        </p>
        <p>
          The concept is called &#8220;blind table&#8221;. The table is used for
          pure layout reasons and is not obvious in the output.
        </p>
        <p>
          An example of an image and the image caption to be kept together:
        </p>
        <source><![CDATA[<fo:table table-layout="fixed" width="100%">
  <fo:table-column column-width="proportional-column-width(1)"/>
  <fo:table-body>
    <fo:table-row keep-with-next="always">
      <fo:table-cell>
        <fo:block>
          <fo:external-graphic src="foo.jpg"/>
        </fo:block>
      </fo:table-cell>
    </fo:table-row>
    <fo:table-row>
      <fo:table-cell>
        <fo:block>Image Caption</fo:block>
      </fo:table-cell>
    </fo:table-row>
  </fo:table-body>
</fo:table>]]></source>
        <p>
          Consider upgrading to the latest version which supports keeps.
        </p>
      </answer>
    </faq>
    <faq id="table-missing">
      <question>My tables are missing, or missing their content.</question>
      <answer>
        <p>
          Check for <code>fo:table-body</code> around the rows. FOP up to 0.20.4 doesn't
          raise an error if it is omitted, it just drops the content. More
          recent releases will catch this problem.
        </p>
        <p>
          Also, the <code>fo:table-with-caption</code> element is not implemented, tables
          within such an element are dropped too. FOP generates an error
          message for this problem. Older DocBook style sheets generate
          <code>fo:table-with-caption</code> elements, so watch out.
        </p>
      </answer>
    </faq>
    <faq id="cells-overflow">
      <question>Text overflowing table cells and the like is not clipped. Long
        text flows into adjacent cells/block, obscuring stuff there.</question>
      <answer>
        <p>
          Clipping as specified by the <code>overflow="hidden"</code> is not yet
          implemented.  If you have long words overflowing table cells, try to
          get them hyphenated. Artificial names like product identifications or
          long numbers usually aren't hyphenated. You can try special processing
          at XSLT level, like
        </p>
        <ul>
          <li>
            clip long text,
          </li>
          <li>
            explicit wrapping+clipping,
          </li>
          <li>
            insert zero width spaces (U+200B or &amp;#x200B;) to allow FOP to
            wrap.
          </li>
        </ul>
        <p>
          Check the <link href="http://dpawson.co.uk/xsl">XSL FAQ</link> and the
          <link href="http://www.mulberrytech.com/xsl/xsl-list/">XSL list
          archive</link> for how to perform these tasks.
        </p>
      </answer>
    </faq>
    <faq id="page-number-align">
      <question>Page numbers are not properly right aligned.</question>
      <answer>
        <p>
          This happens for <code>fo:page-number-citation</code> elements if the
          citation occurs before FOP formatted the requested page,
          usually in TOC or index pages. It is caused by the problem
          that FOP has to guess how much space the yet unknown page
          number will occupy, and usually the guesses are somewhat
          off.
        </p>
        <p>
          The most recent FOP releases should have this problem
          fixed. Check whether you can upgrade.
        </p>
      </answer>
    </faq>
    <faq id="hyphenation-fails">
      <question>Hyphenation does not work.</question>
      <answer>
        <p>Make sure you have set the language and optionally the country attributes for an appropriate XSL-FO element (fo:page-sequence, fo:block or fo:character):</p>
        <source><![CDATA[<fo:page-sequence language="fi">]]></source>
        <p>See <link href="0.93/hyphenation.html#support">Hyphenation Support</link> for details and instructions on using hyphenation with FOP.</p>
        <p>Explicitly enable hyphenation for an appropriate XSL-FO element (fo:block, fo:character):</p>
        <source><![CDATA[<fo:block hyphenate="true">]]></source>
      </answer>
    </faq>
    <faq id="indent-inheritance">
      <question>When I use margins, my content in a nested table or block-containers gets indented twice. Is this a bug?</question>
      <answer>
        <p>
          (Applies to version 0.90 and later)
          No, although you might easily think so. The problem has to do 
          with property inheritance of the start-indent and end-indent 
          properties to which the margin properties are mapped. Apache 
          FOP strictly adheres to the XSL-FO specification here which many 
          other commercial FO implementations don't do to better meet end-user 
          expectations. You can make FOP behave like these if you set 
          <code>setBreakIndentInheritanceOnReferenceAreaBoundary(true)</code> 
          on the FOUserAgent. The better way is to reset <code>start-indent</code>
          and <code>end-indent</code> to "0pt" on table-body or block-container. 
          For further details, please consult the 
          <link href="http://wiki.apache.org/xmlgraphics-fop/IndentInheritance">Wiki page on Indent Inheritance</link>.
        </p>
      </answer>
    </faq>
  </part>
  <part id="part-embedding">
    <title>Embedding FOP. Using FOP in a servlet.</title>
    <faq id="servlet">
      <question>How do I use FOP in a servlet?</question>
      <answer>
        <p>
          See <link href="0.93/servlets.html">Using FOP in a Servlet</link>.
        </p>
      </answer>
    </faq>
    <faq id="servlet-with-xslt">
      <question>How do I use FOP in a servlet with an XSLT
      transformation?</question>
      <answer>
        <p>
          See <link href="0.93/servlets.html#xslt">Using FOP in a Servlet with XSLT Transformation</link>.
        </p>
      </answer>
    </faq>
    <faq id="servlet-xslt-params">
      <question>How do I pass parameters to the XSLT transformation?</question>
      <answer>
        <p>
          See <link href="0.93/servlets.html#xslt">Using FOP in a Servlet with XSLT Transformation</link>.
        </p>
      </answer>
    </faq>
    <faq id="servlet-nonstd-fonts">
      <question>How do I use my own fonts when running FOP from a servlet?</question>
      <answer>
        <p>
          Declare the fonts in the <code>userconfig.xml</code> file as usual.
          See <link href="#usercfg">loading the user configuration file</link>
          for further details.
        </p>
      </answer>
    </faq>
    <faq id="servlet-baseDir">
      <question>How do I set the baseDir property in a servlet environment?</question>
      <answer>
        <p>
          See <link href="0.93/embedding.html#config-internal">Setting the Configuration Programmatically</link>.
        </p>
      </answer>
    </faq>
    <faq id="usercfg">
      <question>How do I use a user configuration file from a servlet?</question>
      <answer>
        <p>
          See <link href="0.93/embedding.html#config-external">Using a Configuration File in an Embedded App</link>.
        </p>
      </answer>
    </faq>
    <faq id="servlet-NoClassDefFound">
      <question>I keep getting NoClassDefFound and other exceptions. How do I
        get FOP working for various servlet engines?</question>
      <answer>
        <p>
          See <link href="0.93/servlets.html#servlet-engine">Servlet Engines</link>.
        </p>
      </answer>
    </faq>
    <faq id="multithreaded">
      <question>Can FOP be used in multithreaded environments?</question>
      <answer>
        <p>
          See <link href="0.93/embedding.html#multithreading">Multithreading FOP</link>.
        </p>
      </answer>
    </faq>
  </part>
  <part id="part-svg">
    <title>SVG specific questions</title>
    <faq id="svg-text">
      <question>The rendering of SVG text in my PDF is of poor quality.
Can I control this?</question>
      <answer>
        <p>See <link href="0.93/graphics.html#svg-pdf-text">Placing SVG Text into PDF</link>.</p>
      </answer>
    </faq>
    <faq id="svg-headless">
      <question>How do I use FOP with SVG on headless servers?</question>
      <answer>
        <p>See <link href="0.93/graphics.html#batik">FOP: Graphics (Batik)</link>.</p>
      </answer>
    </faq>
    <faq id="svghangs">
      <question>FOP does not exit if a SVG is included.</question>
      <answer>
        <p>
          Applies to older FOP versions and JDK 1.3 and older. That's because
          there is an AWT thread hanging around. The solution is to put a
          System.exit(0) somewhere.
        </p>
      </answer>
    </faq>
    <faq id="svg-url">
      <question>I have problems with SVG referring to gradients etc. using
        "uri(#stuff)". I get a MalformedURLException.</question>
      <answer>
        <p>
          This is really a "resolving relative URI" problem with some
          twists. The problem is that the <code>#stuff</code> URL fragment
          identifier is resolved within the current SVG document. So the
          reference must be valid within the XML subset and it cannot
          reference other SVG documents in the same XML file. Some options
          to try:
        </p>
        <ul>
          <li>
            Put the SVG into a separate file and use it with
            fo:external-graphics.
          </li>
          <li>
            Use a separate SVG file which contains only the gradient (and
            perhaps other SVG stuff you want to reference) and point an absolute
            URL to it:
            <code>fill="url(file:///c:/refstuff/grad.svg#PurpleToWhite)"</code>.
          </li>
          <li>
            Same as above but use a relative URL:
            <code>fill="url(grad.svg#PurpleToWhite)"</code>. This may be easier
            to deploy.
          </li>
          <li>
            Make sure that the reference is valid in the current SVG document.
          </li>
        </ul>
        <p>
          In any case, the referenced stuff has to be pointed to by an URL. It
          doesn't necessarily have to be a file URL, HTTP should also
          work. Also, expect a performance hit in all cases, because another XML
          file has to be retrieved and parsed.
        </p>
        <p>
          Ultimately, both FOP and especially Batik should be fixed to make
          your code work as expected, but this will not only take some time
          but also some effort by a standard committee in order to make the
          semantics of this kind of references in embedded SVG clearer.
        </p>
        <p>See also <link href="#MalformedURL">MalformedURLException</link></p>
      </answer>
    </faq>
    <faq id="svg-scaling">
      <question>Why is my SVG rendered at a size different from that specified in my fo:external-graphic element?</question>
      <answer>
        <p>See <link href="0.93/graphics.html#svg-scaling">SVG Scaling</link>.</p>
      </answer>
    </faq>
    <faq id="svg-attribute-required">
      <question>FOP fails with something like "The attribute "width" of the element &lt;rect&gt; is required". What's wrong?</question>
      <answer>
        <p>
          This phenomenon occurs since FOP 0.92 beta. It surfaced due to a change in the handling of non-FO namespaces. It's not a
          bug in FOP, but rather in the dependent packages: Apache Batik, Apache Xalan-J and SAXON. The bug in Apache Batik will be 
          fixed in the next release. In the latest release of Apache Xalan-J, the bug is already fixed. It only occurs in the Xalan
          version bundled with Sun's JVM, because Sun uses a rather old version.
        </p>
        <p>
          Bug description: In a namespace-enabled Level 3 DOM, an attribute in the default namespace must be set with 
          <code>"null"</code> as the value for the namespace URI. SAX, on the other side, uses an empty string ("") to designate 
          the default namespace. Many packages appear to not properly handle this difference in which case they still use the empty 
          string as the namespace URI parameter for <code>org.w3c.dom.Element.setAttributeNS()</code>.
        </p>
        <p>
          Work-around: Use the latest version of Apache Xalan-J. Note that starting with JDK 1.4 it's not enough to replace Xalan-J 
          on the normal application classpath and you need to override the Xalan-J version bundled with the Sun JVM using the 
          <link href="http://java.sun.com/j2se/1.4.2/docs/guide/standards/">Endorsed Standards Override Mechanism</link>, i.e.
          you must place Xalan-J in the <code>"lib/endorsed"</code> directory of your JRE.
        </p>
      </answer>
    </faq>
  </part>
  <part id="part-pdf">
    <title>PDF specific (includes Acrobat peculiarities)</title>
    <faq id="pdf-embed-font">
      <question>How do I embed fonts in PDF?</question>
      <answer>
        <p>
          See the <link href="0.93/fonts.html">Fonts</link> page for information
          about embedding fonts.
        </p>
      </answer>
    </faq>
    <faq id="pdf-characters">
      <question>Some characters are not displayed, or displayed incorrectly, or
      displayed as &#8220;#&#8221;.</question>
      <answer>
        <p>
          This usually means the selected font doesn't have a glyph
          for the character.
        </p>
        <p>
          The standard text fonts supplied with Acrobat Reader have
          mostly glyphs for characters from the ISO Latin 1 character
          set. For a variety of reasons, even those are not completely
          guaranteed to work, for example you can't use the fi
          ligature from the standard serif font. Check the <link
          href="0.93/output.html#pdf-fonts">overview</link> for the default
          PDF fonts.
        </p>
        <p>
          If you use your own fonts, the font must have a glyph for
          the desired character. Furthermore the font must be
          available on the machine where the PDF is viewed or it must
          have been embedded in the PDF file. See <link
          href="0.93/fonts.html">embedding fonts</link>.
        </p>
        <p>
          For most symbols, it is better to select the symbol font
          explicitely, for example in order to get the symbol for the
          mathematical empty set, write:
        </p>
        <source><![CDATA[<fo:inline font-family="Symbol">&#x2205;</fo:inline>]]></source>
        <p>
          The "#" shows up if the selected font does not define a glyph for the
          required character, for example if you try:
        </p>
        <source><![CDATA[<fo:inline font-family="Helvetica">&#x2205;</fo:inline>]]></source>
      </answer>
    </faq>
    <faq id="pdf-postprocess">
      <question>What tools are available for post-processing my PDF document?</question>
      <answer>
        <p>See <link href="0.93/output.html#pdf-postprocess">PDF Post-processing</link>.</p>
      </answer>
    </faq>
    <faq id="pdf-security">
      <question>How do I add security features (encryption, disable printing)
      to my PDF document?</question>
      <answer>
        <p>
          See <link href="0.93/pdfencryption.html">PDF Encryption</link>.
          See also <link href="0.93/output.html#pdf-postprocess">PDF Post-processing</link>.
        </p>
      </answer>
    </faq>
    <faq id="pdf-doc-properties">
      <question>How do I add document properties (title, author, etc.) to my
      PDF document?</question>
      <answer>
        <p>See <link href="0.93/output.html#pdf-postprocess">PDF Post-processing</link>.</p>
      </answer>
    </faq>
    <faq id="pdf-watermark">
      <question>How do I add watermarks to my PDF document?</question>
      <answer>
        <p>See <link href="0.93/output.html#pdf-watermark">PDF Watermarks</link>.</p>
      </answer>
    </faq>
    <faq id="pdf-print-contortion">
      <question>The PDF is printed contorted!</question>
      <answer>
        <p>
          Check the paper size in Acrobat settings and the "fit to page" print
          setting. Contorted printing is often caused by a mismatched paper
          format, for example if the setting is "US Letter" but the PDF was
          made for A4. Sometimes also the printer driver interferes, check its
          settings too.
        </p>
      </answer>
    </faq>
    <faq id="pdf-bookmark-display">
      <question>How do I control the Acrobat bookmark display?</question>
      <answer>
        <p>
          FOP does not currently support this feature. Possible workarounds
          include those mentioned in the <link href="#PDF-postprocess">PDF
            Post-Processing FAQ</link>.
        </p>
      </answer>
    </faq>
  </part>
  <part id="part-iex">
    <title>IEx specific stuff</title>
    <faq id="iex-servlet-multiple">
      <question>The FOP servlet is called multiple times!</question>
      <answer>
        <p>
          This is a problem of Internet Explorer requesting the content several
          times. Please see the <link href="0.93/servlets.html#ie">notes on Internet Explorer</link>
          for more information.
        </p>
      </answer>
    </faq>
    <faq id="iex-pdf-print-from-browser">
      <question>How do I print PDF directly from the browser?</question>
      <answer>
        <p>
          It depends whether you mean "printing to a printer under control of
          the server" or "printing on the client's printer".
        </p>
        <p>
          For the first problem, look at the print servlet in the FOP
          examples. You'll have to gather any printer settings in a HTML form
          and send it to the server.
        </p>
        <p>
          For the second task, you can use some client side script to start
          Acrobat Reader in print mode, or use a Java applet based on the FOP
          print servlet. This depends heavily on the client installation and
          should not relied on except in tightly controlled environments.
        </p>
        <p>
          See also <link href="http://marc.theaimsgroup.com/?l=fop-dev&amp;m=101065988325115&amp;w=2">http://marc.theaimsgroup.com/?l=fop-dev&amp;m=101065988325115&amp;w=2</link>
        </p>
      </answer>
    </faq>
  </part>
  <part id="part-input">
    <title>General questions regarding XSLT, XSLFO, and basic XML</title>
    <faq id="fo-center">
      <question>(FO) How do I vertically center an image or a table (or
      whatever)?</question>
      <answer>
        <p>
          See <link href="fo.html#fo-center-vertical">XSL-FO Vertical Centering</link>.
        </p>
      </answer>
    </faq>
    <faq id="fo-center-table-horizon">
      <question>(FO) How do I center a table horizontally?</question>
      <answer>
        <p>
          See <link href="fo.html#fo-center-table-horizon">XSL-FO Horizontal Centering (Tables)</link>.
        </p>
      </answer>
    </faq>
    <faq id="fo-page-outer">
      <question>(FO) How to get page numbers printed on the "outer side" of the
        page (for books, for example)?</question>
      <answer>
        <p>
          See <link href="fo.html#fo-oddeven">Recto/Verso Static Content Differences</link>.
        </p>
      </answer>
    </faq>
    <faq id="oddeven">
      <question>(FO) How do I use different static content for odd and even
      pages?</question>
      <answer>
        <p>
          See <link href="fo.html#fo-oddeven">Recto/Verso Static Content Differences</link>.
        </p>
      </answer>
    </faq>
    <faq id="fo-first-page-header">
      <question>(FO) How do I get a special header on the first page?</question>
      <answer>
        <p>
          See <link href="fo.html#fo-first-page">Making the First Page Special</link>.
        </p>
      </answer>
    </faq>
    <faq id="fo-omit-headers">
      <question>(FO) How do I omit my headers on a blank page? How do I write
      "This page is left blank" on an intentionally blank page?</question>
      <answer>
        <p>
          See <link href="fo.html#fo-blank-pages">Blank Pages</link>.
        </p>
      </answer>
    </faq>
    <faq id="fo-special-symbols">
      <question>(FO) How do I print an Euro sign, a checkbox or other some other
      special symbols?</question>
      <answer>
        <p>
          See <link href="fo.html#xml-special-chars">Special Characters</link>.
        </p>
      </answer>
    </faq>
    <faq id="fo-preformat">
      <question>(FO) How do I keep linebreaks and hard spaces? How do I get
        preformatted text displayed as expected?</question>
      <answer>
        <p>
          See <link href="fo.html#fo-preformat">Preformatting Content</link>.
        </p>
      </answer>
    </faq>
    <faq id="fo-total-pages">
      <question>(FO) How do I print the total number of pages, for example "page 1
      of 12"</question>
      <answer>
        <p>
          See <link href="fo.html#fo-total-pages">Total Document Pages</link>.
        </p>
      </answer>
    </faq>
    <faq id="fo-region-overlap">
      <question>(FO) The header overlaps body content. The body extends into
      the footer.</question>
      <answer>
        <p>
          See <link href="fo.html#fo-region-align">Aligning Regions</link>.
        </p>
      </answer>
    </faq>
    <faq id="fo-lines">
      <question>(FO) How do I get lines in the document, as separators, side
      bars or folding marks?</question>
      <answer>
        <p>
          See <link href="fo.html#fo-lines">Drawing Lines</link>.
        </p>
      </answer>
    </faq>
    <faq id="fo-validate">
      <question>(FO) How do I validate my FO document?</question>
      <answer>
        <p>
          See <link href="fo.html#fo-validate">Validating XSL-FO</link>.
        </p>
      </answer>
    </faq>
    <faq id="xml-non-breaking-space">
      <question>(XML) How do I get a non-breaking space in FO? There are complaints about <code>&amp;nbsp;</code>.</question>
      <answer>
        <p>
          See <link href="fo.html#xml-special-chars">XML Special Characters</link>.
        </p>
      </answer>
    </faq>
    <faq id="xml-undefined-entities">
      <question>(XML) How do I enter special characters in XML? There are complaints about undefined entities, such as <code>&amp;uuml;</code>, which work in HTML. </question>
      <answer>
        <p>
          See <link href="fo.html#xml-special-chars">XML Special Characters</link>.
        </p>
      </answer>
    </faq>
    <faq id="xml-illegal-entities">
      <question>(XML) There are complaints about illegal characters and entities
      in the input.</question>
      <answer>
        <p>
          See <link href="fo.html#xml-entity-chars">Using HTML Character Names</link>.
        </p>
      </answer>
    </faq>
    <faq id="xml-illegal-chars">
      <question>(XML) There are complaints about illegal bytes or characters in
      the input. There are odd characters in the result.</question>
      <answer>
        <p>
          See <link href="fo.html#xml-encoding">XML Encoding Issues</link>.
        </p>
      </answer>
    </faq>
    <faq id="xslt-current-date">
      <question>(XSLT) How can I use the current date and time in my document?</question>
      <answer>
        <p>See <link href="fo.html#xslt-date">Current Date and Time</link>.</p>
      </answer>
    </faq>
    <faq id="xhtml-to-pdf">
      <question>Can I use FOP to convert XHTML or HTML files to PDF?</question>
      <answer>
        <p>
        	You will get better results if you transform your source
			XML directly into XSLFO. It is tempting to use the
			XML-&gt;XHTML-&gt;XSLFO approach, because this apparently means
			there's only one transformation to maintain, but XHTML
			and publishing grade PDF are dissimilar enough that an
			"generic" XHTML-&gt;XSLFO(PDF) usually wont cut it, because
			the XHTML already lacks information from the original XML.
			It may be worthwhile to go from the source XML to an
			intermediate custom XML which on one hand is close enough
			to representation to allow simple transformation to either
			XHTML or XSLFO for most of the structure, but on the other
			hand retains enough semantic from the original XML that
			elements which must be handled differently in the two
			representations can be handled differently. Setting this
			up requires experience and most likely extensive prototyping.
        </p>
      </answer>
    </faq>
    <faq id="xhtml-to-pdf2">
      <question>I know it may be a bad idea to use FOP to convert XHTML or HTML files to PDF, but I want to do it anyway. Are there any tools available to help me?</question>
      <answer>
        <p>
        	The <link href="resources.html">FOP Resources page</link> has links
        	to a tool called <link href="http://html2fo.sourceforge.net/">html2fo</link>
        	which can be used to make such a transformation. In addition, there
        	are tools on the Antenna House <link href="http://www.antennahouse.com/XSLsample/XSLsample.htm">XSL-FO Tutorial and Sample</link>
			page.
        </p>
      </answer>
    </faq>
  </part>
  <part id="dev-help">
    <title>Development-related Questions.</title>
    <faq id="doc-mgt">
      <question>Where can I learn how the FOP docs and web site are built?</question>
      <answer>
      	<p>
      		See FOP <link href="dev/doc.html">Doc Management</link>. ;-)
      	</p>
      </answer>
    </faq>
  </part>
  <part id="part-help">
    <title>General suggestions. How to solve problems.</title>
    <faq id="bugs">
      <question>I think I have found a bug in FOP. What should I do?</question>
      <answer>
        <p>
          See <link href="bugs.html">the Bugs page</link> for information about
          bugs already reported and how to report new ones.
        </p>
      </answer>
    </faq>
    <faq id="postquestions">
      <question>I have questions that are not addressed in this FAQ. Where
      should I post them?</question>
      <answer>
        <ul>
          <li>If your question is a development-related question, please see the <link href="dev/faq.html">Developer FAQs</link>.</li>
          <li>
            If you have a runtime exception or other runtime problem:
            <ul>
              <li>
                double-check the <link href="#part-running">Runtime FAQs</link>.
              </li>
              <li>
                ClassNotFoundException, NoSuchMethodException and
                NoSuchFieldException problems are almost always a problem with
                the local environment. Try to get local help first.
              </li>
              <li>
                Check <link href="bugs.html#issues_existing">Reported Issues</link>
                to see if this is a known problem.
              </li>
              <li>If none of the above apply, post a question to the fop-dev
                mailing list.
              </li>
            </ul>
          </li>
          <li>
            In the case where something works properly with another formatter,
            (AntennaHouse, PassiveTex, etc.) but doesn't work with FOP, please
            check the <link href="relnotes.html">Release Notes</link>, the
            <link href="compliance.html">FOP Standards Compliance</link> document,
            and the remaining FAQ in this document. If not found there, look at the
            list of <link href="bugs.html#issues_existing">Bugs Already Reported</link>.
            If not found there, please post a question on the fop-user mailing list
            or <link href="bugs.html#issues_new">Open a New Bug</link>.
          </li>
          <li>
            Question about how to use FOP, how to perform certain tasks with FOP
            or how to integrate FOP into another application should be posted to
            fop-user.
          </li>
          <li>
            XSLT specific stuff sould go to the <link
            href="http://www.mulberrytech.com/xsl/xsl-list/">XSL
            list</link>. This includes problems with the language and XSLT
            HOW-TOs.
          </li>
          <li>
            Problems specific to a certain XSLT processor, like Xalan, Saxon or
            MSXML, should be handled by processor specific lists. This includes
            problems with deployment, processor specific extensions, suspected
            bugs and processor specific APIs. Note that JDK 1.4 comes with an
            XML parser and an XSLT processor which are older versions of
            Xerces and Xalan, respectively, and both have a number of annoying
            bugs. See $$$FIXME on how to use more recent versions or other
            packages instead.
          </li>
          <li>
            Problems with servlet containers should be asked on the vendor
            specific lists for these software packages.
          </li>
          <li>
            More general questions regarding Java, including deployment, Java
            APIs, classpath issues and property definitions should be redirected
            to some Java specific list.
          </li>
        </ul>
      </answer>
    </faq>
  </part>
</faqs>