git-svn-id: https://svn.apache.org/repos/asf/xmlgraphics/fop/branches/fop-0_20_2-maintain@196709 13f79535-47bb-0310-9956-ffa450edef68

21 years ago · 726f89d6ad
--- a/src/documentation/content/xdocs/book.xml
+++ b/src/documentation/content/xdocs/book.xml
@@ -8,18 +8,8 @@
        copyright="@year@ The Apache Software Foundation"
        xmlns:xlink="http://www.w3.org/1999/xlink">

        <menu label="About">
          <menu-item label="Home" href="index.html"/>
          <menu-item label="News" href="news.html"/>
          <menu-item label="Logo contest" href="logocontest.html"/>
        </menu>

        <menu label="Project">
          <menu-item label="Status" href="status.html"/>
          <!--
 	  <menu-item label="Changes" href="changes.html"/>
          <menu-item label="Todo" href="todo.html"/>
 	  -->
        <menu label="Home">
          <menu-item label="Introduction" href="index.html"/>
        </menu>

        <menu label="Using FOP">
@@ -29,6 +19,7 @@
          <menu-item label="Configure" href="configuration.html"/>
          <menu-item label="Run" href="running.html"/>
          <menu-item label="Embed" href="embedding.html"/>
          <menu-item label="Servlets" href="servlets.html"/>
          <menu-item label="Ant task" href="anttask.html"/>
        </menu>

@@ -38,6 +29,7 @@
          <menu-item label="PDF encryption" href="pdfencryption.html"/>
          <menu-item label="Graphics" href="graphics.html"/>
          <menu-item label="Fonts" href="fonts.html"/>
          <menu-item label="Hyphenation" href="hyphenation.html"/>
          <menu-item label="Extensions" href="extensions.html"/>
        </menu>

@@ -46,8 +38,21 @@
          <menu-item label="FAQs" href="faq.html"/>
          <menu-item label="XSL-FO" href="fo.html"/>
          <menu-item label="Examples" href="examples.html"/>
          <menu-item label="Mailing Lists" href="maillist.html"/>
          <menu-item label="Bugs" href="bugs.html"/>
          <menu-item label="License" href="license.html"/>
          <menu-item label="Other" href="resources.html"/>
        </menu>

        <menu label="Project">
          <menu-item label="News" href="news.html"/>
          <menu-item label="Logo contest" href="logocontest.html"/>
          <menu-item label="Status" href="status.html"/>
          <!--
          <menu-item label="Changes" href="changes.html"/>
          <menu-item label="Todo" href="todo.html"/>
          -->
          <menu-item label="Team" href="team.html"/>
        </menu>

    </book>
--- a/src/documentation/content/xdocs/compiling.xml
+++ b/src/documentation/content/xdocs/compiling.xml
@@ -7,33 +7,34 @@
    <title>FOP: Building from Source Code</title>
  </header>
  <body>
    <section>
    <section id="build-needed">
      <title>Do You Need To Build?</title>
      <p>FOP distributions are either pre-compiled binary or source.
 If you are using a binary distribution, it is already built and there is no need to build it again. See the <link href="download.html">Download Instructions</link> for information about whether a binary or source distribution is best for your needs.
      </p>
    </section>
    <section>
    <section id="env">
      <title>Set Up Your Environment</title>
      <section>
      <section id="env-jdk">
        <title>JDK</title>
          <p>
            Building FOP requires a minimum Java Development Kit (JDK) of 1.3.
            Building FOP requires a minimum Java Development Kit (JDK/SDK) of 1.3
            (A Java Runtime Environment ist not sufficient)
          </p>
      </section>
      <section>
      <section id="env-classpath">
        <title>CLASSPATH</title>
        <p>There is no generally no need to setup a classpath.
 All libraries needed to compile FOP are included in the source distribution and are referenced by the build script.
 You will only need to adjust the classpath if you build FOP in some other way. See the build scripts (build.bat for Windows, and build.sh for Unix) for details.</p>
      </section>
      <section>
      <section id="env-java-home">
        <title>JAVA_HOME</title>
        <p>Ant, which is used by the build script, requires that the environment variable JAVA_HOME point to your local JDK root directory.
 This is true even if you use JDK 1.2 or above, which normally don't need this setting.</p>
      </section>
  </section>
  <section>
  <section id="build-script">
    <title>Run the "build" Script</title>
    <p>Build FOP by executing the "build" script, which is located in the FOP root directory.
 The Windows batch file is build.bat, and the Unix shell script is build.sh.
@@ -59,8 +60,8 @@ To obtain a complete list of useful build targets:</p>
    <p>To clean the build directory first:</p>
    <source>build.sh clean package</source>
  </section>
  <section>
    <title>Troubleshooting</title>
  <section id="problems">
    <title id="Troubleshooting">Troubleshooting</title>
    <p>If you have problems building FOP, please try the following:</p>
    <ul>
      <li>Run the build with the target of "clean", then rerun the build.</li>
--- a/src/documentation/content/xdocs/compliance.xml
+++ b/src/documentation/content/xdocs/compliance.xml
@@ -216,7 +216,7 @@ want it to.</comment>
        </level-2>
        <level-2 name="Common Font Properties" citation="§7.8" extURL="slice7.html#common-font-properties" ref-name="commonfont">
          <level-3 name="font-family" citation="§7.8.2" extURL="slice7.html#font-family" compliance-level="1" comply="yes">
          	<comment>font-family lists are not suppported, use a single font-family name</comment>
          	<comment>font-family lists are not supported, use a single font-family name</comment>
          </level-3>
          <level-3 name="font-selection-strategy" citation="§7.8.3" extURL="slice7.html#font-selection-strategy" compliance-level="3" comply="no"/>
          <level-3 name="font-size" citation="§7.8.4" extURL="slice7.html#font-size" compliance-level="1" comply="yes"/>
@@ -299,8 +299,12 @@ want it to.</comment>
          <level-3 name="line-stacking-strategy" citation="§7.15.6" extURL="slice7.html#line-stacking-strategy" compliance-level="1" comply="no"/>
          <level-3 name="linefeed-treatment" citation="§7.15.7" extURL="slice7.html#linefeed-treatment" compliance-level="2" comply="no"/>
          <level-3 name="white-space-treatment" citation="§7.15.8" extURL="slice7.html#white-space-treatment" compliance-level="2" comply="no"/>
          <level-3 name="text-align" citation="§7.15.9" extURL="slice7.html#text-align" compliance-level="1" comply="yes"/>
          <level-3 name="text-align-last" citation="§7.15.10" extURL="slice7.html#text-align-last" compliance-level="2" comply="yes"/>
          <level-3 name="text-align" citation="§7.15.9" extURL="slice7.html#text-align" compliance-level="1" comply="partial">
            <comment>Only start, end, center and justify are supported</comment>
          </level-3>
          <level-3 name="text-align-last" citation="§7.15.10" extURL="slice7.html#text-align-last" compliance-level="2" comply="partial">
            <comment>Only start, end, center and justify are supported</comment>
          </level-3>
          <level-3 name="text-indent" citation="§7.15.11" extURL="slice7.html#text-indent" compliance-level="1" comply="yes"/>
          <level-3 name="white-space-collapse" citation="§7.15.12" extURL="slice7.html#white-space-collapse" compliance-level="2" comply="yes"/>
          <level-3 name="wrap-option" citation="§7.15.13" extURL="slice7.html#wrap-option" compliance-level="1" comply="yes"/>
--- a/src/documentation/content/xdocs/configuration.xml
+++ b/src/documentation/content/xdocs/configuration.xml
@@ -4,62 +4,83 @@

 <document>
  <header>
    <title>Configuration</title>
    <title>FOP: Configuration</title>
  </header>

  <body>
  <section>
    <title>How to configure FOP</title>
    <p>In the directory xml-fop/conf you will find two configuration files. One of them,
       config.xml, is only intended for FOP developers, who want to add new default values
       to some FOP feature. Don't change this file. For user configuration there is a file called
       userconfig.xml. It contains templates for all settings a user can change. Most of them are
       commented out. Uncomment the entry you want to set and change the value according to
       your wishes. Please regard any comments which specify the value range. And, well, the
       configuration files are xml files, so keep them at least well-formed. ;-)
    </p>
    <p>The file userconfig.xml is not read automatically, but the user must specify its use on
       the command line. See <link href="running.html">Running FOP</link>
       or <link href="embedding.html">Embedding FOP</link> for details.
    </p>
  <section id="general">
    <title>Configuration File Basics</title>
    <p>The FOP configuration file is an XML file containing a variety of settings that are useful for controlling FOP's behavior, and for helping it find resources that you wish it to use.</p>
    <p>The easiest way to get started using a FOP configuration file is to copy the sample found at <code>{fop-dir}/conf/userconfig.xml</code> to a location of your choice, and then to edit it according to your needs.
 It contains templates for the various configuration options, most of which are commented out. Remove the comments and change the settings for entries that you wish to use.
 Be sure to follow any instructions, including comments which specify the value range.
 Also, since the configuration file is XML, be sure to keep it well-formed.</p>
    <note>Do <strong>not</strong> change <code>{fop-dir}/conf/config.xml</code> or use it as the basis for your configuration file. It has an entirely different purpose.</note>
    <section id="general-entries">
      <title>Creating Entries</title>
      <p>The general structure of the configuration file is a series of &lt;entry> tags, each containing a &lt;key> and a &lt;value>. (Fonts use a different format). Here is an example:</p>
      <source><![CDATA[<entry>
  <key>strokeSVGText</key>
  <value>false</value>
 </entry>]]></source>
    </section>
    <section id="general-available">
      <title>Making Configuration Available to FOP</title>
      <p>After creating your configuration file, you must tell FOP how to find it:</p>
      <ul>
        <li>If running FOP from the command-line, see the "-c" command-line option in <link href="running.html">Running FOP</link>.</li>
        <li>If running FOP as an embedded application, see <link href="embedding.html#config-external">FOP: Embedding, Using a Configuration File</link>.</li>
      </ul>
      <p>See <link href="embedding.html#config-internal">Setting the Configuration Programmatically</link> for instructions on how to do so in an embedded environment.</p>
    </section>
  </section>
  <section>
    <title>Setting up hyphenation</title>
    <p>FOP comes already with some hyphenation pattern. If you need a hyphenation pattern
       which isn't included in the distribution, do the following:
    </p>
    <ol>
      <li>
 Get the TeX hyphenation pattern file and turn it into an xml file which
 conforms to the hyphenation.dtd in the subdirectory /src/hyph.
      </li>
      <li>
 Name this new file following this schema: languageCode_countryCode.xml. If
 you don't need a country code, leave it out, e.g the file name for an American
 english hyphenation pattern would look like this: en_US.xml. For an Italian 
 file: it.xml. Language and country codes must be the same as in xsl:fo, that
 is follow
 <link href="http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt">ISO 639</link>
 and
 <link href="http://www.ics.uci.edu/pub/ietf/http/related/iso3166.txt">ISO 3166</link>
 respectively. NOTE: The ISO 639/ISO 3166 convention is that language names are
 written in lower case, while country codes are written in upper case.
      </li>
      <li>
 If you have build your new hyphenation pattern file successfully there are
 two ways to make it accessible to FOP.
        <ul>
          <li>
 Put this new file into the directory /src/hyph and rebuild FOP. The file will
 be picked up and added to the fop.jar.
          </li>
          <li>
 Put the file into a directory of your choice and specify this directory
 in the userconfig.xml in the entry &lt;hyphenation-dir>.
          </li>
        </ul>
      </li>
    </ol>
  <section id="summary-key-value">
    <title>Summary of Key-Value Configuration Options</title>
    <table>
      <tr>
        <th>Option (key)</th>
        <th>Data Type (for the value)</th>
        <th>Default Value</th>
      </tr>
      <tr>
        <td>baseDir</td>
        <td>URL</td>
        <td>For command-line, the directory containing the input FO or XML file. For embedded, the current working directory.</td>
      </tr>
      <tr>
        <td>fontBaseDir</td>
        <td>URL</td>
        <td>value of baseDir</td>
      </tr>
      <tr>
        <td><link href="#hyphenation-dir">hyphenation-dir</link></td>
        <td>URL</td>
        <td>None. This is for custom hyphenation patterns.</td>
      </tr>
      <tr>
        <td><link href="#svg-strokeSVGText">strokeSVGText</link></td>
        <td>Boolean</td>
        <td>True</td>
      </tr>
    </table>
  </section>
  <section id="detail-key-value">
    <title>Detail for Key-Value Configuration Options</title>
    <p>The sections below provide detailed information for configuration options that are not self-explanatory. The parenthetical information after each key name indicates (Data Type, Default).</p>
    <section id="hyphenation-dir">
      <title>hyphenation-dir (URL, none)</title>
      <p>Use this entry to indicate a directory containing custom hyphenation files (if any).
 See <link href="hyphenation.html">FOP: Hyphenation</link> for more information on creating and modifying hyphenation within FOP.</p>
    </section>
    <section id="strokeSVGText">
      <title>strokeSVGText (boolean, True)</title>
      <p>In some cases, some text in SVG documents is converted to graphical shapes instead of retaining its character as text. To force all text to be rendered as text, set strokeSVGText = false. For a discussion of this issue, see <link href="graphics.html#svg-pdf-text">FOP: Graphics, Placing SVG Text into PDF</link>.</p>
      <note>strokeSVGText is currently only effective in the PDF renderer.</note>
    </section>
  </section>
  <section id="fonts">
    <title>Fonts</title>
    <p>Font configuration information is included in the FOP configuration file, but is documented at <link href="fonts.html">FOP: Fonts</link>. Note especially the section entitled <link href="fonts.html#register">Register Fonts with FOP</link>.</p>
  </section>
  </body>
 </document>
--- a/src/documentation/content/xdocs/dev/api-doc.xml
+++ b/src/documentation/content/xdocs/dev/api-doc.xml
@@ -15,7 +15,7 @@
        <li><link href="http://nagoya.apache.org/gump/javadoc/xml-fop-maintenance/build/javadocs/index.html">Javadocs for Maintenance Branch</link></li>
        <li><link href="http://nagoya.apache.org/gump/javadoc/xml-fop/build/javadocs/index.html">Javadocs for Trunk (Redesign)</link></li>
      </ul>
      <note>If the links return an "Object not found!" message or otherwise do not work properly, it is probably because of a build error. Please raise a question on the <link href="../resources.html#mailing-lists-fop-user">fop-user mailing list</link> so that any problems can be fixed before the next build.</note>
      <note>If the links return an "Object not found!" message or otherwise do not work properly, it is probably because of a build error. Please raise a question on the <link href="../maillist.html#fop-user">fop-user mailing list</link> so that any problems can be fixed before the next build.</note>
    </section>
    <section id="self-built">
      <title>Building them Yourself</title>
