path: root/src/documentation/content/xdocs/faq.xml

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE faqs PUBLIC "-//APACHE//DTD FAQ V1.1//EN"
    "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/schema/dtd/faq-v11.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>
          It's 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 XSLFO?</question>
      <answer>
        <p>
          XSLFO 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="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>.
        </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>
          See also <link href="relnotes.html">release notes</link>.
        </p>
      </answer>
    </faq>
    <faq id="NoClassDefFound">
      <question>I get a NoClassDefFound exception.</question>
      <answer>
        <p>
          This is typically a problem with your <!--link
            href="classpath.html"-->classpath<!--/link-->.</p>
        <p>If you are running FOP from the command line:</p>
        <ul>
          <li>
            Use the fop.bat or fop.sh command file from the FOP distribution.
            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 fop.bat 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.
        </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>
          FOP can consume quite a bit of memory, even though this has been
          continually improved. The memory consumption is partially inherent to
          the formatting process and partially caused by implementation
          choices. For certain layouts, all FO processors currently on the
          market have memory problems.
        </p>
        <p>
          Some hints regarding your document structure:
        </p>
        <ul>
          <li>
            Increase memory settings of the JVM, see for example <link
              href="http://java.sun.com/j2se/1.3/docs/tooldocs/solaris/java.html">the
              -Xmx option</link>. Be aware that it is usually unwise to
            increase the memory allocated to the JVM beyond the amount of
            physical RAM, it will significantly slow down. YMMV.
          </li>
          <li>
            Avoid forward references, that is page number citations to pages to
            places on pages which follow the citation. Forward references cause
            all pages from the page with the reference on to be held in memory
            until the page with the referenced element is encountered. Common
            forward references are table of contents at the beginning of the
            document and the <link href="#pagenum">"page N of TOTAL"</link> in
            footers. Forward references may be required by the task, however,
            if you are getting a memory overflow you should at least check
            whether this is really as necessary as claimed. A TOC, for example,
            could often be placed at the end of the document without dimishing
            it's value too much, the paper can be reshuffled after printing,
            and you can use bookmarks in PDF.
          </li>
          <li>
            Avoid large images, especially if they are scaled down. Scale them
            outside of FOP and use the already scaled images for the FOP
            run. For many image formats it is mainly the size of the image file
            which matters, not width*height, so you can try other means like
            using a higher compression rate.
          </li>
          <li>
            Use multiple page sequences. FOP starts rendering after the end of
            a page sequence is encountered. While the actual rendering is done
            page by page, some additional memory allocated for other purposes
            could be freed after the page sequence has been rendered.
          </li>
          <li>
            Break down large tables. If you don't use table headers and
            footers, just start a new table every N rows. With headers and
            footers, consider integrating them as normal table rows, or, if
            they are used at page breaks, try to put the information into
            static content. You can use markers to change them.
          </li>
        </ul>
        <p>
          There are also some bugs which cause FOP to go into an nonterminating
          loop, which also often results in a memory overflow. A characteristic
          symptom are continuous <link href="#boxoverflow">box
          overflows</link>. Most of them are triggered by elements not fitting
          in the available space, like big images and improperly specified width
          of nested block elements. Look for such stuff and correct it.
        </p>
        <p>
          Reducing memory consumption in general and squishing bugs is an
          ongoing effort, partially addressed in the <link
          href="dev/index.html">redesign</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 src 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 fo:page-sequence or
          fo:flow and put blocks and inline elements directly as children of
          fo:root or fo:page-sequence, 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 fo:conditional-page-master-reference, 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 often produce a NullPointerException. Run the transformation
          separately 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 "-d" 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 the article "<link href="gethelp.html#compliance">Review FOP's Standards Compliance</link>".</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 ">" 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 fo:external-graphics element takes an URI,
          not a file name.
        </p>
        <p>
          Relative URLs are resolved against the baseDir property of FOP. For
          the command line FOP application, the baseDir is the directory of the
          input file, either the FO file or the XML source. If FOP is used
          embedded in a servlet, <link href="embedding.html">baseDir can be
            set explicitely</link>. If it's not set, it is usually the current
          working directory of the process which runs FOP.
        </p>
        <!--p>
          See Understanding URIs and URLs and Understanding
          URL resolving.
        </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&#178;? 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>
      </answer>
    </faq>
  </part>
  <part id="part_output">
    <title>Problems with FOP output</title>
    <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/xsl/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="png_fails">
      <question>My PNG images don't work.</question>
      <answer>
        <p>
          The Jimi image library, which is by default used for processing
          images in PNG and other formats, was removed from the distribution
          for licensing reasons. You have to <fork
            href="http://java.sun.com/products/jimi">download</fork>
          and install it by yourself.
        </p>
        <p>
          Extract the file "JimiProClasses.zip" from the archive you've downloaded, rename it to "jimi-1.0.jar" and move it to FOP's lib directory.
        </p>
        <p>
          An alternative to Jimi is to use Sun's JAI. It is much faster, but
          not available for all platforms.
        </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, 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 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>
      </answer>
    </faq>
    <faq id="table_missing">
      <question>My tables are missing, or missing their content.</question>
      <answer>
        <p>
          Check for fo:table-body 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 fo:table-with-caption element is not implemented, tables
          within such an element are dropped too. FOP generates an error
          message for this problem. The DocBook style sheets generate
          fo:table-with-caption 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 fo:page-number-citation elements if the citation
          occurs before FOP formatted the requested page, usually in TOC or
          index pages.
        </p>
        <p>
          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. You can try to use a non-proportional font like Courier
          to remedy this. However, this is likely to look ugly, and wont fix the
          problem completely.
        </p>
      </answer>
    </faq>
    <faq id="graphic_not_displayed">
      <question>A graphic is not displayed.</question>
      <answer>
        <p>
          The most common reason is that the file is not found because of an
          empty or wrong baseDir setting, spelling errors in the file name, in
          particular using the wrong case, or, if the image is retrieved over
          HTTP, the image was not delivered because of security settings in the
          server, missing cookies or other authorization information, or
          because of server misconfigurations.  One 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>.
        </p>
        <p>
          Several other possibilities:
        </p>
        <ul>
          <li>
            The graphic is too large to fit into the intended space.
          </li>
          <li>
            Some image format subclasses can't be handled, try to convert the
            graphic to a format subclass known to work. (Sorry, no list of
            formats known to work)
          </li>
          <li>
            Something else obscures the graphic, for example stuff from a
            static content (very rare, but has happened).
          </li>
        </ul>
        <!-- p>
          See also supported image formats.
        </p -->
      </answer>
    </faq>
    <faq id="hypenation_fails">
      <question>Hyphenation does not work.</question>
      <answer>
        <p>
          Set the language attribute somewhere. Check whether you use a language
          for which hyphenation is supported. Supported languages can be deduced
          from the files in the hyph directory of the FOP source distribution.
        </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="embedding.html#servlet">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="embedding.html#servlet-transform">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="embedding.html#servlet-transform">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="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="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="embedding.html#servlet-engine">Servlet Engines</link>.
        </p>
      </answer>
    </faq>
    <faq id="multithreaded">
      <question>Can FOP be used in multithreaded environments?</question>
      <answer>
        <p></p>
      </answer>
    </faq>
  </part>
  <part id="part_svg">
    <title>Batik/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="svg.html#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>
          Batik uses AWT classes for rendering SVG, which in turn needs an X
          server on Unixish systems. If you run a server without X, or if you
          can't connect to the X server due to security restrictions or
          policies, SVG rendering will fail.
        </p>
        <p>
          There are still several options:
        </p>
        <ul>
          <li>
            If you are using JDK 1.4, start it with the -Djava.awt.headless=true
            command line option.
          </li>
          <li>
            Install a X server which provides an im-memory framebuffer without
            actually using a screen device or any display hardware, like Xvfb.
          </li>
          <li>
            Use a toolkit which emulates AWT without the need of an underlying X
            server, like <link
            href="http://www.eteks.com/pja/en">PJA</link>. The PJA toolkit is
            free and comes with detailed installation instructions.
          </li>
        </ul>
      </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>
  </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="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>
          There are a few fonts supplied with Acrobat Reader. If you use other
          fonts, 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="fonts.html">embedding fonts</link>.
        </p>
        <p>
          Furthermore, if you select a certain font family, the font must
          contain glyphs for the desired character. There is an <link
            href="output.html#pdf-fonts">overview</link> available for the
          default PDF fonts. 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>
        <ul>
          <li>
            The most popular one that we are aware of is <link
              href="http://www.lowagie.com/iText">iText</link>, which has tools
            for adding security features, document properties, watermarks, and
            many other features to PDF files. FOP and iText can be integrated
            into one Java application, see sample code for <link
              href="#pdf-security">encryption</link>.
            The bad news is that iText swallows PDF bookmarks.
          </li>

          <li>
            You can use Adobe Acrobat (the full version, not the Reader) to
            process the file manually or with scripting that it supports.
          </li>
        </ul>
      </answer>
    </faq>
    <faq id="pdf-security">
      <question>How do I add security features (encryption, disable printing)
      to my PDF document?</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>
        <p>
          Some sample code for encrypting a FOP generated PDF with iText to
          get you started:
        </p>
        <source><![CDATA[public static void main(String args[]) {
  try {
    ByteArrayOutputStream fopout=new ByteArrayOutputStream();
    FileOutputStream outfile=new FileOutputStream(args[2]);
    Driver driver =new Driver();
    driver.setOutputStream(fopout);
    driver.setRenderer(Driver.RENDER_PDF);
    Transformer transformer=TransformerFactory
      .newInstance().newTransformer(new StreamSource(new File(args[1])));
    transformer.transform(new StreamSource(new File(args[0])),
       new SAXResult(driver.getContentHandler()));
    PdfReader reader = new PdfReader(fopout.toByteArray());
    int n = reader.getNumberOfPages();
    Document document = new Document(reader.getPageSizeWithRotation(1));
    PdfWriter writer = PdfWriter.getInstance(document, outfile);
    writer.setEncryption(PdfWriter.STRENGTH40BITS, "pdf", null,
      PdfWriter.AllowCopy);
    document.open();
    PdfContentByte cb = writer.getDirectContent();
    PdfImportedPage page;
    int rotation;
    int i = 0;
    while (i < n) {
      i++;
      document.setPageSize(reader.getPageSizeWithRotation(i));
      document.newPage();
      page = writer.getImportedPage(reader, i);
      rotation = reader.getPageRotation(i);
      if (rotation == 90 || rotation == 270) {
        cb.addTemplate(page, 0, -1f, 1f, 0, 0,
         reader.getPageSizeWithRotation(i).height());  }
      else {
        cb.addTemplate(page, 1f, 0, 0, 1f, 0, 0);
      }
      System.out.println("Processed page " + i);
    }
    document.close();
  }
  catch( Exception e) {
    e.printStackTrace();
  }
}]]></source>
        <p>
          Check the iText tutorial and documentation for setting access flags,
          password, encryption strength and other parameters.
        </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>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>
    <faq id="pdf_watermark">
      <question>How do I add watermarks to my PDF document?</question>
      <answer>
        <p>FOP does not currently support this feature. Possible
        workarounds:</p>
        <ul>
          <li>
            Use a background image for the body region.
          </li>
          <li>
            See the <link href="#PDF-postprocess">PDF Post-Processing
              FAQ</link>.
          </li>
          <li>
            (submitted by Trevor_Campbell@kaz.com.au) Place an image in a
            region that overlaps the flowing text. For example, make
            region-before large enough to contain your image. Then include a
            block (if necessary, use an absolutely positioned block-container)
            containing the watermark image in the static-content for the
            region-before. Note that the image will be drawn on top of the
            normal content.
          </li>
        </ul>
      </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. Some suggestions:
        </p>
        <ul>
          <li>
            Use an URL ending in <code>.pdf</code>, like
            <code>http://myserver/servlet/stuff.pdf</code>. Yes, the servlet can
            be configured to handle this. If the URL has to contain parameters,
            try to have both the base URL as well as the last parameter end in
            <code>.pdf</code>, if necessary append a dummy parameter, like
            <code>http://myserver/servlet/stuff.pdf?par1=a&amp;par2=b&amp;d=.pdf</code>. The
            effect may depend on IEx version.
          </li>
          <li>
            Give IEx the opportunity to cache. In particular, ensure the server
            does not set any headers causing IEx not to cache the content. This
            may be a real problem if the document is sent over HTTPS. Consult
            your server manual.
          </li>
          <li>
            Cache in the server. Including a parameter in the URL which has a
            timestamp as the value may help you to decide whether a request is
            repeated. IEx is reported to retrieve a document up to three times,
            but never more often.
          </li>
        </ul>
      </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 http://marc.theaimsgroup.com/?l=fop-dev&amp;m=101065988325115&amp;w=2
        </p>
      </answer>
    </faq>
  </part>
  <part id="part_input">
    <title>More general questions regarding XSLT and 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>
          Use display-align="center". FOP implements this for block containers
          and table cell. A small self-contained document centering an image on
          a page:
        </p>
        <source><![CDATA[<?xml version="1.0"?>
<fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format">
  <fo:layout-master-set>
    <fo:simple-page-master master-name="content"
      page-width="210mm" page-height="297mm">
      <fo:region-body/>
    </fo:simple-page-master>
  </fo:layout-master-set>
  <fo:page-sequence master-reference="content">
    <fo:flow flow-name="xsl-region-body">
      <fo:table table-layout="fixed" width="100%">
        <fo:table-column column-width="proportional-column-width(1)"/>
        <fo:table-body>
          <fo:table-row height="297mm">
            <fo:table-cell display-align="center">
              <fo:block text-align="center">
                <fo:external-graphic src="fop.jpg"/>
              </fo:block>
            </fo:table-cell>
          </fo:table-row>
        </fo:table-body>
      </fo:table>
    </fo:flow>
  </fo:page-sequence>
</fo:root>]]></source>
      </answer>
    </faq>
    <faq id="fo_center_table_horizon">
      <question>(FO) How do I center a table horizontally?</question>
      <answer>
        <p>
          You can add a column left and right wich pad the table so that the visible part is centered.
        </p>
        <source><![CDATA[<?xml version="1.0"?>
<fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format">
  <fo:layout-master-set>
    <fo:simple-page-master master-name="content"
      page-width="210mm" page-height="297mm">
      <fo:region-body/>
    </fo:simple-page-master>
  </fo:layout-master-set>
  <fo:page-sequence master-reference="content">
    <fo:flow flow-name="xsl-region-body">
      <fo:table table-layout="fixed" width="100%">
        <fo:table-column column-width="proportional-column-width(1)"/>
        <fo:table-column column-width="100mm"/>
        <fo:table-column column-width="proportional-column-width(1)"/>
        <fo:table-body>
          <fo:table-row>
            <fo:table-cell/>
            <fo:table-cell>
              <fo:block>foo</fo:block>
            </fo:table-cell>
            <fo:table-cell/>
          </fo:table-row>
        </fo:table-body>
      </fo:table>
    </fo:flow>
  </fo:page-sequence>
</fo:root>]]></source>
        <p>
          If your table is more complicated, or if defining borders on individual cells becomes too much work, use the code above and nest your table within the moddle cell.
        </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>
          Place different static content on <link href="#oddeven">odd and even
          pages</link>.
        </p>
      </answer>
    </faq>
    <faq id="oddeven">
      <question>(FO) How do I use different static content for odd and even
      pages?</question>
      <answer>
        <p>
          There are examples in the FO distribution and in the <link
          href="http://www.dpawson.co.uk/xsl/sect3/index.html">XSL FAQ FO
          section</link>.
        </p>
        <p>
          Define a page master with alternating pages masters for odd and even
          pages, specify appropriate regions in these page masters, and be sure
          to give them different names. You use these names to put different
          static content in these regions. A self contained document
          demonstrating this:
        </p>
        <source><![CDATA[<?xml version="1.0"?>
<fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format">
  <fo:layout-master-set>
    <fo:simple-page-master master-name="even"
      page-height="297mm" page-width="210mm"
      margin-top="20mm" margin-bottom="20mm"
      margin-left="25mm" margin-right="25mm">
      <fo:region-body margin-bottom="20mm"/>
      <fo:region-after region-name="footer-even" extent="20mm"/>
    </fo:simple-page-master>
    <fo:simple-page-master master-name="odd"
      page-height="297mm" page-width="210mm"
      margin-top="20mm" margin-bottom="20mm"
      margin-left="25mm" margin-right="25mm">
      <fo:region-body margin-bottom="20mm"/>
      <fo:region-after region-name="footer-odd" extent="20mm"/>
    </fo:simple-page-master>
    <fo:page-sequence-master master-name="document">
      <fo:repeatable-page-master-alternatives>
        <fo:conditional-page-master-reference odd-or-even="even"
          master-reference="even"/>
        <fo:conditional-page-master-reference odd-or-even="odd"
          master-reference="odd"/>
      </fo:repeatable-page-master-alternatives>
    </fo:page-sequence-master>
  </fo:layout-master-set>
  <fo:page-sequence master-reference="document">
    <fo:static-content flow-name="footer-even">
      <fo:block text-align="start"><fo:page-number/></fo:block>
    </fo:static-content>
    <fo:static-content flow-name="footer-odd">
      <fo:block text-align-last="end"><fo:page-number/></fo:block>
    </fo:static-content>
    <fo:flow flow-name="xsl-region-body">
      <fo:block/>
      <fo:block break-before="page"/>
    </fo:flow>
  </fo:page-sequence>
</fo:root>]]></source>
      </answer>
    </faq>
    <faq id="fo_first_page_header">
      <question>(FO) How do I get a special header on the first page?</question>
      <answer>
        <p>
          You can insert it into the flow instead of the static content.
          Alternatively, use a page master referring to different page masters
          for the first page and the rest. It is quite similar to the odd/even
          page mechanism. A code sample:
        </p>
        <source><![CDATA[<?xml version="1.0"?>
<fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format">
  <fo:layout-master-set>
    <fo:simple-page-master master-name="first"
      page-height="297mm" page-width="210mm"
      margin-top="20mm" margin-bottom="20mm"
      margin-left="25mm" margin-right="25mm">
      <fo:region-body margin-bottom="20mm"/>
      <fo:region-after region-name="footer-first" extent="20mm"/>
    </fo:simple-page-master>
    <fo:simple-page-master master-name="rest"
      page-height="297mm" page-width="210mm"
      margin-top="20mm" margin-bottom="20mm"
      margin-left="25mm" margin-right="25mm">
      <fo:region-body margin-bottom="20mm"/>
      <fo:region-after region-name="footer-rest" extent="20mm"/>
    </fo:simple-page-master>
    <fo:page-sequence-master master-name="document">
      <fo:repeatable-page-master-alternatives>
        <fo:conditional-page-master-reference page-position="first"
          master-reference="first"/>
        <fo:conditional-page-master-reference page-position="rest"
          master-reference="rest"/>
      </fo:repeatable-page-master-alternatives>
    </fo:page-sequence-master>
  </fo:layout-master-set>
  <fo:page-sequence master-reference="document">
    <fo:static-content flow-name="footer-first">
      <fo:block text-align="center">First page.</fo:block>
    </fo:static-content>
    <fo:static-content flow-name="footer-rest">
      <fo:block text-align-last="center">Other page.</fo:block>
    </fo:static-content>
    <fo:flow flow-name="xsl-region-body">
      <fo:block/>
      <fo:block break-before="page"/>
      <fo:block break-before="page"/>
    </fo:flow>
  </fo:page-sequence>
</fo:root>]]></source>
      </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>
          A blank page can be forced by a <code>break-before="page-even"</code>
          or similar properties, or by a force-page-count="end-on-odd" on a page
          sequence, which ensures a new chapter or something starts on the
          preferred page.
        </p>
        <p>
          You can define a conditional page master with a page master specific
          for blank pages. This allows you to specify static content for blank
          pages (by definition, a page is blank if no content from a flow is
          rendered on the page). You can omit your normal headers and footers,
          and use for example an extended header to print the "..left blank"
          statement.
        </p>
        <source><![CDATA[<?xml version="1.0"?>
<fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format">
  <fo:layout-master-set>
    <fo:simple-page-master master-name="normal"
      page-height="297mm" page-width="210mm"
      margin-top="20mm" margin-bottom="20mm"
      margin-left="25mm" margin-right="25mm">
      <fo:region-body margin-bottom="20mm"/>
      <fo:region-after region-name="footer-normal" extent="20mm"/>
    </fo:simple-page-master>
    <fo:simple-page-master master-name="blank"
      page-height="297mm" page-width="210mm"
      margin-top="20mm" margin-bottom="20mm"
      margin-left="25mm" margin-right="25mm">
      <fo:region-body/>
      <fo:region-before region-name="header-blank" extent="297mm"/>
    </fo:simple-page-master>
    <fo:page-sequence-master master-name="document">
      <fo:repeatable-page-master-alternatives>
        <fo:conditional-page-master-reference blank-or-not-blank="not-blank"
          master-reference="normal"/>
        <fo:conditional-page-master-reference blank-or-not-blank="blank"
          master-reference="blank"/>
      </fo:repeatable-page-master-alternatives>
    </fo:page-sequence-master>
  </fo:layout-master-set>
  <fo:page-sequence master-reference="document" force-page-count="end-on-even">
    <fo:static-content flow-name="footer-normal">
      <fo:block text-align="center">Normal footer</fo:block>
    </fo:static-content>
    <fo:static-content flow-name="header-blank">
      <fo:block space-before="100mm" text-align-last="center">
        Intentionally left blank.</fo:block>
    </fo:static-content>
    <fo:flow flow-name="xsl-region-body">
      <fo:block/>
    </fo:flow>
  </fo:page-sequence>
</fo:root>]]></source>
      </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>
          Try to look the character up in the Unicode reference at the <link
            href="http://www.unicode.org">Unicode Consortium</link>, in
            particular search the <link
            href="http://www.unicode.org/charts/charindex.html">reference by
            name</link>.
        </p>
        <p>
          Use <link
            href="http://www.w3.org/TR/2000/REC-xml-20001006#sec-references">XML
            character references</link> to put the character into your source
          XML, XSLT or FO.
        </p>
        <p>
          For example, the following will result in an Euro sign:
        </p>
        <source><![CDATA[&#x20AC;]]></source>
        <p>
          The selected font family must have a glyph for the character you want
          to show. This is actually a somewhat tricky issue, especially for
          symbol characters.
        </p>
        <p>
          Some environments provide also a character table utility (like Win2K
          or WinXP), which can also help you to get an idea what glyphs are
          available in a certain font.
        </p>
        <p>
          Alternative: Use an embedded graphic: GIF, PNG, SVG, whatever.
        </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>
          The specification provides some properties for this: <link
          href="http://www.w3.org/TR/xsl/slice7.html#white-space-collapse">white
          space collapsing</link> and <link
          href="http://www.w3.org/TR/xsl/slice7.html#linefeed-treatment">line
          feed treatment</link>. In FOP, use white-space-collapse="false" on an
          enclosing block. This will also preserve line breaks (which is
          actually a bug, expect this to be changed).
        </p>
      </answer>
    </faq>
    <faq id="fo_total_pages">
      <question>(FO) How do I print the total number of pages, like in "page 1
      of 12"</question>
      <answer>
        <anchor id="pagenum"/>
        <p>
          This is an XSL FAQ.
        </p>
        <p>
          Put an empty block with an id at the end of the flow:
        </p>
        <source><![CDATA[<fo:flow ...>
    ...
  <fo:block id="last-page"/>
</fo:flow>]]></source>
        <p>
          Get the number of the last page as follows:
        </p>
        <source><![CDATA[ <fo:page-nuber-citation ref-id="last-page"/>]]></source>
        <p>
          This does not work for all problems, for example if you have multiple
          page sequences, an initial page number different from 1, or if you
          force a certain page count, thereby producing blank pages at the end.
        </p>
        <p>
          There is no reliable way to get the real total page count with FO
          mechanisms, you can only get <em>page numbers</em>.
        </p>
        <p>
          The FOP library provides a method to get the total page count after a
          FO document has been rendered. You can implement your own wrapper to
          do a dummy rendering, inquire the total page count and the perform the
          real rendering, passing the total page count to the XSLT processor to
          splice it into the generated FO. A sample code:
        </p>
        <source><![CDATA[import org.apache.fop.apps.*;
import org.xml.sax.*;
import java.io.*;
import javax.xml.transform.*;
import javax.xml.transform.sax.*;
import javax.xml.transform.stream.*;

class rendtest {

  public static void main(String args[]) {
    try {
      Driver driver=new Driver();
      driver.setOutputStream(new FileOutputStream(args[2]));
      driver.setRenderer(Driver.RENDER_PDF);
      Transformer transformer=TransformerFactory.newInstance()
        .newTransformer(new StreamSource(new File(args[1])));
      transformer.setParameter("page-count","#");
      transformer.transform(new StreamSource(new File(args[0])),
        new SAXResult(driver.getContentHandler()));
      String pageCount=Integer.toString(driver.getResults().getPageCount());
      driver=new Driver();
      driver.setOutputStream(new FileOutputStream(args[2]));
      driver.setRenderer(Driver.RENDER_PDF);
      transformer=TransformerFactory.newInstance()
        .newTransformer(new StreamSource(new File(args[1])));
      transformer.setParameter("page-count",pageCount);
      transformer.transform(new StreamSource(new File(args[0])),
        new SAXResult(driver.getContentHandler()));
    }
    catch( Exception e) {
      e.printStackTrace();
    }
  }
}]]></source>
        <p>
          Declare and use the parameter "page-count" in your XSLT. Be aware you
          may run into convergence problems: replacing the "#" placeholder from
          the first run by the actual page count may change it.
        </p>
      </answer>
    </faq>
    <faq id="fo_region_overlap">
      <question>(FO) The header overlaps body content. The body extends into
      the footer.</question>
      <answer>
        <p>
          Contrary to popular opinion, the regions on a page may overlap.
          Defining a certain body region does not automatically constrain other
          regions, this has to be done explicitely.
        </p>
        <p>
          If you have a header region with an extent of 20mm, you should define
          a margin for the body region of at least 20mm too, otherwise the
          header content may overwrite some stuff in the body region. This
          applies similarly to the extent of the after region and the bottom
          margin of the body region.
        </p>
        <p>
          The overlap effect can be used creatively for some purposes.
        </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>
          Several possibilities:
        </p>
        <ul>
          <li>
            Use fo:leader (look up the details in the <link
            href="http://www.w3.org/TR/xsl/slice6.html#fo_leader">XSLFO
            specification</link>, or use a book). For horizontal lines only.
          </li>
          <li>
            Use a solid border on a suitable fo:block. Horizontal and vertical
            lines only.
          </li>
          <li>
            Insert a graphic. GIF, PNG SVG, whatever.
          </li>
        </ul>
      </answer>
    </faq>
    <faq id="FO-validate">
      <question>(FO) How do I validate my FO document?</question>
      <answer>
        <p>
          <link href="http://www.renderx.com">RenderX</link> has provided an
          <link
            href="http://www.renderx.com/Tests/validator/fo.dtd.html">Unofficial
            DTD for FO Documents</link>. This document may be helpful in
          validating general FO issues.
        </p>
        <p>
          FOP also maintains an <link
            href="http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-fop/docs/foschema/fop.xsd?rev=HEAD&amp;content-type=text/plain">Unofficial
            FOP Schema</link> in the FOP CVS Repository. This document can be
          used either to validate against the FO standard, or against the
          actual FOP implementation. See the notes near the beginning of the
          document for instructions on how to use it.
        </p>
      </answer>
    </faq>
    <faq id="xml_non-breaking_space">
      <question>(XML) There are complaints about <code>&amp;nbsp;</code>. How
        do I get a non-breaking space in FO?</question>
      <answer>
        <p>
          Use &amp;#160; everywhere. In your own XML, you could also use a DTD
          which declares the entity.
        </p>
      </answer>
    </faq>
    <faq id="xml_undefined_entities">
      <question>(XML) There are complaints about undefined entities, for example
        about <code>&amp;uuml;</code> which used to work in HTML. How do I enter
        special characters like in HTML?</question>
      <answer>
        <p>
          Don't use names as in HTML, use numbers (unless you have a DTD which
          declares the entities). For predefined HTML entities and their Unicode
          codepoints see <link
          href="http://www.w3.org/TR/html4/sgml/entities.html">Character entity
          references in HTML 4</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>
          Make sure ampersands in text and attributes are written as &amp;amp;,
          "&lt;" is written as &amp;lt; and ">" as &amp;gt;. It's not necessary
          everywhere but do it just to be sure.
        </p>
        <p>
          The XML parser should give the proper line and possibly column for
          offending characters.
        </p>
        <p>
          Refer to the <link href="http://www.w3.org/XML/">XML
            specification</link> or to a good tutorial for details of the XML
            file format.
        </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>
          Usually, this is a character encoding problem. See <link
          href="http://www.dpawson.co.uk/xsl">XSL FAQ</link>. Many software
          packages producing XML, in particular most XSLT processors, produce by
          default UTF-8 encoded files. If you view them with something not aware
          of the encoding, like Notepad for Win95/98/ME/NT, funny characters are
          displayed. A &#197; is a giveaway.
        </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>