--- a/src/documentation/content/xdocs/dev/book.xml
+++ b/src/documentation/content/xdocs/dev/book.xml
@@ -11,7 +11,8 @@
      <menu-item label="Basics" href="index.html"/>
    </menu>
    <menu label="Design">
      <menu-item label="Resolved" href="../design/index.html"/>
      <!--<menu-item label="Resolved" href="../design/index.html"/>-->
      <menu-item label="Resolved" href="http://xml.apache.org/fop/design/index.html"/>      
      <external label="Unresolved (Wiki)" href="http://nagoya.apache.org/wiki/apachewiki.cgi?FOPProjectPages"/>
      <menu-item label="SVG" href="svg.html"/>
      <menu-item label="Fonts" href="fonts.html"/>
--- a/src/documentation/content/xdocs/dev/doc.xml
+++ b/src/documentation/content/xdocs/dev/doc.xml
@@ -19,6 +19,22 @@ The major exception to this rule is the design doc, which currently exclusively
 Maintenance branch releases either copy the trunk content to the maintenance branch or use the trunk content directly for doc builds.</note>
      <p>Basic documents are stored in XML files, and use DTDs provided by Apache Forrest.</p>
    </section>
    <section id="design">
      <title>Design Principles</title>
      <p>These principles are not written in stone, but reflect the current philosophy, and are documented here primarily to help achieve consistency. These principles should be changed if better or more practical ones are found, but they should probably be discussed and changed by common consent.</p>
      <section id="where">
        <title>Where</title>
        <ul>
          <li>To the extent possible, keep user content separate from developer content, primarily so the user doesn't have to filter out technical information.</li>
          <li>To the extent possible, try to document a topic exactly once, in the place the user is most likely to look for it, then link to that from other locations as appropriate. This is somewhat contrary to the principle above, which should be applied as a higher priority.</li>
        </ul>
      </section>
      <section id="design-when">
        <title>When</title>
        <p>The documentation and the product are in a constant state of change, and there is some difficulty in deciding what product state the website content should reflect. The current thinking is that the website should reflect the current state of the repository code branch from which releases are made. Features or other documentation that applies to unreleased code should be marked in such a way within the content that the user can determine whether and how it applies to the version they are using. For example, "Feature xyz is first available in Release n.nn.n".</p>
        <p>Other approaches were considered, but all seemed to have significantly higher costs both to the users and the developers. From the user's standpoint, the choice is either that they potentially have to look multiple places to get the information they need (which was rejected), or they have to filter out an occasional feature that is in code available subsequent to their release (which was accepted).</p>
      </section>
    </section>
    <section id="web">
      <title>Website</title>
      <section id="web-background">
--- a/src/documentation/content/xdocs/dev/extensions.xml
+++ b/src/documentation/content/xdocs/dev/extensions.xml
@@ -38,7 +38,7 @@ They are loaded by FOP when parsing starts to validate input.</li>
 correct name space.
 The examples for SVG and pdfoutline.fo show how this can be done.
 The pdf documents on the FOP site use this extension.
 See also <link href="examples.html">Examples</link> for more examples.</li>
 See also <link href="../examples.html">Examples</link> for more examples.</li>
          <li>Put your jar file in the classpath</li>
          <li>Run FOP using your XSL-FO file as input.</li> 
        </ol>
--- a/src/documentation/content/xdocs/dev/index.xml
+++ b/src/documentation/content/xdocs/dev/index.xml
@@ -18,7 +18,7 @@ This certainly includes programmers, but may also include those contributing to
      <ul>
        <li>The oldest is the one that releases are currently generated from, and is also called the "maintenance branch". Because of limitations in its design, the FOP committers decided to freeze new development on this branch, and are providing only bug fixes. This branch is tagged as "fop-0_20_2-maintain" in the CVS repository.</li>
        <li>The main development line is the future of FOP. It was spawned from the "maintenance" branch, but had to quickly be "broken" so that the needed redesign could be dropped into place. It is currently not as mature as the "maintenance" branch, but has far greater long-term prospects. It is also known as the "root" or "trunk" or "redesign".</li>
        <li>The "Alt Design" is exactly that: an alternative design approach. Because its efforts are largely complementary and parallel to the main development branch, and because it is expected to be merged at some point into the trunk, it is <link href="../design/alt.design/index.html">documented separately</link>. The authors of this effort are currently in the process of merging their work into the trunk.</li>
        <li>The "Alt Design" is exactly that: an alternative design approach. Because its efforts are largely complementary and parallel to the main development branch, and because it is expected to be merged at some point into the trunk, it is <link href="http://xml.apache.org/fop/design/alt.design/index.html">documented separately</link>. The authors of this effort are currently in the process of merging their work into the trunk.</li>
      </ul>
      <p>Please note that patches for enhancements to the maintenance branch will generally not be considered. Bug fixes are welcome there, but new developers are strongly encouraged to apply their efforts to the trunk development line.</p>
      <p>Because there is a fair amount of common information between the maintenance and trunk development lines, we attempt to document them together, highlighting differences only where needed.</p>
@@ -57,7 +57,7 @@ This certainly includes programmers, but may also include those contributing to
      </section>
      <section id="design">
        <title>Understand FOP's Design</title>
        <p>The design for FOP is specified under the <link href="../design/index.html">Design</link> section. This is where the information on how FOP is developed and designed
        <p>The design for FOP is specified under the <link href="http://xml.apache.org/fop/design/index.html">Design</link> section. This is where the information on how FOP is developed and designed
 internally will be kept.
    </p>
      </section>
--- a/src/documentation/content/xdocs/download.xml
+++ b/src/documentation/content/xdocs/download.xml
@@ -20,7 +20,11 @@ However, a source distribution will be preferable if you fall into one of the fo
  <section id="binary">
    <title>Binary Download</title>
    <p>Binary distributions include "-bin" in their names, and can be downloaded from the <link href="http://xml.apache.org/dist/fop/">FOP Distribution</link> directory.
 </p>
    </p>
    <note>We're in the process of moving the download location. Please download the
      latest release candidate from a
      <link href="http://www.apache.org/dyn/closer.cgi/xml/fop">mirror</link>.
    </note>
  </section>
  <section id="source">
    <title>Source Download</title>
@@ -38,4 +42,4 @@ Anyone can do this using the <link href="http://xml.apache.org/cvs.html#AnonCVS"
    </body>
 </document>

 <!-- Last Line of $RCSFile$ -->
 <!-- Last Line of $RCSfile$ -->
--- a/src/documentation/content/xdocs/embedding.xml
+++ b/src/documentation/content/xdocs/embedding.xml
@@ -36,231 +36,178 @@
  <p>Here is an example use of Driver which outputs PDF:
  </p>
    <source><![CDATA[
   import org.apache.fop.apps.Driver;
 import org.apache.fop.apps.Driver;

   /*..*/
 /*..*/

   Driver driver = new Driver(new InputSource(args[0]),
                              new FileOutputStream(args[1]));
   driver.setRenderer(Driver.RENDER_PDF);
   driver.run();]]></source>
 Driver driver = new Driver(new InputSource(args[0]),
                           new FileOutputStream(args[1]));
 driver.setRenderer(Driver.RENDER_PDF);
 driver.run();]]></source>
  <p>
 In the example above, args[0] contains the path to an XSL-FO file, while 
 args[1] contains a path for the target PDF file.
  </p>
  <p>You also need to set up logging. Global logging for all FOP
    processes is managed by MessageHandler. Per-instance logging
    is handled by Driver. You want to set both using an implementation
    of org.apache.avalon.framework.logger.Logger. See 
    <jump href="#logging">below</jump> for more information.
  </p>
  <section id="basic-logging">
    <title>Logging</title>
    <p>
      You also need to set up logging. Global logging for all FOP
      processes is managed by MessageHandler. Per-instance logging
      is handled by Driver. You want to set both using an implementation
      of org.apache.avalon.framework.logger.Logger. See 
      <jump href="#logging">below</jump> for more information.
    </p>
    <p>
      Call <code>setLogger(Logger)</code> always immediately after 
      instantiating the Driver object. See here:
    </p>
    <source><![CDATA[
   import org.apache.avalon.framework.logger.Logger; 
   import org.apache.avalon.framework.logger.ConsoleLogger; 
   
   /*..*/
    
   Logger logger = new ConsoleLogger(ConsoleLogger.LEVEL_INFO);
   MessageHandler.setScreenLogger(logger);
   driver.setLogger(logger);]]></source>
 import org.apache.avalon.framework.logger.Logger; 
 import org.apache.avalon.framework.logger.ConsoleLogger; 

  <p>To setup the user config file you can do the following
  </p>
 /*..*/

 Driver driver = new Driver();
 Logger logger = new ConsoleLogger(ConsoleLogger.LEVEL_INFO);
 MessageHandler.setScreenLogger(logger);
 driver.setLogger(logger);]]></source>
  </section>

  <section id="render">
    <title>Processing XSL-FO</title>
    <p>
      Once the Driver is set up, one of the <code>render()</code> methods
      is called. Depending on whether DOM or an InputSource is being used, the
      invocation of the method is either <code>render(Document)</code> or
      <code>render(Parser, InputSource)</code> respectively.
    </p>
    <p>
      <strong>Another possibility may be used to build the FO Tree: You can
      call <code>getContentHandler()</code> and fire the SAX events yourself.
      </strong>
      You don't have to call <code>run()</code> or <code>render()</code> on the 
      Driver object if you use <code>getContentHandler()</code>.
    </p>
    <p>Here is an example use of Driver:</p>
    <source><![CDATA[
   import org.apache.fop.apps.Options;
   
   /*..*/ 
    
   userConfigFile = new File(userConfig);
   options = new Options(userConfigFile);]]></source>
    <note>
        This is all you need to do, it sets up a static configuration class.
    </note>
 Driver driver = new Driver();
 //Setup logging here: driver.setLogger(...
 driver.setRenderer(Driver.RENDER_PDF);
 driver.setInputSource(new FileInputSource(args[0]));
 driver.setOutputStream(new FileOutputStream(args[1]));
 driver.run();]]></source>
  </section>

  <p>Once the Driver is set up, the render method
     is called. Depending on whether DOM or SAX is being used, the
     invocation of the method is either <code>render(Document)</code> or
     <code>render(Parser, InputSource)</code> respectively.
  </p>
  <p>
     <strong>Another possibility may be used to build the FO Tree. You can
     call <code>getContentHandler()</code> and fire the SAX events yourself.
     </strong>
  </p>
  <p>Once the FO Tree is built, the format() and render() methods may be
     called in that order.
  </p>
  <p>Here is an example use of Driver:</p>
  <source><![CDATA[
  Driver driver = new Driver();
  driver.setRenderer(Driver.RENDER_PDF);
  driver.setInputSource(new FileInputSource(args[0]));
  driver.setOutputStream(new FileOutputStream(args[1]));
  driver.run();]]></source>
  <p>You can also specify an xml and xsl file for the input.
  </p>
  <p>Here is an example use of Driver with the XSLTInputHandler:</p>
  <source><![CDATA[
  Driver driver = new Driver();
  driver.setRenderer(Driver.RENDER_PDF);
  InputHandler inputHandler = new XSLTInputHandler(xmlFile, xslFile);
  XMLReader parser = inputHandler.getParser();
  driver.setOutputStream(new FileOutputStream(outFile));
  driver.render(parser, inputHandler.getInputSource());]]></source>
  <p>Have a look at the classes CommandLineStarter or FopServlet for complete
     examples. Also, have a look at the examples at the bottom of this page.
  </p>
  <section id="render-with-xslt">
    <title>Processing XSL-FO generated from XML+XSLT</title>
    <p>
      If you want to process XSL-FO generated from XML using XSLT we recommend 
      using standard JAXP to do the XSLT part and piping the generated SAX 
      events directly through to FOP. Here's how this would look like:
    </p>
    <source><![CDATA[
 Driver driver = new Driver();
 //Setup logging here: driver.setLogger(...
 driver.setRenderer(Driver.RENDER_PDF);

 //Setup the OutputStream for FOP
 driver.setOutputStream(new java.io.FileOutputStream(outFile));

 //Make sure the XSL transformation's result is piped through to FOP
 Result res = new SAXResult(driver.getContentHandler());

 //Setup XML input
 Source src = new StreamSource(xmlFile);

 <note>If your XSL-FO files contain SVG then Batik will be used. When Batik is
 initialised it uses certain classes in <code>java.awt</code> that
 intialises the java AWT classes. This means that a daemon thread
 is created by the JVM and on Unix it will need to connect to a
 DISPLAY.
 The thread means that the Java application will not automatically quit
 when finished, you will need to call <code>System.exit()</code>. These
 issues should be fixed in the upcoming JDK 1.4</note>
 //Setup Transformer
 Source xsltSrc = new StreamSource(xslFile);
 TransformerFactory transformerFactory = TransformerFactory.newInstance();
 Transformer transformer = transformerFactory.newTransformer(xsltSrc);

 //Start the transformation and rendering process
 transformer.transform(src, res);]]></source>
    <note>There's no need to call <code>run()</code> or <code>render()</code>.</note>
    <p>
      This may look complicated at first, but it's really just the combination of an 
      XSL transformation and a FOP run. It's also easy to comment out the FOP part
      for debugging purposes, for example when you're tracking down a bug in your 
      stylesheet. You can easily write the XSL-FO output from the XSL transformation
      to a file to check if that part generates the expected output.
    </p>
    <p>
      For fully working examples of the above and hints to some interesting 
      possibilities, see the <link href="#examples">examples section</link> below.
    </p>
  </section>
  </section>
  <section id="logging">
    <title>Controlling logging</title>
    <p>FOP uses Jakarta Avalon's
      <fork href="http://jakarta.apache.org/avalon/api/org/apache/avalon/framework/logger/Logger.html">Logger</fork>
       interface to do logging. See the <fork href="http://jakarta.apache.org/avalon/">Jakarta Avalon project</fork> for more information.</p>
    <p>Per default FOP uses the ConsoleLogger which logs to System.out. If you want to do logging using a
    logging framework (such as LogKit, Log4J or JDK 1.4 Logging) you can set a
    different Logger implementation on the Driver object. Here's an example how you would use LogKit:</p>
    <p>
      FOP uses the
      <fork href="http://avalon.apache.org/framework/api/org/apache/avalon/framework/logger/package-summary.html">Logger package</fork>
      from Apache Avalon Framework to do logging. See the 
      <fork href="http://avalon.apache.org/framework/">Apache Avalon Framework</fork>
      for more information.
    </p>
    <p>
      Per default FOP uses the ConsoleLogger which logs to System.out. If you want to do logging using a
      logging framework (such as LogKit, Log4J or JDK 1.4 Logging) you can set a
      different Logger implementation on the Driver object. Here's an example how you would use LogKit:
    </p>
    <source><![CDATA[
    Hierarchy hierarchy = Hierarchy.getDefaultHierarchy();
    PatternFormatter formatter = new PatternFormatter(
       "[%{priority}]: %{message}\n%{throwable}" );
 Hierarchy hierarchy = Hierarchy.getDefaultHierarchy();
 PatternFormatter formatter = new PatternFormatter(
    "[%{priority}]: %{message}\n%{throwable}" );

    LogTarget target = null;
    target = new StreamTarget(System.out, formatter);
 LogTarget target = null;
 target = new StreamTarget(System.out, formatter);

    hierarchy.setDefaultLogTarget(target);
    log = hierarchy.getLoggerFor("fop");
    log.setPriority(Priority.INFO);
 hierarchy.setDefaultLogTarget(target);
 log = hierarchy.getLoggerFor("fop");
 log.setPriority(Priority.INFO);

    driver.setLogger(new org.apache.avalon.framework.logger.LogKitLogger(log));]]></source>
  <p>The LogKitLogger class implements the Logger interface so all logging calls are being redirected to LogKit.
  More information on Jakarta LogKit can be found <fork href="http://jakarta.apache.org/avalon/logkit/index.html">here</fork>.</p>
  <p>Similar implementations exist for Log4J (org.apache.avalon.framework.logger.Log4JLogger) and
  JDK 1.4 logging (org.apache.avalon.framework.logger.Jdk14Logger).</p>
  <p>If you want FOP to be totally silent you can also set an org.apache.avalon.framework.logger.NullLogger instance.</p>
  <p>If you want to use yet another logging facility you simply have to create a class that implements org.apache.avalon.framework.logging.Logger
  and set it on the Driver object. See the existing implementations in Avalon Framework for examples.</p>
  </section>
    <section id="input">
      <title>Input Sources</title>
      <p>The input XSL-FO document is always handled internally as SAX (see the <link href="http://xml.apache.org/fop/design/parsing.html">Parsing Design Document</link> for the rationale).
 However, the input itself can be provided in a variety of ways to FOP, which normalizes the input (if necessary) into SAX events:</p>
      <ul>
        <li><strong>SAX Events through SAX Handler</strong>: <code>FOTreeBuilder</code> is the SAX Handler which is obtained through <code>getContentHandler</code> on <code>Driver</code>.</li>
        <li><strong>DOM (which is converted into SAX Events)</strong>: The conversion of a DOM tree is done via the <code>render(Document)</code> method on <code>Driver</code>.</li>
        <li><strong>Data Source (which is parsed and converted into SAX Events)</strong>: The <code>Driver</code> can take an <code>InputSource</code> as input.
 This can use a <code>Stream</code>, <code>String</code> etc.</li>
        <li><strong>XML+XSLT Transformation</strong> (which is transformed using an XSLT Processor and the result is fired as SAX Events: <code>XSLTInputHandler</code> is used as an <code>InputSource</code> in the render(<code>XMLReader</code>, <code>InputSource</code>) method on <code>Driver</code>.</li>
      </ul>
      <p>There are a variety of upstream data manipulations possible.
 For example, you may have a DOM and an XSL stylesheet; or you may want to
 set variables in the stylesheet.
 Interface documentation and some cookbook solutions to these situations are provided in <fork href="http://xml.apache.org/xalan-j/usagepatterns.html">Xalan Basic Usage Patterns</fork>.</p>
     <p>
 See the <link href="#examples">Examples</link> for some variations on input. 
     </p>
    </section>
  <section id="hints">
    <title>Hints</title>
    <section id="object-reuse">
      <title>Object reuse</title>
     <p>
 If FOP is going to be used multiple times within your application
 it may be useful to reuse certain objects to save time.
     </p>
     <p>
 The renderers and the driver can both be reused. A renderer is reusable
 once the previous render has been completed. The driver is reuseable
 after the rendering is complete and the reset method is called.
 You will need to setup the driver again with a new OutputStream,
 IntputStream and renderer.
     </p>
    </section>
    <section id="render-info">
      <title>Getting information on the rendering process</title>
      <p>
 To get the number of pages that were rendered by FOP you can call 
 <code>Driver.getResults()</code>. This returns a FormattingResults object 
 where you can lookup the number of pages produced. It also gives you the 
 page-sequences that were produced along with their id attribute and their 
 number of pages. This is particularly useful if you render multiple 
 documents (each enclosed by a page-sequence) and have to know the number of 
 pages of each document.
      </p>
    </section>
  </section>
  <section id="servlet">
    <title>Using FOP in a Servlet</title>
      <p>
        Here is a minimal code snippet to demonstrate the basics:
      </p>
      <source>response.setContentType("application/pdf");
 Driver driver=new Driver( new InputSource("foo.fo"),
                          response.getOutputStream());
 driver.setRenderer(Driver.RENDER_PDF);
 driver.run();</source>
      <p>
 There are numerous problems with the code snippet above.
 Its purpose is only to demonstrate the basic concepts.
 See xml-fop/examples/servlet for a working example of FOP used in a servlet.
 After building the servlet, drop the fop.war into the webapps directory of Tomcat.
 Then access a URL as follows:
     </p>
     <p>http://localhost:8080/fop/fop?fo=/home/path/to/fofile.fo</p>
     <p>http://localhost:8080/fop/fop?xml=/home/path/to/xmlfile.xml&amp;xsl=/home/path/to/xslfile.xsl</p>
     <p>The source code for the servlet can be found under xml-fop/examples/servlet/src/FopServlet.java.</p>
      <note>
        Some versions of Internet Explorer will not automatically show the PDF.
 This is well-known to be a limitation of Internet Explorer, and is not a problem with the servlet.
 However, Internet Explorer can still be used to download the PDF so that it can be viewed later. Also, appending ".pdf" to the end of the URL may help.
      </note>
  </section>
  <section id="servlet-transform">
    <title>Using FOP in a Servlet with an XSLT Transformation</title>
 driver.setLogger(new org.apache.avalon.framework.logger.LogKitLogger(log));]]></source>
    <p>
      If both the source XML and XSL are read from files, use the TraxInputHandler:
      The LogKitLogger class implements the Logger interface so all logging calls are being redirected to LogKit.
      More information on Jakarta LogKit can be found <fork href="http://jakarta.apache.org/avalon/logkit/index.html">here</fork>.
    </p>
    <source>response.setContentType("application/pdf");
 XSLTInputHandler input
  =new XSLTInputHandler(new File("foo.xml"), new File("foo.xsl"));
 Driver driver=new Driver();
 driver.setOutputStream(response.getOutputStream());
 driver.setRenderer(Driver.RENDER_PDF);
 driver.render(input.getParser(), input.getInputSource());</source>
    <p>
      This code snippet has the same problems as the one from the <link href="#servlet">section above</link>.
      Similar implementations exist for Log4J (org.apache.avalon.framework.logger.Log4JLogger) and
      JDK 1.4 logging (org.apache.avalon.framework.logger.Jdk14Logger).
    </p>
    <p>
      If your source XML is generated on the fly (for example from a database, a web service, or another servlet), create a transformer object explicitly, and use a SAX event stream to feed the transformation result into FOP:
      If you want FOP to be totally silent you can also set an org.apache.avalon.framework.logger.NullLogger instance.
    </p>
    <source>response.setContentType("application/pdf");
 Driver driver =new Driver();
 driver.setOutputStream(response.getOutputStream());
 driver.setRenderer(Driver.RENDER_PDF);
 Transformer transformer=TransformerFactory.newInstance()
        .newTransformer(new StreamSource("foo.xsl"));
 transformer.transform(xmlsource, new SAXResult(driver.getContentHandler()));</source>
    <p>
      You don't have to call run() or render() on the driver object.
      If you want to use yet another logging facility you simply have to create a class that 
      implements org.apache.avalon.framework.logging.Logger and set it on the Driver object. 
      See the existing implementations in Avalon Framework for examples.
    </p>
  </section>
  <section id="input">
    <title>Input Sources</title>
    <p>
      The <code>xmlsource</code> is a placeholder for your actual XML source.
 If you have to read the XML from a string, supply a <code>new StreamSource(new StringReader(xmlstring))</code>.
 Constructing and reparsing an XML string is generally less desirable than using a SAXSource if you generate your XML.
 You can alternatively supply a DOMSource as well.
 You may also use dynamically generated XSL if you like.
      The input XSL-FO document is always handled internally as SAX (see the 
      <link href="http://xml.apache.org/fop/design/parsing.html">Parsing Design Document</link> for the rationale).
      However, the input itself can be provided in a variety of ways to FOP, 
      which normalizes the input (if necessary) into SAX events:
    </p>
    <ul>
      <li><strong>SAX Events through SAX Handler</strong>: <code>FOTreeBuilder</code> is the SAX Handler which is obtained through <code>getContentHandler</code> on <code>Driver</code>.</li>
      <li><strong>DOM (which is converted into SAX Events)</strong>: The conversion of a DOM tree is done via the <code>render(Document)</code> method on <code>Driver</code>.</li>
      <li><strong>Data Source (which is parsed and converted into SAX Events)</strong>: The <code>Driver</code> can take an <code>InputSource</code> as input.
 This can use a <code>Stream</code>, <code>String</code> etc.</li>
      <li><strong>XML+XSLT Transformation</strong> (which is transformed using an XSLT Processor and the result is fired as SAX Events: <code>XSLTInputHandler</code> is used as an <code>InputSource</code> in the render(<code>XMLReader</code>, <code>InputSource</code>) method on <code>Driver</code>.</li>
    </ul>
    <p>
      Because you have an explicit transformer object, you can also use it to explicitly set parameters for the transformation run.
      There are a variety of upstream data manipulations possible.
      For example, you may have a DOM and an XSL stylesheet; or you may want to
      set variables in the stylesheet. Interface documentation and some cookbook 
      solutions to these situations are provided in 
      <fork href="http://xml.apache.org/xalan-j/usagepatterns.html">Xalan Basic Usage Patterns</fork>.
    </p>
    <p>
      See the <link href="#examples">Examples</link> for some variations on input. 
    </p>
  </section>
  <section id="config-external">
@@ -268,9 +215,19 @@ You may also use dynamically generated XSL if you like.
    <p>
      To access an external configuration:
    </p>
    <source>org.apache.fop.apps.Options options = new Options(new File("userconfig.xml"));</source>
    <source><![CDATA[
 import org.apache.fop.apps.Options;

 /*..*/

 userConfigFile = new File(userConfig);
 options = new Options(userConfigFile);]]></source>
    <note>
        This is all you need to do, it sets up a static configuration class.
    </note>
    <p>
      No further reference to the <code>options</code> variable is necessary.
      The "options = " is actually not even necessary.
    </p>
    <p>
      See <link href="#multithreading">Multithreading FOP</link> for issues related to changing configuration in a multithreaded environment.
@@ -290,6 +247,82 @@ You may also use dynamically generated XSL if you like.
      See <link href="#multithreading">Multithreading FOP</link> for issues related to changing configuration in a multithreaded environment.
    </p>
  </section>
  <section id="hints">
    <title>Hints</title>
    <section id="object-reuse">
      <title>Object reuse</title>
     <p>
 If FOP is going to be used multiple times within your application
 it may be useful to reuse certain objects to save time.
     </p>
     <p>
 The renderers and the driver can both be reused. A renderer is reusable
 once the previous render has been completed. The driver is reuseable
 after the rendering is complete and the <code>reset()</code> method is called.
 You will need to setup the driver again with a new OutputStream,
 IntputStream and renderer.
     </p>
    </section>
    <section id="awt">
      <title>AWT issues</title>
      <p>
        If your XSL-FO files contain SVG then Batik will be used. When Batik is
        initialised it uses certain classes in <code>java.awt</code> that
        intialises the java AWT classes. This means that a daemon thread
        is created by the JVM and on Unix it will need to connect to a
        DISPLAY.
      </p>
      <p>
        The thread means that the Java application may not automatically quit
        when finished, you will need to call <code>System.exit()</code>. These
        issues should be fixed in the upcoming JDK 1.4.
      </p>
      <p>
        If you run into trouble running FOP on a head-less server, please see the
        <link href="graphics.html#batik">notes on Batik</link>.
      </p>
    </section>
    <section id="render-info">
      <title>Getting information on the rendering process</title>
      <p>
 To get the number of pages that were rendered by FOP you can call 
 <code>Driver.getResults()</code>. This returns a FormattingResults object 
 where you can lookup the number of pages produced. It also gives you the 
 page-sequences that were produced along with their id attribute and their 
 number of pages. This is particularly useful if you render multiple 
 documents (each enclosed by a page-sequence) and have to know the number of 
 pages of each document.
      </p>
    </section>
  </section>
  <section id="performance">
    <title>Improving performance</title>
    <p>
      There are several options to consider:
    </p>
    <ul>
      <li>
        Whenever possible, try to use SAX to couple the individual components involved 
        (parser, XSL transformer, SQL datasource etc.).
      </li>
      <li>
        Depending on the target OutputStream (in case of an FileOutputStream, but not 
        for a ByteArrayOutputStream, for example) it may improve performance considerably 
        if you buffer the OutputStream using a BufferedOutputStream: 
        <code>driver.setOutputStream(new java.io.BufferedOutputStream(out));</code>
        <br/>
        Make sure you properly close the OutputStream when FOP is finished.
      </li>
      <li>
        Cache the stylesheet. If you use the same stylesheet multiple times 
        you can setup a JAXP <code>Templates</code> object and reuse it each time you do
        the XSL transformation.
      </li>
      <li>
        Use an XSLT compiler like XSLTC that comes with Xalan-J.
      </li>
    </ul>
  </section>
  <section id="multithreading">
    <title>Multithreading FOP</title>
    <p>
@@ -299,44 +332,26 @@ variables for configuration data and loading images.
 Here are some tips to mitigate these problems:
    </p>
    <ul>
      <li>To avoid having your threads blocked, create a Driver object for each thread.</li>
      <li>If possible, do not change the configuration data while there is a Driver object rendering.
 Setup the configuration only once, preferably in the <code>init()</code> method of the servlet.
      <li>
        To avoid having your threads blocked, create a Driver object for each thread.
      </li>
      <li>If you must change the configuration data more often, or if you have multiple servlets within the same webapp using FOP, consider implementing a singleton class to encapsulate the configuration settings and to run FOP in synchronized methods.
      <li>
        If possible, do not change the configuration data while there is a Driver object rendering.
        Setup the configuration only once, preferably in the <code>init()</code> method of the servlet.
      </li>
      <li>
        If you must change the configuration data more often, or if you have multiple 
        servlets within the same webapp using FOP, consider implementing a singleton 
        class to encapsulate the configuration settings and to run FOP in synchronized methods.
      </li>
    </ul>
  </section>
  <section id="servlet-engine">
    <title>Servlet Engines</title>
    <p>
      When using a servlet engine, there are potential CLASSPATH issues, and potential conflicts with existing XML/XSLT libraries.
 Servlet containers also often use their own classloaders for loading webapps, which can cause bugs and security problems.
    </p>
    <section id="tomcat">
      <title>Tomcat</title>
        <p>
          Check Tomcat's documentation for detailed instructions about installing FOP and Cocoon.
 There are known bugs that must be addressed, particularly for Tomcat 4.0.3.
        </p>
    </section>
    <section id="websphere">
      <title>WebSphere 3.5</title>
      <p>
        Put a copy of a working parser in some directory where WebSphere can access it.
 For example, if /usr/webapps/yourapp/servlets is the CLASSPATH for your servlets, copy the Xerces jar into it (any other directory would also be fine).
 Do not add the jar to the servlet CLASSPATH, but add it to the CLASSPATH of the application server which contains your web application.
 In the WebSphere administration console, click on the "environment" button in the "general" tab.
 In the "variable name" box, enter "CLASSPATH".
 In the "value" box, enter the correct path to the parser jar file (/usr/webapps/yourapp/servlets/Xerces.jar in our example here).
 Press "OK", then apply the change and restart the application server.
      </p>
    </section>
    <p>There is also a known issue with fonts being jumbled between threads when using the AWT renderer (which is used by the -awt and -print output options).
 In general, you cannot safely run multiple threads through the AWT renderer.</p>
  </section>
 <section id="examples">
  <title>Examples</title>
  <p>
 The directory "xml-fop/examples/embedding" contains several working examples. 
 The directory "{fop-fir}/examples/embedding" contains several working examples. 
 In contrast of the examples above the examples here primarily use JAXP for 
 XML access. This may be easier to understand for people familiar with JAXP.
  </p>
--- a/src/documentation/content/xdocs/examples.xml
+++ b/src/documentation/content/xdocs/examples.xml
@@ -7,6 +7,11 @@
    <title>Examples</title>
  </header>
  <body>
    <section>
      <title>Example Documents Using FOP</title>
      <p>
        These examples have been rendered using FOP:
      </p>
    <table>
      <caption>Generated examples</caption>
      <tr>
@@ -20,10 +25,7 @@
        <td><link href="fo/fonts.fo.pdf">fonts.fo.pdf</link></td>
      </tr>
    </table>

    <section>
      <title>Examples in the distribution</title>
    <p>Examples for the use of XSL-FO can be found in the FOP distribution in
    <p>Other basic examples on the use of XSL-FO can be found in the FOP distribution in
       the subdirectory xml-fop/examples/fo. You can start transformation of all fo files into pdf
       files by starting xml-fop/examples/fo/runtests (only source distribution). The resulting test
       files can be found in xml-fop/examples/fo/tests
@@ -57,18 +59,66 @@
      </li>
      <li>readme.fo - uses an old version of FOP documentation for a longer example
      </li>

      <li>Look also into the directory examples/fo/svg. There you find some very extensive SVG examples.
      </li>
      <li>In the directory examples/fo/pagination you find a suite of examples showing the use
          of XSL-FO pagination.
      </li>
    </ul>
      <p>Also, in the directory examples/fo/pagination you will find a suite of examples showing the use
          of XSL-FO pagination.
      </p>
      <p>
 Developers will find the first steps to a test suite for all implemented
 formatting objects and properties in xml-fop/test/xml/.
      </p>
    </section>
 	</section>
          <section>
            <title>Images Examples</title>
            <p>
 Embedding images in FO:
            </p>
  <table>
    <caption>Images in FO</caption>
    <tr>
      <th>description</th>
      <th>fo file</th>
      <th>pdf result</th>
    </tr>
    <tr>
      <td>align in larger viewport</td>
      <td><link href="fo/align.fo">align.fo</link></td>
      <td><link href="fo/align.fo.pdf">align.fo.pdf</link></td>
    </tr>
    <tr>
      <td>align in smaller viewport</td>
      <td><link href="fo/align2.fo">align2.fo</link></td>
      <td><link href="fo/align2.fo.pdf">align2.fo.pdf</link></td>
    </tr>
    <tr>
      <td>scaling image</td>
      <td><link href="fo/size.fo">size.fo</link></td>
      <td><link href="fo/size.fo.pdf">size.fo.pdf</link></td>
    </tr>
  </table>
      <p>Look also into the directory examples/fo/svg. There you find some very extensive SVG examples.
      </p>
          </section>
          <section>
            <title>Instream Foreign Object Examples</title>
            <p>
 Instream Foreign Object images in FO, there are more on the
 <link href="dev/svg.html">SVG Page</link>:
            </p>
  <table>
    <caption>Embedding instream-foreign-object</caption>
    <tr>
      <th>description</th>
      <th>fo file</th>
      <th>pdf result</th>
    </tr>
    <tr>
      <td>embedding svg in viewport</td>
      <td><link href="fo/embed.fo">embed.fo</link></td>
      <td><link href="fo/embed.fo.pdf">embed.fo.pdf</link></td>
    </tr>
  </table>
  </section>
  </body>
 </document>

--- a/src/documentation/content/xdocs/faq.xml
+++ b/src/documentation/content/xdocs/faq.xml
@@ -138,22 +138,21 @@
          definitions.
        </p>
        <p>
          See also <link href="relnotes.html">release notes</link>.
          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 <!--link
            href="classpath.html"-->classpath<!--/link-->.</p>
        <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 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.
            Use the fop.bat or fop.sh 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
@@ -162,8 +161,11 @@
          </li>
        </ul>
        <p>
          If you run FOP embedded in your servlet, web application or other
          Java application, check the classpath of the application.
          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 <link
          href="servlets.html#servlet-engine">servlet engines</link>
          for further hints.
        </p>
      </answer>
    </faq>
@@ -248,7 +250,7 @@
        </p>
        <p>
          If you use XSLT, problems in your style sheet and in your source XML
          also often produce a NullPointerException. Run the transformation
          also can produce a NullPointerException. Run the transformation
          separately to check for this, usually you'll get a detailed error
          message from the XSLT processor.
        </p>
@@ -307,22 +309,7 @@
    <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-->
        <p>The src attribute of the fo:external-graphics 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">
@@ -330,7 +317,7 @@
      <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
          : 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>
@@ -339,11 +326,51 @@
          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 fontBaseDir configuration. (FIXME: add
          link to congfiguration page)
        </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.20.5. 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 text-align="justify" and/or
          text-align-last="justify" to the block with the leader. Be
          sure you haven't accidentally overridden the
          leader-length.maximum="100%" 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>
@@ -488,27 +515,38 @@ Any easy way to check this is to cut&amp;paste the source URL from the fo:extern
      <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.
          This happens for fo:page-number-citation 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>
          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.
          The most recent FOP releases should have this problem
          fixed. Check whether you can upgrade.
        </p>
      </answer>
    </faq>
    <faq id="hypenation-fails">
    <faq id="hyphenation-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.
          Set the language attribute somewhere and explicitly enable hyphenation. 
          Check whether you use a language for which hyphenation is supported. 
          Supported languages can be deduced from the files in the {fop-dir}/src/hyph
          directory of the FOP source distribution. If you want to use a language
          FOP currently doesn't hyphenate, please see the 
          <link href="configuration.html#hyphenation">Configuration page</link>.
        </p>
        <p>
          Set the language (on fo:page-sequence, fo:block or fo:character):
        </p>
        <source><![CDATA[<fo:page-sequence language="fi">]]></source>
        <p>
          Enable hyphenation on a block:
        </p>
        <source><![CDATA[<fo:block hyphenate="true">]]></source>
      </answer>
    </faq>
  </part>
@@ -678,17 +716,28 @@ Can I control this?</question>
      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>.
          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="output.html#pdf-fonts">overview</link> for the default
          PDF fonts.
        </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
          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="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>
@@ -758,31 +807,9 @@ Can I control this?</question>
      <answer>
        <p>
          This is a problem of Internet Explorer requesting the content several
          times. Some suggestions:
          times. Please see the <link href="servlets.html#ie">notes on Internet Explorer</link>
          for more information.
        </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">
@@ -937,7 +964,7 @@ Can I control this?</question>
      in the input.</question>
      <answer>
        <p>
          See <link href="fo.html#xml-entity-chars">XML Entity Characters</link>.
          See <link href="fo.html#xml-entity-chars">Using HTML Character Names</link>.
        </p>
      </answer>
    </faq>
--- a/src/documentation/content/xdocs/fo.xml
+++ b/src/documentation/content/xdocs/fo.xml
@@ -12,7 +12,8 @@
      <p>
        FOP uses XSL-FO as input.
 It is the responsibility of the user to make sure that the XSL-FO submitted to FOP is correct.
 The tutorial items presented here are not comprehensive, but are of the FAQ variety.
 The tutorial items presented here are not comprehensive, but are of the FAQ variety. Another 
 good FAQ is <fork href="http://www.dpawson.co.uk/xsl/xslfaq.html">Dave Pawson's XSL FAQ</fork>.
      </p>
    </section>
    <section id="xml">
@@ -325,7 +326,7 @@ To accomplish this, place an empty block with an id at the end of the flow:
        <p>
          Get the number of the last page as follows:
        </p>
        <source><![CDATA[ <fo:page-nuber-citation ref-id="last-page"/>]]></source>
        <source><![CDATA[ <fo:page-number-citation ref-id="last-page"/>]]></source>
        <p>
          This does not work in certain situations: multiple page sequences, an initial page number other than 1, or forcing a certain page count, thereby producing blank pages at the end.
        </p>
@@ -421,6 +422,28 @@ This document can be used either to validate against the FO standard, or against
 See the notes near the beginning of the document for instructions on how to use it.
          </p>
      </section>
      <section id="landscape">
        <title>Producing landscape pages</title>
        <p>
          Pages in landscape format can easily be produced by exchanging the page-height and page-width values of a simple-page-master element.
        </p>
        <source><![CDATA[<fo:layout-master-set>
  <fo:simple-page-master master-name="A4-portrait" page-height="29.7cm" page-width="21cm" [..]>
    <fo:region-body/>
  </fo:simple-page-master>
  <fo:simple-page-master master-name="A4-landscape" page-height="21cm" page-width="29.7cm" [..]>
    <fo:region-body/>
  </fo:simple-page-master>
 </fo:layout-master-set>]]></source>
      </section>
      <section id="external-resources">
        <title>External Resources</title>
        <p>Resources needed by an XSL-FO file that are external to it (graphics, for example), are defined in the XSL-FO standard as being of type "uri-specification". This is defined in the standard at <jump href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice5.html#section-N8794-Property-Datatypes">Section 5.11 Property Datatypes</jump>, which includes a link to the URI standard itself. Refer to the XSL-FO and URI standards themselves for more detailed instructions.</p>
        <p>URIs may be either absolute or relative to a base URI. (See <link href="configuration.html">FOP: Configuration</link> for information on setting the base URI for a FOP session). Here is an example referencing an external-graphic that is relative to the base URI:</p>
        <source><![CDATA[<fo:external-graphic src="url('images/logo.jpg')"/>]]></source>
        <p>Here is an example referencing an external-graphic that is an absolute URI on a local filesystem:</p>
        <source><![CDATA[fo:external-graphic src="url('file:d:///images/logo.jpg')"/>]]></source>
      </section>
    </section>
  </body>
 </document>
--- a/src/documentation/content/xdocs/fonts.xml
+++ b/src/documentation/content/xdocs/fonts.xml
@@ -1,195 +1,191 @@
 <?xml version="1.0" standalone="no"?>
 <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
    "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/schema/dtd/document-v11.dtd">

 <document>
  <header>
    <title>Fonts</title>
    <title>FOP: Fonts</title>
    <authors>
      <person name="Jeremias Märki" email=""/>
      <person name="Tore Engvig" email=""/>
     </authors>
    </authors>
  </header>
 <body>
  <section id="intro">
    <title>Important</title>
    <p>The information on this page applies primarily to the PDF renderer. The PostScript renderer
    also supports custom fonts but doesn't support font embedding, yet. This page does 
    <strong>not</strong> apply to the AWT, PCL, MIF and other renderers.</p>
    <p>The AWT renderer relies upon AWT to provide the available fonts. And it's the printer 
    driver of your operating system that decides if a font is embedded when using the AWT 
    renderer.</p>
  </section>
  <section id="status">
    <title>Status</title>
    <p>FOP (building PDF files) normally supports only the base 14 font package defined in the Adobe PDF specification.
    That includes the following fonts: Helvetica, Times, Courier, Symbol and ZapfDingbats.
    </p>
    <p>Font support in FOP can be extended by the addition of font metric files (written in XML) created from Adobe
    Type 1 fonts and TrueType fonts. No other font types (Type 3, etc.) are supported at this time.
    More information about font types can be found at
    the <link href="http://partners.adobe.com/asn/developer/type/ftypes.html">
    Adobe font types</link>. There is also lots more font information
    on this <link href="http://partners.adobe.com/asn/developer/technotes/fonts.html">Adobe Font Technote</link>.
    </p>
    <note>
        The font is simply embedded into the PDF file, it is not converted.
    </note>
  </section>
  <section id="type1">
    <title>Adding Type 1 fonts</title>
    <p>As mentioned above you need an XML file containing font metrics to be able to use an additional font. FOP
    contains a tool that can generate such a font metrics file from a PFM file, which normally comes with the font file.
    </p>
    <section id="type1-metrics">
      <title>Generating a font metrics file</title>
      <p> Run the class org.apache.fop.fonts.apps.PFMReader to generate the XML file.
      </p>
      <p>Windows:</p>
 <source>
 java -cp build\fop.jar;lib\avalon-framework.jar;lib\xml-apis.jar;
         lib\xercesImpl.jar;lib\xalan.jar
           org.apache.fop.fonts.apps.PFMReader pfm-file xml-file
 </source>
      <p>Unix:</p>
 <source>
 java -cp build/fop.jar:lib/avalon-framework.jar:lib/xml-apis.jar:
         lib/xercesImpl.jar:lib/xalan.jar
           org.apache.fop.fonts.apps.PFMReader pfm-file xml-file
 </source>
      <note>
        The classpath in the above example has been simplified for readibity. 
        You will have to adjust the classpath to the names of the actual JAR files in the lib directory.
        avalon-framework.jar is necessary only for versions 0.20.5 or later.
        xml-apis.jar, xercesImpl.jar and xalan.jar are not necessary for JDK version 1.4 or later.
      </note>
      <note>The tool will construct some values (FontBBox, StemV and ItalicAngle) based on assumptions and
      calculations which are only an approximation to the real values. FontBBox and Italic Angle can be found in
      the human-readable part of the PFB file or in the AFM file. The PFMReader tool does not yet interpret PFB or AFM files, so if you want
      to be correct, you may have to adjust the values in the XML file manually. The constructed values however
      appear to have no visible influence.
      </note>
  <body>
    <section id="intro">
      <title>Summary</title>
      <p>The following table summarizes the font capabilites of the various FOP renderers:</p>
      <table>
        <tr>
          <th>Renderer</th>
          <th>Base-14</th>
          <th>AWT/OS</th>
          <th>Custom</th>
          <th>Custom Embedding</th>
        </tr>
        <tr>
          <td>PDF</td>
          <td>yes</td>
          <td>no</td>
          <td>yes</td>
          <td>yes</td>
        </tr>
        <tr>
          <td>PostScript</td>
          <td>yes</td>
          <td>no</td>
          <td>yes</td>
          <td>no</td>
        </tr>
        <tr>
          <td>PCL</td>
          <td>yes (modified)</td>
          <td>no</td>
          <td>no</td>
          <td>no</td>
        </tr>
        <tr>
          <td>TXT</td>
          <td>yes (used for layout but not for output)</td>
          <td>no</td>
          <td>yes (used for layout but not for output)</td>
          <td>no</td>
        </tr>
        <tr>
          <td>AWT</td>
          <td>if available from OS</td>
          <td>yes</td>
          <td>no</td>
          <td>n/a (display only)</td>
        </tr>
        <tr>
          <td>Print</td>
          <td>if available from OS</td>
          <td>yes</td>
          <td>no</td>
          <td>controlled by OS printer driver</td>
        </tr>
        <tr>
          <td>RTF</td>
          <td>n/a (font metrics not needed)</td>
          <td>n/a</td>
          <td>n/a</td>
          <td>n/a</td>
        </tr>
        <tr>
          <td>MIF</td>
          <td>n/a (font metrics not needed)</td>
          <td>n/a</td>
          <td>n/a</td>
          <td>n/a</td>
        </tr>
        <tr>
          <td>SVG</td>
          <td>if available from OS</td>
          <td>yes</td>
          <td>no</td>
          <td>no</td>
        </tr>
        <tr>
          <td>XML</td>
          <td>yes</td>
          <td>no</td>
          <td>yes</td>
          <td>n/a</td>
        </tr>
      </table>
    </section>
    <section id="type1-register">
      <title>Register the fonts within FOP</title>
      <p>
        Edit conf/userconfig.xml and add entries for the font
        if the fonts section,
        ie:
      </p>
 <source><![CDATA[<font metrics-file="FTL_____.xml" kerning="yes"
      embed-file="C:\myfonts\FTL_____.pfb">
  <font-triplet name="FrutigerLight" style="normal" weight="normal">
 </font>]]></source>
      <note>
        Starting from FOP version 0.20.5 you can use URLs for the paths to the font files. Relative URLs are resolved 
        relative to the fontBaseDir property (or baseDir) if available.
      </note>
      <note>
        Make sure you specify the PFB file in the embed-file attribute 
        and not the PFM you used to generate the XML font metrics file.
      </note>
      <note>
        If you do not want the font embedded in the PDF then remove the
        "embed-file" attribute. The PDF will then contain text using
        the font with the font metrics and to view it properly the
        font will need to be installed where it is being viewed.
      </note>
      <note>
        Cocoon users will need to setup the config, see FOPSerializer
        for more information.
      </note>
    <section>
      <title>Base-14 Fonts</title>
      <p>The Adobe PDF Specification specifies a set of 14 fonts that must be available to every PDF reader: Helvetica (normal, bold, italic, bold italic), Times (normal, bold, italic, bold italic), Courier (normal, bold, italic, bold italic), Symbol and ZapfDingbats.</p>
    </section>
  </section>
  <section id="truetype">
    <title>Adding TrueType Fonts</title>
        <p>Adding TrueType fonts is almost identical to the process of
        adding Type 1 fonts. The main difference is in the first
        step.</p>

    <section id="truetype-metrics">
      <title>Generating a font metrics file</title>
            <p>As mentioned above you need an XML file containing font
            metrics to be able to use an additional font. FOP contains
            a tool that can generate such a font metrics file from
            your TrueType font file.
      </p>
      <p>
      Create metrics for the fontfile (we assume the file has
            the name cmr10.ttf and exists in c:\myfonts\):
      </p>
 <source>
 java -cp build\fop.jar;lib\avalon-framework.jar;lib\xml-apis.jar;
    <section id="awt">
      <title>AWT/Operating System Fonts</title>
      <p>The AWT family of renderers (AWT, Print, SVG), use the Java AWT libraries for font metric information. Through operating system registration, the AWT libraries know what fonts are available on the system, and the font metrics for each one.</p>
    </section>
    <section id="custom">
      <title>Custom Fonts</title>
      <p>Support for custom fonts is added by creating font metric files (written in XML) from the actual font files, and registering them with FOP. Currently only Type 1 and TrueType fonts can be added.
 More information about fonts can be found at:</p>
      <ul>
        <li><link href="http://partners.adobe.com/asn/developer/type/ftypes.html">Adobe font types</link></li>
        <li><link href="http://partners.adobe.com/asn/developer/technotes/fonts.html">Adobe Font Technote</link>
 </li>
      </ul>
      <section id="type1-metrics">
        <title>Type 1 Font Metrics</title>
        <p>FOP includes PFMReader, which reads the PFM file that normally comes with a Type 1 font, and generates an appropriate font metrics file for it.
 To use it, run the class org.apache.fop.fonts.apps.PFMReader:</p>
        <p>Windows:</p>
        <source>java -cp build\fop.jar;lib\avalon-framework.jar;lib\xml-apis.jar;
         lib\xercesImpl.jar;lib\xalan.jar
           org.apache.fop.fonts.apps.PFMReader pfm-file xml-file</source>
        <p>Unix:</p>
        <source>java -cp build/fop.jar:lib/avalon-framework.jar:lib/xml-apis.jar:
         lib/xercesImpl.jar:lib/xalan.jar
           org.apache.fop.fonts.apps.PFMReader pfm-file xml-file</source>
        <note>The classpath in the above example has been simplified for readibity.
 You will have to adjust the classpath to the names of the actual JAR files in the lib directory.
 avalon-framework.jar is necessary only for versions 0.20.5 or later.
 xml-apis.jar, xercesImpl.jar and xalan.jar are not necessary for JDK version 1.4 or later.</note>
        <note>The tool will construct some values (FontBBox, StemV and ItalicAngle) based on assumptions and calculations which are only an approximation to the real values.
 FontBBox and Italic Angle can be found in the human-readable part of the PFB file or in the AFM file.
 The PFMReader tool does not yet interpret PFB or AFM files, so if you want to be correct, you may have to adjust the values in the XML file manually.
 The constructed values however appear to have no visible influence.</note>
      </section>
      <section id="truetype-metrics">
        <title>TrueType Font Metrics</title>
        <p>FOP includes TTFReader, which reads the TTF file and generates an appropriate font metrics file for it.
 Use it in a similar manner to PFMReader.
 For example, to create such a metcis file in Windows from the TrueType font at c:\myfonts\cmr10.ttf:</p>
        <source>java -cp build\fop.jar;lib\avalon-framework.jar;lib\xml-apis.jar;
         lib\xercesImpl.jar;lib\xalan.jar
           org.apache.fop.fonts.apps.TTFReader
             C:\myfonts\cmr10.ttf ttfcm.xml
 </source>
    </section>
    <section id="truetype-collections">
      <title>TrueType collections</title>
      <p>
      TrueType collections (.ttc files) contains more than one
      font. To create metrics for a ttc file you must specify
      the font in the collection with the -ttcname option to
      TTFReader.
      </p>
      <p>
      To get a list of the fonts in a collection, just start the
      TTFReader as if it were a normal TrueType file (without
      the -ttcname option). It will then display all the font
      names and exit with an Exception...
      </p>
      <p>
      Example on generating metrics for a .ttc file:
      </p>
 <source>
 java -cp build\fop.jar;lib\avalon-framework.jar;lib\xml-apis.jar;
             C:\myfonts\cmr10.ttf ttfcm.xml</source>
      </section>
      <section id="truetype-collections-metrics">
        <title>TrueType Collections Font Metrics</title>
        <p>TrueType collections (.ttc files) contain more than one font.
 To create metrics files for these fonts, you must specify which font in the collection should be generated, by using the "-ttcname" option with the TTFReader.</p>
        <p>To get a list of the fonts in a collection, just start the TTFReader as if it were a normal TrueType file (without the -ttcname option).
 It will display all of the font names and exit with an Exception.</p>
        <p>Here is an example of generating a metrics file for a .ttc file:</p>
        <source>java -cp build\fop.jar;lib\avalon-framework.jar;lib\xml-apis.jar;
         lib\xercesImpl.jar;lib\xalan.jar
           org.apache.fop.fonts.apps.TTFReader -ttcname "MS Mincho"
             msmincho.ttc msminch.xml
 </source>
    </section>

      <section id="truetype-register">
        <title>Register the fonts within FOP</title>
        <p>
          Similiar to Type 1 fonts.
        </p>
 <source><![CDATA[<font metrics-file="cyberbit.xml" kerning="yes"
      embed-file="C:\WINNT\Fonts\Cyberbit.ttf">
  <font-triplet name="Cyberbit" style="normal" weight="normal">
             msmincho.ttc msminch.xml</source>
      </section>
      <section id="register">
        <title>Register Fonts with FOP</title>
        <p>You must tell FOP how to find and use the font metrics files by registering them in the <link href="configuration.html">FOP Configuration</link>. Add entries for your custom fonts, regardless of font type, to the configuration file in a manner similar to the following:</p>
        <source><![CDATA[<font metrics-file="FTL_____.xml" kerning="yes"
      embed-file="C:\myfonts\FTL_____.pfb">
  <font-triplet name="FrutigerLight" style="normal" weight="normal"/>
 </font>]]></source>
        <note>Review the documentation for <link href="configuration.html">FOP Configuration</link> for instructions on making the FOP configuration available to FOP when it runs. Otherwise, FOP has no way of finding your custom font information.</note>
        <ul>
          <li>Starting with FOP version 0.20.5 you can use URLs for the paths to the font files.
 Relative URLs are resolved relative to the fontBaseDir property (or baseDir) if available. See <link href="configuration.html">FOP: Configuration</link> for more information.</li>
          <li>The "kerning" and "embed-file" attributes are optional. Kerning is currently not used at all. If embedding is off, the output will position the text correctly (from the metrics file), but it will not be displayed or printed correctly unless the viewer has the applicable font available to their local system.</li>
          <li>When setting the embed-file attribute for Type 1 fonts, be sure to specify the PFB (actual font data), not PFM (font metrics) file that you used to generate the XML font metrics file.</li>
        </ul>
        <note>Cocoon users will need to setup the config, see FOPSerializer for more information.</note>
      </section>

  </section>
  <section id="embedding">
    <title>Embedding fonts</title>
    <p>
      Font embedding is enabled in the userconfig.xml file and controlled by the embed-file attribute.
      If you don't specify the embed-file attribute the font will not be embedded, but will only be referenced.
    </p>
    <p>
      When FOP embeds a font, it scrambles its fontname by inserting a prefix that ensures that the fontname will not match the fontname of an installed font.
 This is helpful with older versions of Acrobat Reader that preferred installed fonts over embedded fonts.
    </p>
    <p>
      When embedding PostScript fonts, the entire font is always embedded.
    </p>
    <p>
      When embedding TrueType fonts (ttf) or TrueType Collections (ttc), a new font, containing only the glyphs used, is created from the original font and embedded in the pdf.
      <section id="embedding">
        <title>Embedding</title>
        <note>The PostScript renderer does not yet support font embedding.</note>
        <note>The font is simply embedded into the PDF file, it is not converted.</note>
        <p>Font embedding is enabled in the userconfig.xml file and controlled by the embed-file attribute.
 If you don't specify the embed-file attribute the font will not be embedded, but will only be referenced.</p>
        <p>When FOP embeds a font, it scrambles its fontname by inserting a prefix that ensures that the fontname will not match the fontname of an installed font.
 This is helpful with older versions of Acrobat Reader that preferred installed fonts over embedded fonts.</p>
        <p>When embedding PostScript fonts, the entire font is always embedded.</p>
        <p>When embedding TrueType fonts (ttf) or TrueType Collections (ttc), a new font, containing only the glyphs used, is created from the original font and embedded in the pdf.
 Currently, this embedded font contains only the minimum data needed to be embedded in a pdf document, and does not contain any codepage information.
 The PDF document contains indexes to the glyphs in the font instead of to encoded characters.
 While the document will be displayed correctly, the net effect of this is that searching, indexing, and cut-and-paste will not work properly.
    </p>
    <p>
      One workaround for this behavior is to use the -ansi option when generating metrics with TTFReader.
 While the document will be displayed correctly, the net effect of this is that searching, indexing, and cut-and-paste will not work properly.</p>
        <p>One workaround for this behavior is to use the -ansi option when generating metrics with TTFReader.
 This will cause the whole font to be embedded in the pdf document.
 Characters will be WinAnsi encoded (as specified in the PDF spec), so you lose the ability to use characters from other character sets.
    </p>
  </section>
  <note>
    Be sure to start FOP with the option to find the config file ("-c conf/userconfig.xml" from the command line). Otherwise, it has no way of finding your custom font information.
  </note>
 </body>
 Characters will be WinAnsi encoded (as specified in the PDF spec), so you lose the ability to use characters from other character sets.</p>
      </section>
    </section>
  </body>
 </document>

--- a/src/documentation/content/xdocs/gethelp.xml
+++ b/src/documentation/content/xdocs/gethelp.xml
@@ -40,7 +40,7 @@ There is information about how to run FOP, how to embed it, how to add custom fo
    <section id="user-archive">
      <title>Review FOP User Mailing List Archive</title>
      <p>It is possible that your question has already been answered but has not yet found its way into the FAQ.
 Links to the FOP User mailing list archives are on the <link href="resources.html#mailing-lists-fop-user">Resources</link> page.
 Links to the FOP User mailing list archives are on the <link href="maillist.html#fop-user">Mailing List</link> page.
        </p>
    </section>
    <section id="existing-issue">
@@ -50,19 +50,7 @@ If so, please do not post a mailing list question or report another issue, as th
    </section>
    <section id="user-mailing-list">
      <title>Submit Question to FOP User Mailing List</title>
      <ul>
        <li>Subscription information is on the <link href="resources.html#mailing-lists-fop-user">Resources</link> page.</li>
        <li>Review <link href="resources.html#mailing-lists-general">General Mailing List Information</link> before submitting your question.</li>
        <li>State the version of FOP you're using.</li>
        <li>Include detailed error messages, if there are any.</li>
        <li>Provide FO code instead of XSLT snippets or DocBook source. 
 See <link href="running.html#running_xalan">Running Xalan</link> for how to produce FO from your XML+XSLT.</li>
        <li>Provide the shortest possible complete, <strong>self-contained</strong> FO code that demonstrates the problem.
 Include images only if they are an integral part of the question.
 Filter out any confidential material.</li>
        <li>Include only those portions of stack traces that will be helpful in finding the problem.</li>
        <li>Instead of attaching large PDF files or screen shots, include a small B&amp;W GIF, JPG or PNG of the area of interest.</li>
      </ul>
      <p>See <link href="maillist.html#fop-user">FOP User Mailing List</link> for details.</p>
    </section>
    <section id="enter-issue">
      <title>Enter an Issue Report</title>
--- a/src/documentation/content/xdocs/graphics.xml
+++ b/src/documentation/content/xdocs/graphics.xml
@@ -18,94 +18,39 @@
          <th>Support Thru</th>
        </tr>
        <tr>
          <td>BMP (Microsoft Windows Bitmap)</td>
          <td><link href="#bmp">BMP</link> (Microsoft Windows Bitmap)</td>
          <td>bitmap</td>
          <td><link href="#jimi">JIMI</link> or <link href="#jai">JAI</link></td>
        </tr>
        <tr>
          <td>CUR</td>
          <td>unknown</td>
          <td><link href="#jimi">JIMI</link></td>
          <td><link href="#native">FOP native</link></td>
        </tr>
        <tr>
          <td><link href="#eps">EPS</link> (Encapsulated PostScript)</td>
          <td>metafile (both bitmap and vector), probably most frequently used for vector drawings</td>
          <td><link href="#native">FOP native</link> (limited support)</td>
          <td><link href="#native">FOP native</link> (limited support, see restrictions below)</td>
        </tr>
        <tr>
          <td>GIF (Graphics Interchange Format)</td>
          <td>bitmap</td>
          <td><link href="#native">FOP native</link></td>
        </tr>
        <tr>
          <td>FPX</td>
          <td>unknown</td>
          <td><link href="#jai">JAI</link></td>
        </tr>
        <tr>
          <td>ICO (Sun Icon)</td>
          <td>bitmap</td>
          <td><link href="#jimi">JIMI</link></td>
        </tr>
        <tr>
          <td><link href="#jpeg">JPEG</link> (Joint Photographic Experts Group)</td>
          <td>bitmap</td>
          <td><link href="#native">FOP native</link></td>
        </tr>
        <tr>
          <td>PCX (PC Paintbrush)</td>
          <td>bitmap</td>
          <td><link href="#jimi">JIMI</link></td>
        </tr>
        <tr>
          <td>PICT (Macintosh PICT)</td>
          <td>metafile</td>
          <td><link href="#jimi">JIMI</link></td>
        </tr>
        <tr>
          <td>PNG (Portable Network Graphic)</td>
          <td><link href="#png">PNG</link> (Portable Network Graphic)</td>
          <td>bitmap</td>
          <td><link href="#jimi">JIMI</link> or <link href="#jai">JAI</link></td>
        </tr>
        <tr>
          <td>PNM (Portable aNyMap Utilities, part of the Portable Bitmap Utilies, aka pbmplus. PNM is a superset encompassing PBM or Portable Bitmap, PGM or Portable Grayscale, and PPM or Portable Pixmap.)</td>
          <td>bitmap</td>
          <td><link href="#jai">JAI</link></td>
        </tr>
        <tr>
          <td>PSD (Adobe Photoshop)</td>
          <td>bitmap</td>
          <td><link href="#jimi">JIMI</link></td>
        </tr>
        <tr>
          <td>RAS (Sunraster)</td>
          <td>bitmap</td>
          <td><link href="#jimi">JIMI</link></td>
        </tr>
        <tr>
          <td><link href="#svg">SVG</link> (Scalable Vector Graphics)</td>
          <td>vector (with embedded bitmaps)</td>
          <td><link href="#batik">Batik</link></td>
        </tr>
        <tr>
          <td>TGA (Targa)</td>
          <td><link href="#tiff">TIFF</link> (Tag Image Format File)</td>
          <td>bitmap</td>
          <td><link href="#jimi">JIMI</link></td>
        </tr>
        <tr>
          <td>TIFF (Tag Image Format File)</td>
          <td>bitmap</td>
          <td><link href="#jimi">JIMI</link> or <link href="#jai">JAI</link></td>
        </tr>
        <tr>
          <td>XBM (X BitMap)</td>
          <td>bitmap</td>
          <td><link href="#jimi">JIMI</link></td>
        </tr>
        <tr>
          <td>XPM (X PixMap)</td>
          <td>bitmap</td>
          <td><link href="#jimi">JIMI</link></td>
          <td><link href="#native">FOP native</link> or <link href="#jai">JAI</link>, depending on the subformat. See <link href="#tiff">TIFF</link> for more details.(JIMI also supports TIFF, but this has not been implemented within FOP).</td>
        </tr>
      </table>
    </section>
@@ -121,14 +66,15 @@
        <title>JIMI</title>
        <p>
          Because of licensing issues, the JIMI image library is not included in the FOP distribution. First, <fork href="http://java.sun.com/products/jimi">download</fork> and install it.
 Then, copy the file "JimiProClasses.zip" from the archive to xml-fop/lib/jimi-1.0.jar. Please note that FOP binary distributions are compiled with JIMI support, so there is no need for you to build FOP to add the support. If jimi-1.0.jar is installed in the right place, it will automatically be used by FOP, otherwise it will not.
 Then, copy the file "JimiProClasses.zip" from the archive to {fop-install-dir}/lib/jimi-1.0.jar. Please note that FOP binary distributions are compiled with JIMI support, so there is no need for you to build FOP to add the support. If jimi-1.0.jar is installed in the right place, it will automatically be used by FOP, otherwise it will not.
        </p>
      </section>
      <section id="jai">
        <title>JAI</title>
        <title>JAI (Java Advanced Imaging API)</title>
        <warning>JAI support is available for Release 0.20.5 and later. The comments in this section do not apply to releases earlier than 0.20.5.</warning>
        <p>
          FOP has been compiled with JAI support, but JAI is not included in the FOP distribution.
 To use it, simply install <link href="http://java.sun.com/products/java-media/jai">JAI</link>.
 To use it, install <link href="http://java.sun.com/products/java-media/jai">JAI</link>, then copy the jai_core.jar and the jai_codec.jar files to {fop-install-dir}/lib.
 JAI is much faster than JIMI, but is not available for all platforms. See <link href="http://java.sun.com/products/java-media/jai/forDevelopers/jaifaq.html#platforms">What platforms are supported?</link> on the JAI FAQ page for more details.
        </p>
      </section>
@@ -149,19 +95,41 @@ If you run a server without X, or if you can't connect to the X server due to se
        </ul>
      </section>
    </section>
    <section id="bmp">
      <title>BMP</title>
      <p>FOP native support for BMP images is limited to the RGB color-space.</p>
    </section>
    <section id="eps">
      <title>EPS</title>
      <p>FOP provides support for two output targets:</p>
      <ul>
        <li>PostScript (full support).</li>
        <li>PDF (partial support). FOP embeds the EPS file into the PDF, but currently does not do so completely correctly. PostScript devices (including ghostscript) will render the EPS correctly, but Acrobat Reader will not currently display it.</li>
        <li>
          PDF (partial support). Due to the lack of a built-in PostScript interpreter, FOP 
          can only embed the EPS file into the PDF. Acrobat Reader will not currently display 
          the EPS (it doesn't have a PostScript interpreter, either) but it will be shown 
          correctly when you print the PDF on a PostScript-capable printer. PostScript devices 
          (including GhostScript) will render the EPS correctly.
        </li>
      </ul>
      <p>
        Other output targets can't be supported at the moment because
        FOP lacks a PostScript interpreter.
      </p>
    </section>
    <section id="jpeg">
      <title>JPEG</title>
      <p>Not all variants of JPEG are supported, especially those containing unusual color lookup tables and color profiles. If you have trouble with a JPEG image in FOP, try opening it with an image processing program (such as Photoshop or Gimp) and then saving it. Specifying 24-bit color output may also help.
      <p>FOP native support of JPEG does not include all variants, especially those containing unusual color lookup tables and color profiles.
 If you have trouble with a JPEG image in FOP, try opening it with an image processing program (such as Photoshop or Gimp) and then saving it.
 Specifying 24-bit color output may also help.
 For the PDF and PostScript renderers most JPEG images can be passed through without decompression.
 User reports indicate that grayscale, RGB, and CMYK color-spaces are all rendered properly.
      </p>
    </section>
    <section id="png">
      <title>PNG</title>
      <p>If using JAI for PNG support, only RGB and RGBA color-spaces are supported for FOP rendering.</p>
    </section>
    <section id="svg">
      <title>SVG</title>
      <section id="svg-intro">
@@ -214,23 +182,10 @@ If the text is inserted into the PDF using the inbuilt text commands
 for PDF it will use a single character.
        </p>
        <p>
 It is possible to make sure that all text is drawn into PDF using the
 PDF text commands (instead of the graphical shapes), by adding the following to the user config:
        </p>
        <source><![CDATA[<entry>
  <key>strokeSVGText</key>
  <value>false</value>
 </entry>]]></source>
        <p>In a servlet environment, you can set it directly:</p>
        <source>org.apache.fop.configuration.Configuration.put("strokeSVGText", Boolean.FALSE);</source>
        <p>For information on using a configuration file in a servlet, see the <link href="faq.html#usercfg">FAQ</link> on that topic.</p>
        <p>Note that this configuration setting works only for the PDF renderer.</p>
        <p>
 The drawback to forcing text to be rendered as text is that it will be confined to text that is
 possible for PDF fonts (including embedded fonts) and implemented with
 this workaround. The fonts available are the standard pdf fonts and any
 fonts that you have embedded using FOP. The font sizes will be rounded
 to an integer value. In future this will be improved.
 For PDF output, there is a <link href="configuration.html#svg-strokeSVGText">configuration option to force SVG text to be rendered as text</link>.
 The drawback to this approach is that it is effective only for available fonts (including embedded fonts).
 Font sizes are rounded to the next integer point size.
 This will be improved in the future.
        </p>
        <p>Note that because SVG text can be rendered as either text or a vector graphic, you may need to consider settings in your viewer for both.
 The Acrobat viewer has both "smooth line art" and "smooth text" settings that may need to be set for SVG images to be displayed nicely on your screen (see Edit / Preferences / Display).
@@ -276,6 +231,16 @@ into a raster graphic are not drawn properly in PDF. The image is opaque.
        </ul>
      </section>
    </section>
    <section id="tiff">
      <title>TIFF</title>
      <p>FOP-native TIFF support is limited to PDF and PostScript output only. Also, according to user reports, FOP's native support for TIFF is limited to images with the following characteristics (all must be true for successful rendering):</p>
      <ul>
        <li>single channel images (i.e., bi-level and grayscale only)</li>
        <li>uncompressed images, or images using CCITT T.4, CCITT T.6, or JPEG compression</li>
        <li>images using white-is-zero encoding in the TIFF PhotometricInterpretation tag</li>
      </ul>
      <p><em>JAI:</em> Supports RGB and RGBA only for FOP rendering.</p>
    </section>
    <section id="resolution">
      <title>Graphics Resolution</title>
      <p>Some bitmapped image file formats store a dots-per-inch (dpi) or other resolution value. Since PDF and most output formats do not have a concept of resolution, but only of absolute image units (i.e. pixels) FOP ignores the resolution values as well. Instead, FOP uses the dimensions of the image as specified in the fo:external-graphic element to render the image:</p>
@@ -287,5 +252,20 @@ into a raster graphic are not drawn properly in PDF. The image is opaque.
      <p>If you need a higher apparent output resolution for bitmapped images, first make sure that at least one dimension of the image is defined in your XSL-FO input. Apart from that, resolution problems are in the image file itself, and must be corrected there: use or create a higher-resolution image file.</p>
      <note>The explanation above describes only the basic default behavior. There are other attributes of the fo:external-graphic element that can affect the behavior described above.</note>
    </section>
    <section id="caching">
      <title>Image caching</title>
      <p>
        FOP caches images between runs. The URL is used as a key to identify images which means that when
        a particular URL appears again, the image is taken from the cache. If you have a servlet that
        generates a different image each time it is called with the same URL you need to use a constantly 
        changing dummy parameter on the URL to avoid caching.
      </p>
      <p>
        Currently, the images are not automatically released when an OutOfMemoryError is imminent. The
        image cache can grow to a considerable size over time when a lot of different URLs are in use.
        Starting with version 0.20.5 you can call <code>org.apache.fop.image.FopImageFactory.resetCache()</code>
        to manually empty the cache. Image caching will be improved as part of our redesign effort.
      </p>
    </section>
  </body>
 </document>
--- a/src/documentation/content/xdocs/index.xml
+++ b/src/documentation/content/xdocs/index.xml
@@ -55,7 +55,7 @@ The most common method is to convert semantic XML to XSL-FO, using an XSLT trans
   <p>The FOP layout system is currently being rewritten to better support the XSL-FO standard.</p>
  </section>
  <note>
    The PDF files on this site are created using the latest development version of FOP.
    The PDF files on this site are created using FOP.
  </note>
  </body>
 </document>
--- a/src/documentation/content/xdocs/logocontest.xml
+++ b/src/documentation/content/xdocs/logocontest.xml
@@ -3,19 +3,19 @@
    "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/schema/dtd/document-v11.dtd">
 <document id="logocontest">
 	<header>
 		<title>Logo contest</title>
 		<title>Logo Contest</title>
 	</header>
 	<body>
 		<p>FOP needs new logo and FOP Team decided to hold an open logo contest. We invite all members of 
 		<p>FOP needs a new logo and so we've decided to hold an open logo contest. We invite all members of 
 		the FOP community as well as any other interested parties to participate as contestants or by expressing 
 		your opinion through voting. We have set up <link href="http://vote.sparklit.com/web_poll.spark/714566">Web Poll</link> where you can see
 		contestant logos and vote.</p>
 		contestant logos and vote your favorite.</p>
 		<section>
 			<title>The rules</title>
 			<p>The rules are simple:</p>
 			<ul>
 				<li>Everyone can participate as contestant</li>
 				<li>Everyone can vote, but only FOP Team picks out the winner</li>
 				<li>Everyone can participate as a contestant</li>
 				<li>Everyone can vote, but only FOP Team will choose the winner</li>
 				<li>No reward except for pride</li>
 				<li>The winner image is donated to Apache, but the authorship is preserved</li>
 				<li>The final result should be in SVG format</li>
@@ -25,14 +25,14 @@
 		</section>
 		<section>
 			<title>How to participate</title>
 			<p>Submit your image or link to it to <link href="http://xml.apache.org/fop/resources.html#xpointer(/document[1]/body[1]/section[1]/section[1])">fop-user</link> mail list.
 			 Vote for a logo you like the most at FOP logo contest <link href="http://vote.sparklit.com/web_poll.spark/714566">Web Poll</link>.
 			<p>Submit your image or link to it at the <link href="maillist.html#fop-user">fop-user</link> mail list.
 			 Vote for the logo you like the most at FOP logo contest <link href="http://vote.sparklit.com/web_poll.spark/714566">Web Poll</link>.
 			</p>
 		</section>
 		<section>
 			<title>Credits</title>
 			<p>We would like to thank <link href="http://ant.apache.org">Ant</link> and 
 			<link href="http://jakarta.apache.org/poi/index.html">POI</link> teams for ideas how to make a logo contest.</p>
 			<p>We would like to thank the <link href="http://ant.apache.org">Ant</link> and 
 			<link href="http://jakarta.apache.org/poi/index.html">POI</link> teams for their ideas on how to make this logo contest.</p>
 		</section>
 	</body>
 </document>
--- a/src/documentation/content/xdocs/news.xml
+++ b/src/documentation/content/xdocs/news.xml
@@ -7,6 +7,17 @@
    <title>News</title>
  </header>
  <body>
    <section>
      <title>29 June 2003 - New Committer</title>
      <p>Welcome Glen Mazza!</p>
    </section>
    <section>
      <title>23 May 2003 - FOP 0.20.5 Release Candidate 3 available</title>
      <p>
      See the full text of the <link
      href="http://archives.apache.org/eyebrowse/ReadMsg?listName=fop-dev@xml.apache.org&amp;msgNo=5429">announcement</link>.
      </p>
    </section>
    <section>
      <title>18 February 2003 - FOP 0.20.5 Release Candidate 2 available</title>
      <p>
@@ -21,10 +32,10 @@
      </p>
    </section>
    <section>
 	    <title>28 January 2003 - FOP logo contest</title>
 		<p>We are looking for a new logo. FOP <link href="logocontest.html">logo
           contest</link> is started!</p>
 	</section>
      <title>28 January 2003 - FOP logo contest</title>
      <p>We are looking for a new logo. FOP <link href="logocontest.html">logo
      contest</link> is started!</p>
    </section>
    <section>
      <title>23 December 2002 - Official FOP Wiki</title>
      <p>
--- a/src/documentation/content/xdocs/output.xml
+++ b/src/documentation/content/xdocs/output.xml
@@ -277,19 +277,15 @@ Adobe Framemaker. This is currently not fully implemented.
 <section id="txt">
  <title>TXT</title>
    <p>
 Text as you could imagine does not work very well. It is an output format
 that you should expect bad results. The main purpose of this is to get
 a quick and dirty view of the document and the text inside it.
    </p>
    <p>
 The TXTRenderer is a FOP renderer that produces plain ASCII text output
 The text renderer produces plain ASCII text output
 that attempts to match the output of the PDFRenderer as closely as
 possible. This was originally developed to accommodate an archive system
 that could only accept plain text files. Of course when limited to plain
 fixed pitch text the output does not always look very good.
 that could only accept plain text files, and is primarily useful for getting
 a quick-and-dirty view of the document text. The renderer is very limited,
 so do not be surprised if it gives unsatisfactory results.
    </p>
    <p>
 The TXTRenderer works with a fixed size page buffer. The size of this
 The Text renderer works with a fixed size page buffer. The size of this
 buffer is controlled with the textCPI and textLPI public variables.
 The textCPI is the effective horizontal characters per inch to use.
 The textLPI is the vertical lines per inch to use. From these values
@@ -298,6 +294,13 @@ The formatting objects to be rendered are then mapped to this grid.
 Graphic elements (lines, borders, etc) are assigned a lower priority
 than text, so text will overwrite any graphic element representations.
    </p>
    <p>Because FOP lays the text onto a grid during layout, there are frequently extra or missing spaces between characters and lines, which is generally unsatisfactory.
 Users have reported that the optimal settings to avoid such spacing problems are:</p>
    <ul>
      <li>font-family="Courier"</li>
      <li>font-size="7.3pt"</li>
      <li>line-height="10.5pt"</li>
    </ul>
 </section>

    </body>
--- a/src/documentation/content/xdocs/pdfencryption.xml
+++ b/src/documentation/content/xdocs/pdfencryption.xml
@@ -7,20 +7,22 @@
    <title>PDF encryption.</title>
    <authors>
      <person name="J.Pietschmann" email="pietsch@apache.org"/>
      <person name="Jeremias Märki" email="jeremias@apache.org"/>
    </authors>
  </header>
  <body>
    <section>
      <title>Overview</title>
      <warning>PDF Encryption is available in Release 0.20.5 and later. The comments on this page do not apply to releases earlier than 0.20.5.</warning>
      <p>
        FOP supports encryption of PDF output, thanks to Patrick
        C. Lankswert. This feature is commonly used to prevent unauthorized
        viewing, printing, editing and copying text from the document
        annotations. It is also possible to ask the user for a password in order
        to view the contents. Note that there already exist third party
        applications which can decrypt an encrypted PDF without effort and allow
        the aforementioned operations, therefore the degree of protection is
        limited.
        C. Lankswert. This feature is commonly used to prevent
        unauthorized viewing, printing, editing, copying text from the
        document and doing annotations. It is also possible to ask the
        user for a password in order to view the contents. Note that
        there already exist third party applications which can decrypt
        an encrypted PDF without effort and allow the aforementioned
        operations, therefore the degree of protection is limited.
      </p>
      <p>
        For further information about features and restrictions regarding PDF
@@ -29,19 +31,21 @@
      </p>
    </section>
    <section>
      <title>Usage</title>
      <title>Usage (command line)</title>
      <p>
        Encryption is enabled by supplying any of the encryption related
        options.
      </p>
      <p>
        An owner password with the <code>-o</code> option. This password is
        actually used as encryption key. Usually it is also used by most tools
        to disregard any restriction imposed on the PDF document.
        An owner password is set with the <code>-o</code> option. This
        password is actually used as encryption key. Many tools for
        PDF processing ask for this password to disregard any
        restriction imposed on the PDF document.
      </p>
      <p>
        If no owner password has been supplied but FOP was asked to apply some
        restrictions, a random password is used.
        restrictions, a random password is used. In this case it is obviously
        impossiible to disregard restrictions in PDF processing tools.
      </p>
      <p>
        A user password, supplied with the <code>-u</code> option, will
@@ -56,16 +60,83 @@
        text, editing in Adobe Acrobat and making annotations, respectively.
      </p>
    </section>
    <section>
      <title>Usage (embedded)</title>
      <p>
        When FOP is embedded in another Java application you need to set an 
        options map on the renderer. These are the supported options:
      </p>
      <table>
        <tr>
          <th>Option</th>
          <th>Description</th>
          <th>Values</th>
          <th>Default</th>
        </tr>
        <tr>
          <td>ownerPassword</td>
          <td>The owner password</td>
          <td>String</td>
          <td/>
        </tr>
        <tr>
          <td>userPassword</td>
          <td>The user password</td>
          <td>String</td>
          <td/>
        </tr>
        <tr>
          <td>allowPrint</td>
          <td>Allows/disallows printing of the PDF</td>
          <td>"TRUE" or "FALSE"</td>
          <td>"TRUE"</td>
        </tr>
        <tr>
          <td>allowCopyContent</td>
          <td>Allows/disallows copy/paste of content</td>
          <td>"TRUE" or "FALSE"</td>
          <td>"TRUE"</td>
        </tr>
        <tr>
          <td>allowEditContent</td>
          <td>Allows/disallows editing of content</td>
          <td>"TRUE" or "FALSE"</td>
          <td>"TRUE"</td>
        </tr>
        <tr>
          <td>allowEditAnnotations</td>
          <td>Allows/disallows editing of annotations</td>
          <td>"TRUE" or "FALSE"</td>
          <td>"TRUE"</td>
        </tr>
      </table>
      <note>
        Encryption is enabled as soon as one of these options is set.
      </note>
      <p>
        An example to enable PDF encryption in Java code:
      </p>
      <source><![CDATA[
 Driver driver = new Driver();
 driver.setRenderer(Driver.RENDER_PDF);
 Map rendererOptions = new java.util.HashMap();
 rendererOptions.put("ownerPassword", "mypassword");
 rendererOptions.put("allowCopyContent", "FALSE");
 rendererOptions.put("allowEditContent", "FALSE");
 rendererOptions.put("allowPrint", "FALSE");
 driver.getRenderer().setOptions(rendererOptions);
 driver.setOutputStream(...]]></source>
    </section>
    <section>
      <title>Environment</title>
      <p>
        In order to use PDF encryption, FOP has to be compiled with cryptography
        support. Currently, only <link
        In order to use PDF encryption, FOP has to be compiled with
        cryptography support. Currently, only <link
        href="http://java.sun.com/j2se/1.4/docs/guide/security/jce/JCERefGuide.html">JCE</link>
        is supported. JCE is part of JDK 1.4. For earlier JDKs, it can be
        installed separately. The build process automatically senses JCE
        presence and installs PDF support if possible, otherwise, a stub is
        compiled in.
        is supported. JCE is part of JDK 1.4. For earlier JDKs, it can
        be installed separately. The build process automatically
        detects JCE presence and installs PDF encryption support if
        possible, otherwise a stub is compiled in.
      </p>
      <p>
        Cryptography support must also be present at run time. In particular, a
@@ -75,7 +146,7 @@
      </p>
      <source>"Cannot find any provider supporting RC4"</source>
      <p>
        then you don't have the needed support.
        then you don't have the needed infrastructure.
      </p>
      <p>
        There are several commercial and a few Open Source packages which
@@ -112,6 +183,10 @@
          providers. For JDK 1.4 this is detailed on <link href="http://java.sun.com/j2se/1.4/docs/guide/security/jce/JCERefGuide.html#InstallProvider">Sun's web site</link>.
        </li>
      </ol>
      <p>
        If you have any experience with Mozilla JSS or any other
        cryptography provider, please post it to the fop-user list.
      </p>
    </section>
  </body>
 </document>
--- a/src/documentation/content/xdocs/relnotes.xml
+++ b/src/documentation/content/xdocs/relnotes.xml
@@ -14,9 +14,11 @@
  <p>Important changes since the last release (0.20.4):</p>
  <ul>
    <li>Some hyphenation patterns (cs, da, de, de_DR, el, en, en_US, fr, nl,
        no, pt, ru, sk, tr) have been removed due to licensing reasons
        (en_GB hyphenation has been renamed to en).
        We hope to resolve this issue before the final release.
      no, sk, tr) have been removed due to licensing reasons
      (en_GB hyphenation has been renamed to en).
      We're still working on this issue
      (see <link href="http://nagoya.apache.org/wiki/apachewiki.cgi?FOPAudits/March2003">
      Wiki</link> for details).
    </li>
    <li>Documentation is now built with <link href="http://xml.apache.org/forrest/">
        Forrest</link> (version 0.4). You need to install Forrest if you want build the docs
@@ -39,6 +41,18 @@
    <li>Links in PDF won't generate multiple link rectangles anymore. If this causes
        a problem you can set the system property "links.merge" to "no".
    </li>
    <li>FOP has been compiled with cryptography support. See <link href="pdfencryption.html">
      PDF encryption</link> for details about installation and usage.
    </li>
    <li>The behaviour of leader has changed. See
      <link href="http://nagoya.apache.org/bugzilla/show_bug.cgi?id=19341">bug #19341</link>,
      <link href="http://nagoya.apache.org/bugzilla/show_bug.cgi?id=19465">bug #19465</link>
      and <code>leader.fo</code> (examples).
    </li>
    <li>
      For a more detailed list of changes, see the CHANGES file in the root of the
      FOP distribution.
    </li>
  </ul>

 </section>
--- a/src/documentation/content/xdocs/resources.xml
+++ b/src/documentation/content/xdocs/resources.xml
@@ -4,67 +4,10 @@
 <!-- FOP Relevant Specifications and links -->
 <document>
  <header>
    <title>Resources</title>
    <title>FOP: Other Resources</title>
    <subtitle>Resources useful for developing and using FOP</subtitle>
  </header>
  <body>
    <section id="mailing-lists">
      <title>Mailing Lists and Archives</title>
      <section id="mailing-lists-general">
        <title>General Information</title>
        <p>Before posting questions to any list, review "<jump href="http://www.catb.org/~esr/faqs/smart-questions.html">How To Ask Questions The Smart Way</jump>".</p>
        <p>Be sure to set your email client to send plain text email messages to any mailing lists.
 Please do <em>not</em> send html or rtf email, as they do not work well with the archive engines.
 If you are using Microsoft Outlook, this setting can be found at the "Mail Format" tab of the Tools/Options menu.</p>
        <p>For help in understanding email acronyms, see the <jump href="http://www.lingo2word.com/lists/acronym_listA.html">Lingo2Word Acronym List</jump>, or the <jump href="http://www.keno.org/web_design/acronyms.htm">Keno Internet Services Internet Glossary</jump>.</p>
      </section>
      <section id="mailing-lists-fop-user">
        <title>FOP User Mailing List</title>
        <p>Use this forum to discuss topics of interest to FOP users.
 After reviewing the FOP documentation and searching the archives (see below), use this forum to ask questions about how to download, install, configure, and use FOP.
 Please do <em>not</em> use this forum for general XSL-FO, XSLT, or PDF questions.</p>
        <ul>
          <li>To review the archives, you have several options:
            <ul>
              <li>The <jump href="http://marc.theaimsgroup.com/?l=fop-user&amp;r=1&amp;w=2">Mailing list ARChives </jump> (MARC) at the AIMS group (search).</li>
              <li>The <jump href="http://nagoya.apache.org/eyebrowse/SummarizeList?listName=fop-user@xml.apache.org">Apache Eyebrowse</jump> archive (search, list by date, author, subject, or thread).</li>
              <li>The <link href="http://xml.apache.org/mail/fop-user">Apache Mailing List archive</link> (gzip files).</li>
            </ul>
          </li>
          <li>Before posting questions to any list, see "<link href="#mailing-lists-general">General Information</link>".</li>
          <li>See <link href="http://xml.apache.org/mail.html#fop-user">Apache XML Mailing Lists</link> for detailed subscription information.</li>
          <li>To subscribe (digest only): Send email to <link href="mailto:fop-user-digest-subscribe@xml.apache.org">fop-user-digest-subscribe@xml.apache.org</link>.</li>
          <li>To subscribe fully: Send email to <link href="mailto:fop-user-subscribe@xml.apache.org">fop-user-subscribe@xml.apache.org</link>.</li>
          <li>For standard help: Send email to <link href="mailto:fop-user-help@xml.apache.org">fop-user-help@xml.apache.org</link>.</li>
          <li>To unsubscribe: Send email to <link href="mailto:fop-user-unsubscribe@xml.apache.org">fop-user-unsubscribe@xml.apache.org</link>.</li>
        </ul>
      </section>
      <section id="mailing-lists-w3c-xslfo">
        <title>XSL-FO Mailing List (at W3C)</title>
        <p>Use this forum to ask general XSL-FO questions.</p>
        <ul>
          <li>To review the archive: <jump href="http://lists.w3.org/Archives/Public/www-xsl-fo/">W3C XSL-FO Archives</jump>.</li>
          <li>Before posting questions to any list, see "<link href="#mailing-lists-general">General Information</link>".</li>
          <li>Subscription administration information can be found at <jump href="http://www.w3.org/Mail/Request">W3C Mailing List Administrativia</jump>.
 After reviewing the instructions there, send your subscribe or unsubscribe request to <link href="mailto:www-xsl-fo-request@w3.org">www-xsl-fo-request@w3.org</link>.</li>
        </ul>
      </section>
      <section id="mailing-lists-yahoogroups-xslfo">
        <title>XSL-FO Mailing List (at YahooGroups)</title>
        <p>Use this forum to ask general XSL-FO questions.</p>
        <ul>
          <li>Before posting questions to any list, see "<link href="#mailing-lists-general">General Information</link>".</li>
          <li>The home page for this groups is <jump href="http://groups.yahoo.com/group/XSL-FO">XSL-FO - discussion of XSL Formatting Objects</jump>.</li>
        </ul>
      </section>
      <section id="mailing-lists-xslt-mulberry">
        <title>XSLT List (Mulberry Tech)</title>
        <ul>
          <li>Before posting questions to any list, see "<link href="#mailing-lists-general">General Information</link>".</li>
          <li>Information for using and subscribing can be found at <jump href="http://www.mulberrytech.com/xsl/xsl-list">XSL-List -- Open Forum on XSL</jump>.</li>
        </ul>
      </section>
    </section>
    <section id="specs">
      <title>Specifications</title>
      <section id="specs-xslfo">
@@ -95,11 +38,17 @@ After reviewing the instructions there, send your subscribe or unsubscribe reque
          <li><jump href="http://java.sun.com/j2se/1.3/docs/api/index.html">Java JDK 1.3 Documentation</jump></li>
        </ul>
      </section>
      <section id="specs-pdf">
        <title>PDF</title>
        <ul>
          <li><jump href="http://partners.adobe.com/asn/developer/acrosdk/docs/filefmtspecs/PDFReference.pdf">Portable Document Format (PDF) 1.4 Reference Manual</jump>
         </li>
        </ul>
      </section>
      <section id="specs-other">
        <title>Other</title>
        <ul>
          <li><jump href="http://www.w3.org/TR/SVG/">Supported SVG Recommendation (04 September 2001)</jump></li>
          <li><jump href="http://partners.adobe.com/asn/developer/acrosdk/docs/filefmtspecs/PDFReference.pdf">Portable Document Format (PDF) 1.4 Reference Manual</jump></li>
        </ul>
      </section>
    </section>
@@ -125,7 +74,7 @@ After reviewing the instructions there, send your subscribe or unsubscribe reque
          <li>[book] <jump href="http://wrox.com/books/1861005067.htm">XSLT Programmer's Reference</jump>, by Michael H. Kay, Wrox Press, ISBN 1-861-00506-7.</li>
          <li>[book] <jump href="http://www.oreilly.com/catalog/xslt">XSLT</jump>, by Doug Tidwell, O'Reilly &amp; Associates, 2001, ISBN 0-596-00053-7.</li>
          <li>[book] <jump href="http://www.oreilly.com/catalog/xsltckbk">XSLT Cookbook</jump>, by Sal Mangano, O'Reilly &amp; Associates, 2002, ISBN 0-596-00372-2.</li>
          <li>[article] <jump href="http://www.dpawson.co.uk/xsl/xslfaq.html">Dave Pawson's XSLT FAQ</jump>.</li>
          <li>[article] <jump href="http://www.dpawson.co.uk/xsl/xslfaq.html">Dave Pawson's XSL FAQ</jump>.</li>
         <li>[book] <jump href="http://www.oreilly.com/catalog/xpathpointer">XPath and XPointer: Locating Content in XML Documents</jump>, by John E. Simpson, O'Reilly &amp; Associates, 2002, ISBN 0-596-00291-2.</li>
          <li>[book] <jump href="http://www.wiley.com/cda/product/0,,0471416207,00.html">XSL Essentials</jump>, by Michael Fitzgerald, John Wiley &amp; Sons, 2001, ISBN 0-471-41620-7.</li>
          <li>[book] <jump href="http://www.oreilly.com/catalog/javaxslt">Java and XSLT</jump>, by Eric M. Burke, O'Reilly &amp; Associates, 2001, ISBN 0-596-00143-6.</li>
@@ -145,21 +94,63 @@ After reviewing the instructions there, send your subscribe or unsubscribe reque
          <li>[online resource] A great number of Java-related books and articles can be found at the <jump href="http://java.oreilly.com">O'Reilly Java Site</jump>.</li>
        </ul>
      </section>
      <section id="documents-pdf">
        <title>PDF</title>
        <ul>
          <li>[online resource] Links to the various PDF file format specifications and numerous other documents can be found at Adobe Solutions Network, Acrobat Resources, <jump href="http://partners.adobe.com/asn/acrobat/docs.jsp#filefmtspecs">Acrobat 5.0 SDK Documentation</jump>.</li>
          <li>[online resource] A list of PDF technical resources can be found at Adobe Solutions Network, Acrobat Resources, <jump href="http://partners.adobe.com/asn/acrobat/technotes.jsp">Acrobat/PDF Technical Notes</jump></li>
          <li>[online resource] A list of Acrobat and PDF developer resources can be found at Adobe Solutions Network, Acrobat Resources, <jump href="http://partners.adobe.com/asn/acrobat">Resources for Developers</jump>.</li>
        </ul>
      </section>
      <section id="documents-ps">
        <title>PostScript</title>
        <ul>
          <li>[online resource] A list of PostScript-related technical resources can be found at Adobe Solutions Network, <jump href="http://partners.adobe.com/asn/tech/ps/technotes.jsp">PostScript Language Technical Notes</jump></li>
          <li>[online resource] Additional PostScript-related developer resources can be found at Adobe Solutions Network, <jump href="http://partners.adobe.com/asn/tech/ps/index.jsp">PostScript SDK Archive</jump>.</li>
        </ul>
      </section>
    </section>
    <section id="products">
      <title>Related/Useful Products</title>
      <ul>
        <li>PJ is an open source product that can be used to modify PDF documents:
 <jump href="http://www.etymon.com/pj/index.html">http://www.etymon.com/pj/index.html</jump></li>
        <li>iText is a library that can edit PDF files, it is possible to do
 post processing of the generated PDF files: <jump href="http://www.lowagie.com/iText/">http://www.lowagie.com/iText/</jump>.</li>
        <li>html2fo is a converter from html to xsl:fo: <jump href="http://html2fo.sourceforge.net/">http://html2fo.sourceforge.net/</jump>.</li>
        <li>FOA is a XSL-FO Authoring tool: <jump href="http://foa.sourceforge.net/">http://foa.sourceforge.net/</jump>.</li>
        <li>TIFFRenderer is a renderer for outputting multi-page TIFF: <jump href="http://www.tkachenko.com/fop/tiffrenderer.html">http://www.tkachenko.com/fop/tiffrenderer.html</jump>.</li>
        <li>AFP Renderer / Batch Assembler for FOP: <jump href="http://mypage.bluewin.ch/huanderegg/">http://mypage.bluewin.ch/huanderegg/</jump>.</li>
        <li>The <jump href="http://mogwai.sourceforge.net">Mogwai Project</jump> includes a renderer for FOP that generates output for Okidata dot matrix printers.</li>
        <li> [software] <jump href="http://www.vbxml.com/xpathvisualizer">The XPath Visualizer</jump>. Web site says: "This is a full blown Visual XPath Interpreter for the evaluation of any XPath expression and visual presentation of the resulting nodeset or scalar value."</li>
      </ul>
      <section id="products-fop-add-ons">
        <title>FOP add-ons</title>
        <ul>
          <li>[software] TIFFRenderer is a renderer for outputting multi-page TIFF: <jump href="http://www.tkachenko.com/fop/tiffrenderer.html">http://www.tkachenko.com/fop/tiffrenderer.html</jump> (MPL)</li>
          <li>[software] AFP Renderer / Batch Assembler for FOP: <jump href="http://mypage.bluewin.ch/huanderegg/">http://mypage.bluewin.ch/huanderegg/</jump> (open source, license unclear)</li>
          <li>[software] The <jump href="http://mogwai.sourceforge.net">Mogwai Project</jump> includes a renderer for FOP that generates output for Okidata dot matrix printers (GPL).</li>
          <li>[software] <jump href="http://www.krysalis.org/barcode">Krysalis Barcode</jump> is a barcode generator which can be used with FOP (Apache-style license).</li>
        </ul>        
      </section>
      <section id="products-pdf">
        <title>PDF post-processors</title>
        <ul>
          <li>[software] <jump href="http://www.lowagie.com/iText">iText</jump> (MPL and LGPL)</li>
          <li>[software] <jump href="http://www.etymon.com/pjc">PJ Classic</jump> by Etymon (GPL)</li>
          <li>[software] <jump href="http://www.etymon.com/pjx">PJ Professional</jump> by Etymon (commercial)</li>
        </ul>
      </section>
      <section id="products-editors">
        <title>XSL-FO editors</title>
        <ul>
          <li>[software] <jump href="http://foa.sourceforge.net/">FOA (Formatting Objects Authoring)</jump> (MPL)</li>
          <li>[software] <jump href="http://www.scruffyware.com/products/foeditor/">FOEditor</jump> by Scruffy Software (Shareware)</li>
          <li>[software] <jump href="http://www.scriptura-xsl.com">Scriptura</jump> by Inventive Designers (commercial)</li>
          <li>[software] <jump href="http://www.xslfast.com">XSLfast</jump> by jCatalog Software AG (commercial)</li>
          <li>[software] <jump href="http://www.rubico.com/styler">XML Report Styler</jump> by Rubico (commercial)</li>
        </ul>
      </section>
      <section id="products-other">
        <title>Other products</title>
        <ul>
          <li>[software] <jump href="http://html2fo.sourceforge.net/">html2fo</jump> is a converter from HTML to XSL-FO (GPL).</li>
          <li>[software] <jump href="http://wh2fo.sourceforge.net/">wh2fo</jump> is a converter from Word HTML to XSL-FO (MPL).</li>
          <li>[software] <jump href="http://www.rtf2fo.com">RTF2FO</jump> is a converter from RTF to XSL-FO by Novosoft (commercial).</li>
          <li> [software] <jump href="http://www.vbxml.com/xpathvisualizer">The XPath Visualizer</jump>.
 Web site says: "This is a full blown Visual XPath Interpreter for the evaluation of any XPath expression and visual presentation of the resulting nodeset or scalar value."
 Requires Internet Explorer 5+.
 (freeware)</li>
        </ul>
      </section>
    </section>
  </body>
 </document>
--- a/src/documentation/content/xdocs/running.xml
+++ b/src/documentation/content/xdocs/running.xml
@@ -156,6 +156,11 @@ 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 then use markers to change them.
        </li>
        <li>
 Clear the image cache. At the moment, images in the cache are not released automatically when an OutOfMemoryError is imminent.
 Starting with version 0.20.5 however, you can call <code>org.apache.fop.image.FopImageFactory.resetCache()</code> to empty the 
 <jump href="graphics.html#caching">image cache</jump>.
        </li>
      </ul>
      <p>
 There are currently some bugs which cause FOP to go into a nonterminating loop, which will also often result in a memory overflow.