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

21 years ago · 0f3d559ccc
--- a/src/documentation/content/xdocs/anttask.xml
+++ b/src/documentation/content/xdocs/anttask.xml
@@ -0,0 +1,139 @@
 <?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>Ant task</title>
  </header>
  <body>
    <p>
    FOP provides an Ant task for automating the document build process.</p>
    <section><title>Description</title>
    <p>
    The FOP Ant task will convert XSL-FO documents to PDF/PS/PCL/MIF/RTF output
    (see <link href="output.html">Output formats</link> for available formats).</p>
    <p>
 	To call FOP tasks within Ant, first add a FOP task definition to your Ant build file.
 	One method of defining the task is as follows:
 	</p>
 	<source><![CDATA[
 <property name="fop.dir" value="....path to your FOP jar files..."/>

 <taskdef name="fop" 
         classname="org.apache.fop.tools.anttasks.Fop">
         <classpath>
            <pathelement location="${fop.dir}\fop.jar"/>
            <pathelement location="${fop.dir}\avalon.jar"/>
            <pathelement location="${fop.dir}\batik.jar"/>
         </classpath>
 </taskdef>
 	]]></source>
 <p>
 	Then create FOP tasks within your Ant build file, using the FOP task parameters listed below.</p>
    </section>
    <!-- TODO: Installation/Configuration -->
    <section><title>Parameters for FOP Ant task</title>
     <table><caption>Parameters specified as attributes</caption> 
      <tr> 
       <th>Attribute</th> 
       <th>Description</th> 
       <th>Required</th> 
      </tr> 
      <tr> 
       <td>fofile</td> 
       <td>XSL-FO file to be rendered</td> 
       <td>Yes, if no fileset nested element is used</td> 
      </tr> 
      <tr> 
       <td>outfile</td> 
       <td>Output filename</td> 
       <td>Yes, when fofile is used.  (This attribute is not valid for filesets.)</td> 
      </tr> 
      <tr> 
       <td>format</td> 
       <td>Possible output formats:<br/>
         <code>application/pdf</code><br/>
         <code>application/postscript</code><br/>
         <code>application/vnd.mif</code><br/>
         <code>application/rtf</code><br/>
         <code>application/vnd.hp-PCL</code><br/>
         <code>text/plain</code><br/>
         <code>text/xml</code><br/>
       </td> 
       <td>No, defaults to <code>application/pdf</code></td> 
      </tr> 
      <tr> 
       <td>outdir</td> 
       <td>Output directory</td> 
       <td>Required if a fileset is used to specify the files to render; optional for fofile. (Can alternatively specify the full path in the fofile value.)</td> 
      </tr> 
      <!--tr  Commented out; attribute is currently unimplemented according to the code> 
       <td>basedir</td> 
       <td>Directory to work from</td> 
       <td>Yes</td> 
      </tr--> 
      <tr> 
       <td>userconfig</td> 
       <td>User configuration file (same as the FOP "-c" command line option)</td> 
       <td>No</td> 
      </tr> 
      <tr> 
       <td>messagelevel</td> 
       <td>Logging level<br/>
       Possible values: <code>error</code>, <code>warn</code>, <code>info</code>, <code>verbose</code>, <code>debug</code></td> 
       <td>No, defaults to <code>verbose</code></td> 
      </tr> 
      <tr> 
       <td>logFiles</td> 
       <td>Controls whether the names of the files that are processed are logged 
 	   		(<code>true</code>) or not (<code>false</code>)</td> 
       <td>No, default is <code>true</code></td> 
      </tr> 
     </table>
 	 <p/>
 	 <table><caption>Parameters specified as nested elements</caption>
      <tr> 
       <th>Attribute</th> 
       <th>Description</th> 
       <th>Required</th> 
      </tr> 
      <tr> 
       <td>fileset</td> 
       <td><link href="http://ant.apache.org/manual/CoreTypes/fileset.html">FileSets</link> 
 	   		are used to specify multiple XSL-FO files to be rendered.</td> 
       <td>Yes, if no fofile attribute is supplied</td> 
      </tr> 
 	  </table>
    </section>
    <section>
    <title>Examples</title>
    <p>
    The following example converts a single XSL-FO file to a PDF document:
    </p>

    <source><![CDATA[
 <target name="generate-pdf" description="Generates a single PDF file">
   <fop format="application/pdf" 
        fofile="c:\working\foDirectory\foDocument.fo"
        outfile="c:\working\pdfDirectory\pdfDocument.pdf" />
 </target>
    ]]></source>
    <p>
    This example converts all XSL-FO files within an entire directory to PostScript:
    </p>
    <source><![CDATA[
 <target name="generate-multiple-ps" 
        description="Generates multiple PostScript files">
   <fop format="application/postscript" 
        outdir="${build.dir}" messagelevel="debug">
        <fileset dir="${fo.examples.dir}">
           <include name="*.fo"/>
        </fileset>
   </fop>
 </target>
    ]]></source>
    </section>
    </body>
 </document>

--- a/src/documentation/content/xdocs/dev/api-doc.xml
+++ b/src/documentation/content/xdocs/dev/api-doc.xml
@@ -0,0 +1,25 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!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>FOP API Documentation (javadocs)</title>
  </header>
  <body>
    <section id="gump">
      <title>On-line Access (through Gump)</title>
      <p>FOP (and many other Apache projects) use <link href="http://jakarta.apache.org/gump">Apache Gump</link> to do a test build several times each day. One of the useful byproducts of this process is that javadocs can be created and made available.</p>
      <p>First, determine which line of development code you wish to see. If you don't know, you probably want the "Maintenance Branch", which is the line that currently produces FOP releases. See <link href="index.html#lines">Development Lines</link> for more details.</p>
      <warning>Javadocs for both development lines are made from current CVS code, and are not tied to any particular release. Both the documentation and the API may be different, even if you are working with the correct branch. Currently, the only way to obtain API documentation for a specific release is to <link href="#self-built">build it yourself</link>.</warning>
      <ul>
        <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="../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>
      <p>See <link href="../download.html#source">Source Download</link> for instructions on obtaining the source code. Then see <link href="../compiling.html">Building FOP</link> for instructions on running the build process. The Ant build target that you will use to generate the API documentation is "javadocs", and the results will be stored in xml-fop/build/javadocs.</p>
    </section>
  </body>
 </document>
--- a/src/documentation/content/xdocs/dev/book.xml
+++ b/src/documentation/content/xdocs/dev/book.xml
@@ -0,0 +1,38 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE book PUBLIC "-//APACHE//DTD Cocoon Documentation Book V1.0//EN"
    "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-cocoon2/src/documentation/xdocs/dtd/book-cocoon-v10.dtd">

 <book software="FOP"
      title="FOP"
      copyright="@year@ The Apache Software Foundation"
      xmlns:xlink="http://www.w3.org/1999/xlink">

    <menu label="Introduction">
      <menu-item label="Basics" href="index.html"/>
    </menu>
    <menu label="Design">
      <menu-item label="Resolved" href="../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"/>
      <menu-item label="Extensions" href="extensions.html"/>
    </menu>
    <menu label="Develop">
      <menu-item label="API Doc" href="api-doc.html"></menu-item>
      <menu-item label="Walk-Thru" href="implement.html"/>
      <external label="Patch queue" href="http://nagoya.apache.org/bugzilla/buglist.cgi?bug_status=NEW&amp;bug_status=ASSIGNED&amp;bug_status=REOPENED&amp;email1=&amp;emailtype1=substring&amp;emailassigned_to1=1&amp;email2=&amp;emailtype2=substring&amp;emailreporter2=1&amp;bugidtype=include&amp;bug_id=&amp;changedin=&amp;votes=&amp;chfieldfrom=&amp;chfieldto=Now&amp;chfieldvalue=&amp;product=Fop&amp;short_desc=%5BPATCH%5D&amp;short_desc_type=allwordssubstr&amp;long_desc=&amp;long_desc_type=allwordssubstr&amp;bug_file_loc=&amp;bug_file_loc_type=allwordssubstr&amp;keywords=&amp;keywords_type=anywords&amp;field0-0-0=noop&amp;type0-0-0=noop&amp;value0-0-0=&amp;namedcmd=Fop+all&amp;newqueryname=fop+patch+queue&amp;tofooter=1&amp;order=Reuse+same+sort+as+last+time"/>
    </menu>
    <menu label="Test">
      <menu-item label="Testing" href="testing.html"/>
    </menu>
    <menu label="Deploy">
      <menu-item label="Doc Mgmt" href="doc.html"/>
      <external label="Bugs" href="http://nagoya.apache.org/bugzilla/buglist.cgi?bug_status=NEW&amp;bug_status=ASSIGNED&amp;bug_status=REOPENED&amp;email1=&amp;emailtype1=substring&amp;emailassigned_to1=1&amp;email2=&amp;emailtype2=substring&amp;emailreporter2=1&amp;bugidtype=include&amp;bug_id=&amp;changedin=&amp;votes=&amp;chfieldfrom=&amp;chfieldto=Now&amp;chfieldvalue=&amp;product=Fop&amp;short_desc=&amp;short_desc_type=allwordssubstr&amp;long_desc=&amp;long_desc_type=allwordssubstr&amp;bug_file_loc=&amp;bug_file_loc_type=allwordssubstr&amp;keywords=&amp;keywords_type=anywords&amp;field0-0-0=noop&amp;type0-0-0=noop&amp;value0-0-0=&amp;order=bugs.component"/>
    </menu>
    <menu label="Resources">
      <menu-item label="FAQs" href="faq.html"/>
      <menu-item label="Examples" href="examples.html"/>
      <menu-item label="Tools" href="tools.html"/>
      <external label="ViewCVS" href="http://cvs.apache.org/viewcvs.cgi/xml-fop"/>
    </menu>
 </book>
--- a/src/documentation/content/xdocs/dev/doc.xml
+++ b/src/documentation/content/xdocs/dev/doc.xml
@@ -0,0 +1,151 @@
 <?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>Managing FOP Documentation</title>
  </header>
  <body>
    <section id="general">
      <title>General Information</title>
      <p>All raw documentation content is managed in the FOP CVS repository.
 Updates should be committed to the repository, then the repository files are used to generate usable output.
 The remaining discussions on this page assume that the CVS repository is the starting place for processing.
 The path to the documentation is xml-fop/src/documentation/content/xdocs.</p>
      <note>All documentation is maintained on the trunk.
 Although we are currently maintaining two sets of code (trunk and maintenance), there is only one set of documentation.
 Most of the user and developer doc is common to the two environments, and differences are highlighted where necessary.
 The major exception to this rule is the design doc, which currently exclusively pertains to the trunk (redesign).
 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">
        <title>Background</title>
        <p>The FOP web site and documentation are generated using <link href="http://xml.apache.org/forrest">Apache Forrest</link>.</p>
        <p>The following table summarizes the flow of data to the FOP website in chronological order:</p>
        <table>
          <tr>
            <th>Process</th>
            <th>Output</th>
            <th>State</th>
            <th>View(s)</th>
          </tr>
          <tr>
            <td>Developer commits code to FOP repository.</td>
            <td>FOP source repository (cvs) at icarus.apache.org/home/cvs/xml-fop</td>
            <td>Raw XML and other content</td>
            <td><link href="http://cvs.apache.org/viewcvs.cgi/xml-fop/src/documentation/content/xdocs/">ViewCVS</link></td>
          </tr>
          <tr>
            <td>
              <link href="#forrestbot-refresh">Forrestbot "refresh"</link>. Automatically done every six hours. Can be manually refreshed by authorized users at <link href="http://forrestbot.cocoondev.org">the Forrestbot Web Interface</link>.
          </td>
            <td>Physical location unknown and unimportant to us</td>
            <td>web-ready</td>
            <td>Content can be viewed <link href="http://forrestbot.cocoondev.org/sites/xml-fop">here</link>.</td>
          </tr>
          <tr>
            <td><link href="#forrestbot-publish">Forrestbot "publish"</link>. Always done manually at <link href="http://forrestbot.cocoondev.org">the Forrestbot Web Interface</link>.</td>
            <td>FOP web repository (cvs) at icarus.apache.org/home/cvs/xml-site/targets/fop</td>
            <td>web-ready</td>
            <td><link href="http://cvs.apache.org/viewcvs.cgi/xml-site/targets/fop/">ViewCVS</link></td>
          </tr>
          <tr>
            <td>Automatic Live Site Update every six hours (midnight, 6am, noon, 6pm Pacific time).</td>
            <td>FOP live web site, somewhere on daedalus.apache.org</td>
            <td>web-ready</td>
            <td><link href="http://xml.apache.org/fop">FOP Web Site</link></td>
          </tr>
        </table>
      </section>
      <section id="web-forrestbot-refresh">
        <title>Forrestbot "refresh" Step-by-Step</title>
        <note>The Forrestbot "refresh" is automatically run on the server every six hours. Only follow the steps below if you need to check the results more promptly than that allows, or if you need to "refresh" in preparation for a "publish".</note>
        <p>To manually use the Forrestbot "refresh", simply follow these steps:</p>
        <ul>
          <li>Make sure your changes are committed to the FOP source repository.</li>
          <li>Open http://forrestbot.cocoondev.org in your browser.</li>
          <li>Login.</li>
          <li>In the "Select a module" box, select "xml-fop".</li>
          <li>Click the "refresh" button to have the interim site built.
 On-screen instructions tell you how to view the log as the build progresses.</li>
        </ul>
      </section>
      <section id="web-forrestbot-publish">
        <title>Forrestbot "publish" Step-by-Step</title>
        <p>To "publish" the Forrestbot output to the FOP Web repository:</p>
        <ul>
          <li>Make sure you are satisfied with the "refreshed" site.</li>
          <li>Open http://forrestbot.cocoondev.org in your browser.</li>
          <li>Login.</li>
          <li>In the "Select a module" box, select "xml-fop".</li>
          <li>Click the "publish" button.
 On-screen instructions tell you how to view the log as the build progresses.</li>
          <li>Wait for the next 6-hour live-site update cycle and check your changes.</li>
        </ul>
      </section>
      <section id="web-live-update">
        <title>Live Site Update</title>
        <p>If there are problems with the live site update (the process of copying the web site contents from the FOP web repository to the live site:</p>
        <ul>
          <li>The CVS update logs can be viewed at http://www.apache.org/~rubys/updatesite.logx, where "x" is a number from 1-4, these four files being the updates done over the past 24 hours.
 Review the most recent log file for clues.</li>
          <li>The script is maintained by Sam Ruby (rubys@apache.org).
 Contact him for further help.</li>
        </ul>
      </section>
      <section id="web-local-forrest">
        <title>Using a Local Forrest</title>
        <note>Most documentation content changes do not require a local copy of Forrest.
 In general, use the Forrestbot instead. Forrestbot is easy to use, always uses the "approved" methodology, and has fewer error-prone manual steps.</note>
        <p>There are some situations where you may want to have a local Forrest installation. For example, you do not want to tie up server resources testing major changes, such as sitemap building, that may require many edit/build/test/debug cycles. After you are done testing, use the forrestbot to "refresh" and "publish" the site.</p>
        <note>Forrest needs to be run on a machine with a graphical environment.
 It will fail in a headless environment when it tries to use FOP to generate the PDF files.</note>
        <p>To use a local Forrest:</p>
        <ul>
          <li>checkout the xml-forrest module (same repository as xml-fop)</li>
          <li>checkout the xml-site/targets/fop module (same repository as xml-fop)</li>
          <li>you will also need access to a current xml-fop sandbox (you probably already
    have one)</li>
          <li>cd to xml-forrest</li>
          <li>run: build.sh(bat) dist to build forrest</li>
          <li>set environment variable FORREST_HOME=~/xml-forrest/build/dist/shbat where ~ is the directory in which xml-forrest is installed (see http://xml.apache.org/forrest/your-project.html for details)</li>
          <li>set environment variable PATH=$PATH:$FORREST_HOME/bin</li>
          <li>cd to xml-fop directory</li>
          <li>run forrest(.bat), which will build the web-site documents in xml-fop/build/site.</li>
        </ul>
      </section>
      <section id="web-manual">
        <title>Updating the FOP Web Repository Manually (Deprecated)</title>
        <warning>The steps in this section should not ordinarily be used. They are documented here for historical reasons, and for emergencies.
 See <link href="#delete">manually deleting retired files</link> for an exception to this rule.</warning>
        <ul>
          <li>Copy (or sym-link) the documents generated by Forrest (in xml-fop/build/site) to xml-site/targets/fop on your local machine.</li>
          <li>Commit xml-site/targets/fop.</li>
        </ul>
      </section>
      <section id="delete">
        <title>Deleting Documentation Files</title>
        <p>The one place where manual updates of the web cvs repository are required is when a document is retired. At this point, it will no longer be generated. However, it will still exist in the web cvs repository. You will need to use a cvs client to remove the files, then commit the changes to keep them from continuing to exist on the live site.</p>
      </section>
    </section>
  </body>
 </document>
--- a/src/documentation/content/xdocs/dev/extensions.xml
+++ b/src/documentation/content/xdocs/dev/extensions.xml
@@ -0,0 +1,48 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!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>Adding an Extension to FOP</title>
  </header>
  <body>
    <section id="overview">
      <title>Overview</title>
      <p>For documentation of standard FOP extensions, see the <link href="../extensions.html">User FOP Extensions</link> document.</p>
      <p>
 If the default funtionality of FOP needs to be extended for
 some reason then you can write an extension.
            </p>
            <p>There are three types of extensions possible:</p>
            <ul>
              <li>An output document extension such as the PDF bookmarks</li>
              <li>an instream-foreign-object extensions such as SVG</li>
              <li>an fo extension that creates an area in the area tree where normal xsl:fo is not possible</li>
            </ul>
          </section>
          <section id="adding">
            <title>Adding Your Own</title>
            <p>
 To add your own extension you need to do the following things.
 </p>
        <ol>
          <li>Write code that implements your extension functionality. The easiest place to
 start is by looking at the code in org.apache.fop.extension, and by looking at the examples in the <code>contrib</code> directory.</li>
          <li>Create a class that implements the org.apache.fop.fo.ElementMapping interface. ElementMapping is a hashmap of all of the elements in a particular namespace, which makes it easier for FOP to create a different object for each element.
 ElementMapping objects are static to save on memory.
 They are loaded by FOP when parsing starts to validate input.</li>
          <li>Create the following file: "/META-INF/services/org.apache.fop.fo.ElementMapping", which should contain the fully qualified classname of your ElementMapping implementation class.</li>
          <li>Create a jar file containing all of the above files.</li>
          <li>Create your XSL-FO file with the extra XML data embedded in the file with the
 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>
          <li>Put your jar file in the classpath</li>
          <li>Run FOP using your XSL-FO file as input.</li> 
        </ol>
    </section>
  </body>
 </document>

--- a/src/documentation/content/xdocs/dev/faq.xml
+++ b/src/documentation/content/xdocs/dev/faq.xml
@@ -0,0 +1,42 @@
 <?xml version="1.0" encoding="ISO-8859-1"?>
 <!DOCTYPE faqs PUBLIC "-//APACHE//DTD FAQ V1.1//EN"
    "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/schema/dtd/faq-v11.dtd">

 <faqs title="FOP Developer FAQ">
  <part id="part_general">
    <title>General Questions</title>
    <faq>
      <question>How can I contribute?</question>
      <answer>
        <p>There are many ways that you can help:</p>
        <ul>
          <li>You can help us implement missing features that are needed in order to comply with the standard. See the <link href="../compliance.html">Standards Compliance</link> for more details.</li>
          <li>You can help us address bug reports. See <link href="../bugs.html#issues_existing">bugzilla</link> for more information.</li>
          <li>You can help support our user base by answering questions on the fop-user mailing list.</li>
          <li>You can help us document FOP better.</li>
        </ul>
      </answer>
    </faq>
  </part>
  <part id="part_documentation">
    <title>Documentation</title>
    <faq id="javadoc_location">
      <question>How do I get the javadocs for FOP?</question>
      <answer>
        <p>Currently, the only way to get FOP javadocs is to <link href="../download.html">
        Download the source code</link> and then <link href="../compiling.html">Build
        FOP</link> using the ant build task "javadocs".</p>
      </answer>
    </faq>
  </part>
  <part id="part_further_help">
    <title>Further Help</title>
    <faq id="other_faqs">
      <question>I don't see my question addressed here. Are there other FAQs?</question>
      <answer>
        <p>Yes. See also the <link href="../faq.html">FOP General FAQs</link>.</p>
      </answer>
    </faq>
  </part>
 </faqs>

--- a/src/documentation/content/xdocs/dev/fonts.xml
+++ b/src/documentation/content/xdocs/dev/fonts.xml
@@ -0,0 +1,75 @@
 <?xml version="1.0" standalone="no"?>

 <!-- $Id$ -->
 <!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 (Developer Information)</title>
  </header>
  <body>
    <section>
      <title>Goals</title>
      <ul>
        <li>refactor existing font logic for better clarity and to reduce duplication</li>
        <li>parse registered font metric information on-the-fly (to make sure most up-to-date parsing is used??)</li>
        <li>resolve whether the FontBBox, StemV, and ItalicAngle font metric information is important or not -- if so, parse the .pfb file to extract it when building the FOP xml metric file</li>
        <li>handle fonts registered at the operating system (through AWT)</li>
        <li>add support for parsing OpenType fonts</li>
      </ul>
    </section>
    <section>
      <title>Issues</title>
      <ul>
        <li>Why are we using our own font metric parsing and registration system, instead of the AWT system provided as part of Java?
          <ul>
            <li>Answer 1: Many of our customers use FOP in a so-called "headless" server environment -- that is, the operating system is operating in character mode, with no concept of a graphical environment. We need some mechanism of allowing these environments to get font information. Java 1.4 has a mechanism for dealing with headless environments, and this issue may be resolved when we require that as a minimum platform. However, there may be an issue then of how to get fonts registered at the operating system in these environments. That will probably at least require some documentation for users.</li>
            <li>Answer 2: At some level, we don't yet fully trust AWT to handle fonts correctly. There are still unresolved discrepancies between the two systems.</li>
            <li>Answer 3: In the AWT mechanism, there does not appear to be a way to find the physical font file associated with an AWT font, or to otherwise get access to its contents so that it can be embedded in FOP output.</li>
            <li>Answer 4: The Java 1.4 javadocs state (in java.awt.Font): "All implementations of the Java 2 platform must support TrueType fonts; support for other font technologies is implementation dependent." We wish to provide a greater base of font technologies for our users.</li>
          </ul>
        </li>
      </ul>
    </section>
    <section>
      <title>Implementation</title>
      <p>There are two main font functions needed within FOP:</p>
      <ul>
        <li>provision of a font object to be used in layout</li>
        <li>embedding of a font file in output (such as PDF)</li>
      </ul>
      <p>For the first of these, we will implement something along the lines of a "Facade" Structural Pattern to hide the differences between the various font types and font sources from the rest of the system.
 Public classes will consist of TypeFaceFamily, TypeFace, and Font. (TypeFace roughly corresponds to the contents of a normal font file, while Font is a general typeface implemented at a specific point size, and perhaps with other specific parameters).
 When another part of FOP requests a font object, existing font objects will be checked first, and an appropriate one returned if possible.
 If not, the Font logic should resolve the TypeFace and TypeFaceFamily if possible, create a Font object, and return it.</p>
    </section>
    <section>
      <title>Resources</title>
      <section>
        <title>Type 1 Fonts</title>
        <ul>
          <li><link href="http://partners.adobe.com/asn/developer/pdfs/tn/T1_SPEC.PDF">Adobe Type 1 Font Format</link></li>
          <li>According to the Adobe web site, the documentation for the font metrics files (.pfm = printer font metrics) is written and controlled by Microsoft, since it is actually a workaround to allow Type 1 fonts to be used on a GUI screen in Windows. However, the document does not appear to be on the Microsoft web site. The best resource for this information is <link href="http://partners.adobe.com/asn/developer/pdfs/tn/5178.PFM.pdf">Adobe Technical Note #5178</link>: Building PFM Files for Postscript-Language CJK Fonts</li>
          <li>FOP does not currently use the Adobe Font Metrics file, but the specification can be found in <link href="http://partners.adobe.com/asn/developer/pdfs/tn/5004.AFM_Spec.pdf">Adobe Technical Note #5004</link>: Adobe Font Metrics File Format Specification</li>
          <li><link href="http://partners.adobe.com/asn/developer/pdfs/tn/5040.Download_Fonts.pdf">Adobe Technical Note #5040</link>: Supporting Downloadable Postscript Language Fonts may also include some useful information.</li>
        </ul>
      </section>
      <section>
        <title>TrueType Fonts</title>
        <ul>
          <li>The <link href="http://www.microsoft.com/typography/tt/ttf_spec/ttspec.zip">TrueType specification</link></li>
        </ul>
      </section>
      <section>
        <title>OpenType Fonts</title>
        <ul>
          <li>The <link href="http://download.microsoft.com/download/Typography/archive/v1.4/WIN98MeXP/EN-US/otsp14.exe">OpenType specification</link></li>
          <li>The Adobe <link href="http://www.adobe.com/type/opentype/main.html">Introduction to OpenType fonts</link> page has some useful general information and links.</li>
        </ul>
      </section>
    </section>
  </body>
 </document>

 <!-- Last Line of $RCSfile$ -->
--- a/src/documentation/content/xdocs/dev/implement.xml
+++ b/src/documentation/content/xdocs/dev/implement.xml
@@ -0,0 +1,93 @@
 <?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>Implementation Overview</title>
    <subtitle>Following a Document Through FOP</subtitle>
    <authors>
      <person name="Arved Sandstrom" email=""/>
    </authors>
  </header>
  <body>
    <p>The purpose of this document is to tie together the FOP design (interface) with some of the key points where control is passed within FOP (implementation), so that developers can quickly find the section of code that is relevant to their needs. The process described is for a "typical" command-line document. All classes are in org.apache.fop unless otherwise designated.</p>
    <section>
      <title>Overview</title>
      <p>The input FO document is sent to the FO tree builder via SAX events. Fragments of an FO Tree are built from this process. As each page-sequence element is completed, it is passed to a layout processor, which in turn converts it into an Area Tree. The Area Tree is then given to the Renderer, which converts it into a stream of data containing the output document. The sections below will provide additional details. Where needed differences between the trunk and maintenance branches are shown in tabular format.</p>
    </section>
    <section>
      <title>Startup</title>
      <ul>
        <li>The job starts in <em>apps.Fop.main()</em>.</li>
        <li>Control is passed to <em>apps.CommandLineStarter.run()</em>.</li>
        <li>Control is passed to <em>apps.Driver.render()</em>. This class fires up a SAX parser, the events from which indirectly control the remaining processing, including building the FO Tree, building the Area Tree, rendering, output and logging.</li>
      </ul>
    </section>
    <section>
      <title>Formatting Object Tree</title>
      <table>
        <tr>
          <th>Trunk</th><th>Maintenance</th>
        </tr>
        <tr>
          <td colspan="2">The SAX events that the parser creates are handled by <em>fo.FOTreeBuilder</em>, which uses <code>startElement()</code>, <code>endElement()</code>, and <code>characters()</code> methods to build the FO Tree.</td>
        </tr>
        <tr>
          <td><code>fo.FOTreeBuilder.endElement()</code> runs the <code>end()</code> method for each node as it is created. The <em>fo.pagination.PageSequence</em> class overrides this <code>end()</code> method to run <code>apps.LayoutHandler.endPageSequence()</code>, which in turn runs <code>fo.pagination.PageSequence.format()</code>.</td>
          <td>the end of a PageSequence element causes the PageSequence object to be passed to <code>apps.StreamRenderer.render()</code>, which in turn runs <code>fo.pagination.PageSequence.format()</code>.</td>
        </tr>
        <tr>
          <td><code>fo.pagination.PageSequence.format()</code> creates a <em>layoutmgr.PageLayoutManager</em>, passing the AreaTree and PageSequence objects to it, then calls its <code>run()</code> method.</td>
          <td><code>fo.pagination.PageSequence.addFlow()</code> programatically adds a Flow object to the page sequence.</td>
        </tr>
        <tr>
          <td>.</td>
          <td><code>fo.pagination.PageSequence.makePage()</code> creates a BodyArea and passes it to <em>fo.Flow.layout</em></td>
        </tr>
        <tr>
          <td>.</td>
          <td>the layout process is then driven from <code>fo.pagination.PageSequence.format()</code>.</td>
        </tr>
      </table>
    </section>
    <section>
      <title>Layout</title>
      <p>There are layout managers for each type of layout decision.
 They take an FO Tree as input and build a laid-out Area Tree from it.
 The layout process involves finding out where line breaks and page breaks should be made, then creating the areas on the page.
 Static areas can then be added for any static regions.
 As pages are completed, they are added to the Area Tree.</p>
    </section>
    <section>
      <title>Area Tree</title>
      <p>The area tree is a data structure designed to hold the page areas.
 These pages are then filled with the page regions and various areas.
 The area tree is used primarily as a minimal structure that can be rendered
 by the renderers.</p>
      <p>The area tree is supported by an area tree model. This model
 handles the adding of pages to the area tree. It also handles
 page sequence starts, document level extensions, id references
 and unresolved id areas. This model allows the pages to be handled
 directly by a renderer or to store the pages for later use.
 </p>
    </section>
    <section>
      <title>Rendering</title>
      <p>
 The renderer receives pages from the area tree and renders those pages.
 If a renderer supports out of order rendering then it will either
 render or prepare a page in the correct order. Otherwise the
 pages are rendered in order.
 The task of the renderer is to take the pages and output them to
 the requested type.
 In the case of the AWTRenderer it needs to be able to view any page.
 </p>
      <p>
 When rendering a page it takes the page and renders each page region.
 The main work for a renderer implementation is to handle the viewports
 and inline areas. The inline areas need to be drawn on the page in the
 correct place.
 </p>
    </section>
  </body>
 </document>
--- a/src/documentation/content/xdocs/dev/index.xml
+++ b/src/documentation/content/xdocs/dev/index.xml
@@ -0,0 +1,142 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!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>Information for FOP Developers</title>
  </header>
  <body>
    <section id="intro">
      <title>Introduction</title>
      <p>These pages contain information that should be helpful for those developing FOP.
 This certainly includes programmers, but may also include those contributing to the project in other ways.</p>
      <p>For basic and user information on FOP, please visit the <link href="http://xml.apache.org/fop">FOP homepage</link>.</p>
    </section>
    <section id="lines">
      <title>Development Lines</title>
      <p>There are currently three lines of development on the FOP product:</p>
      <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>
      </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>
    </section>
    <section id="involved">
      <title>Getting Involved</title>
      <section id="apache-roles">
        <title>Understand Apache Roles</title>
        <p>Review the <link href="http://xml.apache.org/roles.html">Apache Project Roles and Responsibilities</link> document for an understanding of the various roles of contributors within the community.</p>
      </section>
      <section id="fop-tasks">
        <title>Understand FOP Development Tasks</title>
        <p>There are many different ways that you can help with FOP development. The following is a non-exhaustive list of ways that <em>non-programmers</em> can help. Remember that an hour spent on the tasks below is an hour that a programmer can devote to fixing bugs or adding features instead:</p>
        <ul>
          <li>Answer questions on the fop-user mailing list.</li>
          <li>Contribute examples that are useful to other users.</li>
          <li>Contribute test cases.</li>
          <li>Submit well-written feature requests.</li>
          <li>Submit well-written bug reports.</li>
          <li>Review open issues to see if you have any insight into them that might help a programmer solve the problem faster. Add comments and test cases as appropriate.</li>
          <li>Test newly-closed issues to make sure they are truly closed.</li>
          <li>Submit patches to the documentation.</li>
        </ul>
        <p>Of course, we're glad to have programmers help as well. Here are some additional tasks that would require programming ability:</p>
        <ul>
          <li>Fixing bugs.</li>
          <li>Implementing new features.</li>
        </ul>
      </section>
      <section id="fop-standards">
        <title>Understand FOP-related standards</title>
        <p>At the moment FOP is mainly a tool to render XSL-FO files to pdf. Therefore if you want to contribute to FOP you should become familiar with these standards. You can find links at <link href="../resources.html#specs">Specifications</link>.</p>
      </section>
      <section id="doc">
        <title>Review the Developer Documentation</title>
      </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
 internally will be kept.
    </p>
      </section>
      <section id="mail-fop-dev">
        <title>Subscribe to the fop-dev Mailing List</title>
        <p>Use this forum to discuss topics related to FOP development, including patch submissions, bug reports, and design issues. Please <em>do not</em> use it for XML support, XSLT support, XSL-FO support, or even FOP support.
 Appropriate mailing lists for these topics can be found on the <link href="../maillist.html">FOP Mailing List</link> page.
        </p>
        <ul>
          <li>
 To review the archives, you have several options:
            <ul>
              <li>The <link href="http://marc.theaimsgroup.com/?l=fop-dev&amp;r=1&amp;w=2">Mailing list ARChives</link> (MARC) at the AIMS group (search).
              </li>
              <li>
 The <link href="http://nagoya.apache.org/eyebrowse/SummarizeList?listName=fop-dev@xml.apache.org">Apache Eyebrowse</link> archive (search, list by date, author, subject, or thread).
              </li>
              <li>
 The <link href="http://xml.apache.org/mail/fop-dev/">Apache Mailing List archive</link>.
              </li>
            </ul>
          </li>
          <li>Before posting questions to any list, see "<link href="../maillist.html#general">General Information</link>".</li>
          <li>
 See <link href="http://xml.apache.org/mail.html#fop-dev_fop-cvs">Apache XML Mailing Lists</link>
 for detailed subscription information.
          </li>
          <li>
 To subscribe (digest only): Send email to <link href="mailto:fop-dev-digest-subscribe@xml.apache.org">fop-dev-digest-subscribe@xml.apache.org</link>.
          </li>
          <li>
 To subscribe fully: Send email to <link href="mailto:fop-dev-subscribe@xml.apache.org">fop-dev-subscribe@xml.apache.org</link>.
          </li>
          <li>
 For standard help: Send email to <link href="mailto:fop-dev-help@xml.apache.org">fop-dev-help@xml.apache.org</link>.
          </li>
          <li>
 To unsubscribe: Send email to <link href="mailto:fop-dev-unsubscribe@xml.apache.org">fop-dev-unsubscribe@xml.apache.org</link>.
          </li>
        </ul>
      </section>
      <section id="mail-fop-cvs">
        <title>Subscribe to the fop-cvs Mailing List</title>
        <p>When changes are committed to the code repository, a record of the diffs is emailed to the fop-cvs mailing list. FOP developers are encouraged to subscribe to this list because it helps in following the progress of the project.
        </p>
        <ul>
          <li>Subscribe by sending an email to <link href="mailto:fop-cvs-subscribe@xml.apache.org">fop-cvs-subscribe@xml.apache.org</link>.</li>
        </ul>
      </section>
      <section id="dev-code">
        <title>Download and Use the Developers' Code Using CVS</title>
        <p>Between releases the newest code can be accessed via cvs. To do this you need to install a cvs
     client on your computer, if it is not already there. An explanation how to connect to the
     FOP source repository can be found at <link href="http://xml.apache.org/cvs.html">http://xml.apache.org/cvs.html</link>.
     An introduction into cvs and the cvs manual can be found in the
     <link href="http://xml.apache.org/library.html">reference library</link>.</p>
      </section>
      <section id="patches">
        <title>Submitting Patches</title>
        <p>If you have useful changes to source code (bugfixes or enhancements), test files, or documentation that you would like to contribute to the project, please do the following:</p>
        <ul>
          <li>If your changes include source code, make sure that it does not break FOP (i.e. make sure that FOP still compiles with your changes).</li>
          <li>If your changes include test files, review the <link href="testing.html">Testing page</link>.</li>
          <li><link href="tools.html#cvs_patch">Create a patch file</link> for the differences to be applied to the existing code.</li>
          <li><link href="../bugs.html#issues_new">Create a new bugzilla issue</link> for the patch. Include the text "[PATCH]" at the beginning of the description. Attach the patch file to the issue.</li>
        </ul>
        <p>One of the committers will test your patch and consider its implications for the project. They will then either commit it to the repository or explain on the issue why they did not. Depending on the work load and skill-sets of the various committers, it may take some time before a a submitted patch is addressed.</p>
      </section>
      <section id="code-conventions">
        <title>Coding Conventions</title>
        <p>As mentioned in <link href="http://xml.apache.org/source.html">Apache XML Project Guidelines</link>,
  <strong>all Java Language source code in the repository must be written in conformance to the</strong>
          <link href="http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html">Code Conventions
  for the Java Programming Language</link> as published by Sun. Additionally we agreed on 4
  spaces (no tabs) for indenting.</p>
        <p>If you don't like those conventions, just use your own standards while developing and reformat the source before
  committing with a tool like <link href="http://astyle.sourceforge.net/">astyle</link> (Artistic Style).
  </p>
      </section>
    </section>
  </body>
 </document>
--- a/src/documentation/content/xdocs/dev/svg.xml
+++ b/src/documentation/content/xdocs/dev/svg.xml
@@ -0,0 +1,120 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!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>SVG Developer Issues</title>
  </header>
  <body>
    <p>See also <link href="../graphics.html#svg">SVG User Documentation</link> for more information.</p>
          <section>
            <title>Examples</title>
            <p>
 These examples illustrate a number of issues relating to conversion
 to PDF:
            </p>
  <table>
    <caption>SVG to PDF examples</caption>
    <tr>
      <th></th>
      <th>svg file</th>
      <th>png file</th>
      <th>pdf result</th>
    </tr>
    <tr>
      <td>images</td>
      <td><link href="svg/images.svg">images.svg</link></td>
      <td><!--link href="svg/images.png"-->images.png<!--/link--></td>
      <td><link href="svg/images.pdf">images.pdf</link></td>
    </tr>
    <tr>
      <td>svg linking</td>
      <td><link href="svg/link.svg">link.svg</link></td>
      <td><!--link href="svg/link.png"-->link.png<!--/link--></td>
      <td><link href="svg/link.pdf">link.pdf</link></td>
    </tr>
    <tr>
      <td>gradients and patterns</td>
      <td><link href="svg/paints.svg">paints.svg</link></td>
      <td><!--link href="svg/paints.png"-->paints.png<!--/link--></td>
      <td><link href="svg/paints.pdf">paints.pdf</link></td>
    </tr>
    <tr>
      <td>various text and effects on text</td>
      <td><link href="svg/text.svg">text.svg</link></td>
      <td><!--link href="svg/text.png"-->text.png<!--/link--></td>
      <td><link href="svg/text.pdf">text.pdf</link></td>
    </tr>
    <tr>
      <td>transparent objects</td>
      <td><link href="svg/transparency.svg">transparency.svg</link></td>
      <td><!--link href="svg/transparency.png"-->transparency.png<!--/link--></td>
      <td><link href="svg/transparency.pdf">transparency.pdf</link></td>
    </tr>
  </table>
    <p>
 As can be seen most of the specific issues are handled.
    </p>
 <note>
 You will need Acrobat 5.0 to see transparency.
 </note>
  <table>
    <caption>XSL:FO to PDF examples</caption>
    <tr>
      <th></th>
      <th>fo file</th>
      <th>pdf result</th>
    </tr>
    <tr>
      <td>embedding svg</td>
      <td><link href="fo/embedding.fo">embedding.fo</link></td>
      <td><link href="fo/embedding.fo.pdf">embedding.fo.pdf</link></td>
    </tr>
  </table>
          </section>
          <section>
            <title>Developer Notes</title>
            <p>
 For most output formats in FOP the SVG is simply drawn into
 an image with Batik.
 For PDF there are a set of classes to handle drawing the
 <link href="http://xml.apache.org/batik/architecture.html">GVT (Graphic Vector Toolkit)</link>
 into PDF markup.
            </p>
          <section>
            <title>Classes</title>
            <p>
 These are the relevant classes, found in the package org.apache.fop.svg :
    </p>
 <ul>
 <li><em>PDFGraphics2D</em>
 <br/>
 used for drawing onto a Graphics2D into an existing pdf document, used
 internally to draw the svg.
 </li>
 <li><em>PDFDocumentGraphics2D</em>
 <br/>
 used to create a pdf document and inherits from PDFGraphics2D to do the
 rest of the drawing. Used by the transcoder to create a standalone pdf
 document from an svg. Can be used independantly the same as any Graphics2D.
 </li>
 <li><em>PDFTranscoder</em>
 <br/>
 used by Batik to transcode an svg document into a standalone pdf, via
 PDFDocumentGraphics2D.
 </li>
 </ul>
          </section>
          <section>
            <title>Ideas</title>
            <p>
 Batik can convert ttf to svg font.
 This svg font could be converted into a pdf stroked font
 (type 3 font).
        </p>
      </section>
    </section>
  </body>
 </document>

--- a/src/documentation/content/xdocs/dev/testing.xml
+++ b/src/documentation/content/xdocs/dev/testing.xml
@@ -0,0 +1,119 @@
 <?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>Testing FOP</title>
    </header>

    <body>
    <section id="build">
      <title>"Build" Testing</title>
      <p>Apache projects use an automated build tool called "gump" to create nightly builds from the CVS repository. Gump sends "nag" messages if the build fails. This can be considered a sort of basic test of the build process. To view the most recent logs of the gump builds:</p>
      <ul>
        <li><link href="http://gump.cocoondev.org/xml-fop.html">Gump build for the Trunk</link></li>
        <li><link href="http://gump.cocoondev.org/xml-fop-maintenance.html">Gump build for the Maintenance Branch</link></li>
      </ul>
    </section>
 <section id="functional">
  <title>Functional Testing</title>
  <section>
    <title>Running and Using Tests</title>
    <p>
 Testing is an important part of getting FOP to operate correctly and conform to the
 necessary standards.
    </p>
    <p>
 A testing system has been set up that works with as a build target when developing
 with FOP. A developer can run the tests after making changes to the code, the aim
 is to have the tests run to verfiy that nothing working has been broken.
    </p>
    <p>
 To setup the testing the developer must place a reference fop.jar in the
 "&lt;cvs_repository>/test/reference/" directory. This jar will be dynamically
 loaded to create the reference output.
    </p>
  </section>

  <section>
    <title>W3C TestSuite</title>
    <p>
 The testing is set up so that you can download the testsuite from
 <jump href="http://www.w3.org/Style/XSL/TestSuite/">http://www.w3.org/Style/XSL/TestSuite/</jump>,
 unzip the file into the base directory of FOP.
 Then you can uncomment the lines in the build.xml file in the test target and itwill run through all the tests in the testsuite distribution.
    </p>
  </section>

  <section>
    <title>Writing a Test</title>
    <p>
 A test belongs to one of a few catagories. A basic test should excercise one
 element in a number of situations such as changing a property. This should have
 at least one normal value, one border value and one invalid value. If the property
 can be of different types then this should also be included.
    </p>
    <p>
 A bug test is a test that is specifically aimed at a problem with FOP. That is, the test
 is not excercising the specification but rather a problem with FOP in handling a particular
 situation that is not exposed with the other testing.
    </p>
    <p>
 A system test is one that tests the abitlity of FOP to handle a number of different
 elements together.
    </p>
    <p>
 A test can consist of a complete fo document or a part of the document such as
 some elements that will be placed into the flow of a standard document.
    </p>

  </section>
  <section>
    <title>Submitting a Test</title>
    <p>
 If you have a test which you think would be useful you should supply the
 test and a diff to the appropriate test suite xml file. Make sure that the
 test works as would be expected against the current build.
    </p>
  </section>

  <section>
    <title>How Testing Works</title>
    <p>
 The tests are stored in the "&lt;cvs_repository>/test" directory.
    </p>
    <p>
 You can run the tests by specifying the build target "test" ie: <br/>
 <code>build.sh test</code>
    </p>
    <p>
 This will then compare the current code in the local src directory to a specified
 release of FOP. Any differences between the current code and the output from
 the reference version will be reported. If the test previously passed then the
 test run will have failed.
    </p>
    <p>
 The testing is done by reading a test suite xml file, which corresponds to the
 standard testsuite.dtd supplied from w3c. This xml file contains a test xml
 file and an xsl file (which may simply copy the file). It also contains information
 such as if the test has passed and any comments.
    </p>
    <p>
 For FOP the testing is done by rendering all the testing documents using the
 XML renderer. The XML files are then compared to see if there are any differences.
    </p>
  </section>

  <section>
    <title>SVG Testing</title>
    <p>
 The testing of SVG is not part of this testing system. SVG is tested for its rendering
 accuracy by using the transcoding mechanism via Batik. So that the only part that needs
 testing is how the SVG image is embedded inside the flow of the fo document.
    </p>
  </section>
 </section>
 </body>
 </document>

--- a/src/documentation/content/xdocs/dev/tools.xml
+++ b/src/documentation/content/xdocs/dev/tools.xml
@@ -0,0 +1,78 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!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>Developer Tools</title>
  </header>
  <body>
    <p>This page documents items that may be helpful to other developers, especially to those who are new to FOP. Exhaustive treatment of these topics is better suited to other fora, but the information presented here is intended to deal with FOP-specific issues related to these tools, especially "gotchas", and to help developers get jump-started.</p>
    <section id="general">
      <title>General Developer Information</title>
    <p>See <link href="http://www.apache.org/dev/contributors.html">the Apache Contributors Tech Guide</link> for useful information and links for Apache developers, including help with tools and procedures.</p>
    </section>
    <section id="cvs">
      <title>Concurrent Versions System (CVS)</title>
      <section id="cvs_general">
        <title>General</title>
        <p>Visit <link href="http://xml.apache.org/cvs.html">Apache XML CVS Repositories</link> for useful information.</p>
        <p>You will need a CVS client to be able to gain access to the FOP repository. For general CVS information, visit <link href="http://www.cvshome.org">CVS Home</link>. Nice GUI clients for Windows, Mac, and X(??) can be found at <link href="http://www.wincvs.org">WinCVS</link>.</p>
        <p>Regardless of what platform you develop on, please be sure to submit patches that use Unix line endings. If you are using WinCVS, check code out this way by going to the Admin / Preferences menu item, clicking on the "Globals" tab, then select the "Checkout text files with the Unix LF (0xa)" option. You will also need to use an editor that supports opening and saving files using Unix line endings.</p>
      </section>
      <section id="wincvs_download">
        <title>Step-by-step instructions for downloading FOP using WinCVS</title>
        <ul>
          <li>Select "Create / Checkout Module" menu item.</li>
          <li>“Checkout Settings” Tab:
            <ul>
              <li>“Enter the module name and path on the server:”<br/>
                <code>xml-fop</code>
              </li>
              <li>“Local folder to checkout to:”<br/>Enter your local directory</li>
            </ul>
          </li>
          <li>“Checkout Options” Tab:
          <ul>
              <li>If you are checking out the trunk, unset all options.</li>
              <li>If you are checking out the maintenance branch (currently distributed code), check “By revision/tag/branch:” and enter <code>fop-0_20_2-maintain</code>.</li>
            </ul>
          </li>
          <li>“General” Tab:
          <ul>
              <li>“Enter the CVSROOT:”<br/>
                <code>:pserver:anoncvs@cvs.apache.org:/home/cvspublic</code>
              </li>
              <li>“Authentication:”<br/>
                <code>“passwd” file on the cvs server</code>
              </li>
            </ul>
          </li>
          <li>“Globals” Tab:
          <ul>
              <li>check “Checkout text files with the Unix LF (Oxa)”</li>
            </ul>
          </li>
          <li>Click "OK" and the download should begin.</li>
        </ul>
      </section>
      <section id="cvs_patch">
        <title>Creating Patches</title>
        <ul>
          <li>
            <code>cd</code> to a directory that contains all of the changes that you wish to include in the patch. To comprehend the entire distribution, <code>cd</code> to the directory above the "xml-fop" directory that was created when you checked out the code.</li>
          <li>Run: <code>cvs -q diff -wu &lt;list of items to diff&gt;</code>
            <br/>The &lt;list of items to diff&gt; is a space-separated list of files and directories relative to the current directory that you wish to include in the diff. For example, to include the entire distribution, assuming that you are in the directory, above xml-fop, simply enter "xml-fop". This will recursively go through the directories beneath xml-fop to diff each file.</li>
          <li>If you are running WinCVS, select "Admin/Command Line" for a console in which to key the above command.</li>
          <li>On a Linux/Unix machine, you will want to redirect the output from the above command into a file. If you are using GNU WinCVS, you can cut the output from the console window and paste it into a file. The "-w" ignores whitespace differences. The "-u" puts the diff in "universal" format. You may wish to use the "-N" option as well, which is supposed to treat new files as if there were an old 0 byte file -- in other words, it is supposed to include the new file in the patch. However, it only operates on files that have been "add"ed to the CVS repository, which cannot be done without commit access.</li>
        </ul>
      </section>
    </section>
    <section id="ide">
      <title>Integrated Development Environments (IDEs)</title>
      <p>An IDE is not required, but will generally be found to be helpful, especially for serious debugging and refactoring.</p>
      <p>See <link href="http://jakarta.apache.org/site/idedevelopers.html">the Apache Jakarta IDE Developer's Guide</link> for useful information on Java IDEs.</p>
      <p>Borland's JBuilder 7/8 does not support Ant builds unless you have the Enterprise Edition (which is quite expensive). This causes problems with any code that is generated by the Ant build. First, you must run the Ant build before you can use the IDE. Second, when you are editing in the IDE, you must be editing the generated files, which means that you must make any changes to the source files in another editor. This is less serious for development on the trunk, but in the maintenance branch, all source files were "generated".</p>
      <p>Sun ONE Studio Four does support Ant, but seems to use a built-in version, and as of this writing chokes on the FOP build file, saying that it is not valid. There is awkward because there is no official DTD for Ant, and it may be merely an Ant version issue.</p>
    </section>
  </body>
 </document>
--- a/src/documentation/content/xdocs/fo.xml
+++ b/src/documentation/content/xdocs/fo.xml
@@ -0,0 +1,440 @@
 <?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>XSL-FO Input</title>
    <subtitle>Basic Help for Using XML, XSLT, and XSL-FO</subtitle>
  </header>
  <body>
    <section id="overview">
      <title>Overview</title>
      <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.
      </p>
    </section>
    <section id="xml">
      <title>XML Issues</title>
      <section id="xml-special-chars">
        <title>Special Characters</title>
        <p>
          When entering special (non-ASCII) characters in XML, the general rule is to use the applicable Unicode character instead of trying to use a character entity as you would with HTML.
 Remember that HTML is an SGML document type.
 SGML has a limited character set, which requires it to use character entities to represent special characters.
 One of the improvements of XML over SGML (and thus HTML) is native support for Unicode.
 Basic XML has only a handful of character entities, primarily because it doesn't really need more.
        </p>
        <p>
          Entities such as <code>&amp;uuml;</code> (u with an umlaut), which work in HTML, will be flagged as undefined entities unless you define them yourself in your DTD.
 Use the corresponding Unicode character instead.
 A list of predefined HTML entities and their Unicode codepoints can be found at <link href="http://www.w3.org/TR/html4/sgml/entities.html">Character entity references in HTML 4</link>.
        </p>
        <p>
          One common example is <code>&amp;nbsp;</code>, used to obtain a non-breaking space in HTML.
 In XML, use &amp;#160; instead.
        </p>
        <p>
          For other non-ASCII characters, such as the Euro symbol, checkbox, etc., see the <link href="http://www.unicode.org/charts/charindex.html">Unicode Reference By Name</link> document that is found at the <link href="http://www.unicode.org">Unicode Consortium</link> site.
        </p>
        <p>
          After finding the correct Unicode codepoint to represent the character, use <link href="http://www.w3.org/TR/2000/REC-xml-20001006#sec-references">XML Character References</link> to put the character into your source XML, XSLT or FO.
 See the non-breaking-space comments above for an example of the syntax using decimal notation.
 The following hexadecimal example will result in a Euro sign:
        </p>
        <source><![CDATA[&#x20AC;]]></source>
        <p>
          Getting your XML correctly encoded is only part of the job.
 If you want the character to display or print correctly (and you probably do), then the selected font must contain the necessary glyph.
 Because of differences between font encoding methods, and limitations in some font technologies, this can be a troublesome issue, especially for symbol characters.
 The FOP example file <link href="fo/fonts.fo.pdf">Base-14 Font Character Mapping</link> is a very useful resource in sorting these issues out for the Base-14 fonts.
 For other fonts, use font editing sofware or operating system utilities (such as the Character Map in most Windows platforms) to determine what characters the font supports.
        </p>
        <p>
          An alternative to encoding the character and making it available through a font is to use an embedded graphic to represent the character: GIF, PNG, SVG, etc.
        </p>
      </section>
      <section id="xml-entity-chars">
        <title>Entity Characters</title>
        <p>
            The handful of basic XML character entities that do exist are the ampersand, apostrophe, less-than, greater-than, and single-quote characters.
 These are needed to distinguish markup tags from content, and to distinguish character entities from content.
 To avoid parser complaints about illegal characters and entities in your input, ensure that ampersands in text and attributes are written as &amp;amp;, "&lt;" is written as &amp;lt;, and ">" as &amp;gt;.
 It is not necessary everywhere, but it is wise to do so anyway, just to be sure.
        </p>
        <p>
          Most XML parsers will provide a line number and sometimes a column number for offending characters.
        </p>
        <p>
          Review the <link href="http://www.w3.org/XML/">XML Specification</link> or a good tutorial for details of the XML file format.
        </p>
      </section>
      <section id="xml-encoding">
        <title>Encoding Issues</title>
        <p>
          If the parser complains about illegal bytes or characters in the input, or there are unexpected characters in the output, this is usually is the result of a character encoding problem.
 See the <link href="http://www.dpawson.co.uk/xsl">XSL FAQ</link> for additional information.
 Many software packages that produce XML, including XSLT processors, use UTF-8 encoding as a default.
 If you view their output with something not aware of the encoding, like Notepad for Win95/98/ME/NT, funny characters are displayed. A &#197; is a giveaway.
        </p>
      </section>
    </section>
    <section id="xsl-fo">
      <title>XSL-FO Issues</title>
      <section id="fo-center-vertical">
        <title>Vertical Centering</title>
        <p>
          To vertically center an image, table, or other item, use display-align="center".
 See <link href="compliance.html#fo-property-display-align">display-align Compliance</link> for implementation status.
 Here is a small, self-contained document centering an image on a page:
        </p>
        <source><![CDATA[<?xml version="1.0"?>
 <fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format">
  <fo:layout-master-set>
    <fo:simple-page-master master-name="content"
        page-width="210mm" page-height="297mm">
      <fo:region-body/>
    </fo:simple-page-master>
  </fo:layout-master-set>
  <fo:page-sequence master-reference="content">
    <fo:flow flow-name="xsl-region-body">
      <fo:table table-layout="fixed" width="100%">
        <fo:table-column column-width="proportional-column-width(1)"/>
        <fo:table-body>
          <fo:table-row height="297mm">
            <fo:table-cell display-align="center">
              <fo:block text-align="center">
                <fo:external-graphic src="fop.jpg"/>
              </fo:block>
            </fo:table-cell>
          </fo:table-row>
        </fo:table-body>
      </fo:table>
    </fo:flow>
  </fo:page-sequence>
 </fo:root>]]></source>
      </section>
      <section id="fo-center-table-horizon">
        <title>Horizontal Centering (Tables)</title>
        <p>
          To center a table horizontally, one possibility is to add one column on the left and one on the right which pad the table so that the visible part is centered:
        </p>
        <source><![CDATA[<?xml version="1.0"?>
 <fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format">
  <fo:layout-master-set>
    <fo:simple-page-master master-name="content"
      page-width="210mm" page-height="297mm">
      <fo:region-body/>
    </fo:simple-page-master>
  </fo:layout-master-set>
  <fo:page-sequence master-reference="content">
    <fo:flow flow-name="xsl-region-body">
      <fo:table table-layout="fixed" width="100%">
        <fo:table-column column-width="proportional-column-width(1)"/>
        <fo:table-column column-width="100mm"/>
        <fo:table-column column-width="proportional-column-width(1)"/>
        <fo:table-body>
          <fo:table-row>
            <fo:table-cell/>
            <fo:table-cell>
              <fo:block>foo</fo:block>
            </fo:table-cell>
            <fo:table-cell/>
          </fo:table-row>
        </fo:table-body>
      </fo:table>
    </fo:flow>
  </fo:page-sequence>
 </fo:root>]]></source>
        <p>
          If your table is more complicated, or if defining borders on individual cells becomes too much work, use the code above and nest your table within the middle cell.
        </p>
      </section>
      <section id="fo-oddeven">
        <title>Recto/Verso Static Content Differences</title>
        <p>
          One frequent request is that static content be different between recto pages (right-side or odd-numbered pages typically) and verso pages(left-side or even-numbered pages typically).
 For example, you may wish to place the page number on the "outer" side of each page.
 There are examples in the FO distribution and in the <link href="http://www.dpawson.co.uk/xsl/sect3/index.html">XSL FAQ FO section</link>.
        </p>
        <p>
          First, define a page master with alternating pages masters for odd and even pages.
 Then specify appropriate regions in these page masters, giving them different names.
 Use these names to put different static content in these regions. Here is a self-contained demonstration:
        </p>
        <source><![CDATA[<?xml version="1.0"?>
 <fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format">
  <fo:layout-master-set>
    <fo:simple-page-master master-name="even"
      page-height="297mm" page-width="210mm"
      margin-top="20mm" margin-bottom="20mm"
      margin-left="25mm" margin-right="25mm">
      <fo:region-body margin-bottom="20mm"/>
      <fo:region-after region-name="footer-even" extent="20mm"/>
    </fo:simple-page-master>
    <fo:simple-page-master master-name="odd"
      page-height="297mm" page-width="210mm"
      margin-top="20mm" margin-bottom="20mm"
      margin-left="25mm" margin-right="25mm">
      <fo:region-body margin-bottom="20mm"/>
      <fo:region-after region-name="footer-odd" extent="20mm"/>
    </fo:simple-page-master>
    <fo:page-sequence-master master-name="document">
      <fo:repeatable-page-master-alternatives>
        <fo:conditional-page-master-reference odd-or-even="even"
          master-reference="even"/>
        <fo:conditional-page-master-reference odd-or-even="odd"
          master-reference="odd"/>
      </fo:repeatable-page-master-alternatives>
    </fo:page-sequence-master>
  </fo:layout-master-set>
  <fo:page-sequence master-reference="document">
    <fo:static-content flow-name="footer-even">
      <fo:block text-align="start"><fo:page-number/></fo:block>
    </fo:static-content>
    <fo:static-content flow-name="footer-odd">
      <fo:block text-align-last="end"><fo:page-number/></fo:block>
    </fo:static-content>
    <fo:flow flow-name="xsl-region-body">
      <fo:block/>
      <fo:block break-before="page"/>
    </fo:flow>
  </fo:page-sequence>
 </fo:root>]]></source>
      </section>
      <section id="fo-first-page">
        <title>Making the First Page Special</title>
        <p>
          To get a special header on the first page, one possibility is to insert it into the flow instead of the static content. Alternatively, use a page master referring to different page masters for the first page and the rest. Here is a code sample:
        </p>
        <source><![CDATA[<?xml version="1.0"?>
 <fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format">
  <fo:layout-master-set>
    <fo:simple-page-master master-name="first"
      page-height="297mm" page-width="210mm"
      margin-top="20mm" margin-bottom="20mm"
      margin-left="25mm" margin-right="25mm">
      <fo:region-body margin-bottom="20mm"/>
      <fo:region-after region-name="footer-first" extent="20mm"/>
    </fo:simple-page-master>
    <fo:simple-page-master master-name="rest"
      page-height="297mm" page-width="210mm"
      margin-top="20mm" margin-bottom="20mm"
      margin-left="25mm" margin-right="25mm">
      <fo:region-body margin-bottom="20mm"/>
      <fo:region-after region-name="footer-rest" extent="20mm"/>
    </fo:simple-page-master>
    <fo:page-sequence-master master-name="document">
      <fo:repeatable-page-master-alternatives>
        <fo:conditional-page-master-reference page-position="first"
          master-reference="first"/>
        <fo:conditional-page-master-reference page-position="rest"
          master-reference="rest"/>
      </fo:repeatable-page-master-alternatives>
    </fo:page-sequence-master>
  </fo:layout-master-set>
  <fo:page-sequence master-reference="document">
    <fo:static-content flow-name="footer-first">
      <fo:block text-align="center">First page.</fo:block>
    </fo:static-content>
    <fo:static-content flow-name="footer-rest">
      <fo:block text-align-last="center">Other page.</fo:block>
    </fo:static-content>
    <fo:flow flow-name="xsl-region-body">
      <fo:block/>
      <fo:block break-before="page"/>
      <fo:block break-before="page"/>
    </fo:flow>
  </fo:page-sequence>
 </fo:root>]]></source>
      </section>
      <section id="fo-blank-pages">
        <title>Blank Pages</title>
        <p>
          Sometimes it is desirable to insert blank pages within your output, starting, for example, a new chapter on an odd page or an even page.
 A blank page can be forced by using <code>break-before="page-even"</code> or similar properties, or by a force-page-count="end-on-odd" on a page sequence.
        </p>
        <p>
          To write "This page is intentionally left blank" (or something similar) on an intentionally blank page, first define a conditional page master with a page master specific for blank pages.
 This allows you to specify static content for blank pages (by definition, a page is blank if no content from a flow is rendered on the page).
 Omit your normal headers and footers, and use (for example) an extended header to print the "..left blank" statement:
          </p>
        <source><![CDATA[<?xml version="1.0"?>
 <fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format">
  <fo:layout-master-set>
    <fo:simple-page-master master-name="normal"
      page-height="297mm" page-width="210mm"
      margin-top="20mm" margin-bottom="20mm"
      margin-left="25mm" margin-right="25mm">
      <fo:region-body margin-bottom="20mm"/>
      <fo:region-after region-name="footer-normal" extent="20mm"/>
    </fo:simple-page-master>
    <fo:simple-page-master master-name="blank"
      page-height="297mm" page-width="210mm"
      margin-top="20mm" margin-bottom="20mm"
      margin-left="25mm" margin-right="25mm">
      <fo:region-body/>
      <fo:region-before region-name="header-blank" extent="297mm"/>
    </fo:simple-page-master>
    <fo:page-sequence-master master-name="document">
      <fo:repeatable-page-master-alternatives>
        <fo:conditional-page-master-reference blank-or-not-blank="not-blank"
          master-reference="normal"/>
        <fo:conditional-page-master-reference blank-or-not-blank="blank"
          master-reference="blank"/>
      </fo:repeatable-page-master-alternatives>
    </fo:page-sequence-master>
  </fo:layout-master-set>
  <fo:page-sequence master-reference="document" force-page-count="end-on-even">
    <fo:static-content flow-name="footer-normal">
      <fo:block text-align="center">Normal footer</fo:block>
    </fo:static-content>
    <fo:static-content flow-name="header-blank">
      <fo:block space-before="100mm" text-align-last="center">
        Intentionally left blank.</fo:block>
    </fo:static-content>
    <fo:flow flow-name="xsl-region-body">
      <fo:block/>
    </fo:flow>
  </fo:page-sequence>
 </fo:root>]]></source>
      </section>
      <section id="fo-preformat">
        <title>Preformatting Content</title>
        <p>
          Sometimes it is desirable to retain linebreaks and hard spaces, and to get preformatted text to pass through without being changed.
 The XSL-FO specification provides some properties for this: <link href="http://www.w3.org/TR/xsl/slice7.html#white-space-collapse">white-space-collapse</link> and <link href="http://www.w3.org/TR/xsl/slice7.html#linefeed-treatment">linefeed-treatment</link>.
 In FOP, use white-space-collapse="false" on an enclosing block.
        </p>
        <warning>
          Due to a bug in current versions of FOP, setting white-space-collapse="false" will also preserve line breaks in the text. Do not rely on this behavior, as it is non-conformant and will be changed.
        </warning>
      </section>
      <section id="fo-total-pages">
        <title>Total Document Pages</title>
        <p>
          It is frequently desirable to know the total number of pages in a document and to use that number within the document.
 For example, you might wish to show the page number on the first page as being "page 1 of 12".
 To accomplish this, place an empty block with an id at the end of the flow:
        </p>
        <source><![CDATA[<fo:flow ...>
    ...
  <fo:block id="last-page"/>
 </fo:flow>]]></source>
        <p>
          Get the number of the last page as follows:
        </p>
        <source><![CDATA[ <fo:page-nuber-citation ref-id="last-page"/>]]></source>
        <p>
          This does not work 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>
        <warning>
          There is no reliable way to get the real total page count with FO mechanisms. You can only get <em>page numbers</em>.
        </warning>
        <p>
          The FOP library provides a method to get the total page count after an FO document has been rendered.
 One possibility is to implement your own wrapper to do a dummy rendering, inquire the total page count and then perform the real rendering, passing the total page count to the XSLT processor to splice it into the generated FO.
 For example:
          </p>
        <source><![CDATA[import org.apache.fop.apps.*;
 import org.xml.sax.*;
 import java.io.*;
 import javax.xml.transform.*;
 import javax.xml.transform.sax.*;
 import javax.xml.transform.stream.*;

 class rendtest {

  public static void main(String args[]) {
    try {
      Driver driver=new Driver();
      driver.setOutputStream(new FileOutputStream(args[2]));
      driver.setRenderer(Driver.RENDER_PDF);
      Transformer transformer=TransformerFactory.newInstance()
        .newTransformer(new StreamSource(new File(args[1])));
      transformer.setParameter("page-count","#");
      transformer.transform(new StreamSource(new File(args[0])),
        new SAXResult(driver.getContentHandler()));
      String pageCount=Integer.toString(driver.getResults().getPageCount());
      driver=new Driver();
      driver.setOutputStream(new FileOutputStream(args[2]));
      driver.setRenderer(Driver.RENDER_PDF);
      transformer=TransformerFactory.newInstance()
        .newTransformer(new StreamSource(new File(args[1])));
      transformer.setParameter("page-count",pageCount);
      transformer.transform(new StreamSource(new File(args[0])),
        new SAXResult(driver.getContentHandler()));
    }
    catch( Exception e) {
      e.printStackTrace();
    }
  }
 }]]></source>
        <p>
          Declare and use the parameter "page-count" in your XSLT.
        </p>
        <warning>
          It is possible to run into a convergence problem with this solution. Replacing the "#" placeholder in the first run with the actual page count in the second run, may change the total number of pages in the document.
        </warning>
      </section>
      <section id="fo-region-align">
        <title>Aligning Regions</title>
        <p>
          Although it may seem counterintuitive, the regions on a page may overlap.
 Defining a certain body region does not automatically constrain other regions.
 Instead, this has to be done explicitly.
 Sometimes for creative reasons it may be desirable to have the regions overlap.
 Otherwise, you will want to set them up so that the header does not overlap body content or the body extend into the footer.
        </p>
        <p>
          Assuming you wish to keep the regions separate, if you have a header region with an extent of 20mm, you should define a margin for the body region of at least 20mm too.
 Otherwise the header content may overwrite some stuff in the body region.
 This applies similarly to the extent of the after region and the bottom margin of the body region.
        </p>
      </section>
      <section id="fo-lines">
        <title>Drawing Lines</title>
        <p>
          It is frequently desirable to draw lines in a document, as separators, side bars or folding marks. There are several possibilities:
        </p>
        <ul>
          <li>
            Horizontal lines can be drawn using <link href="http://www.w3.org/TR/xsl/slice6.html#fo_leader">fo:leader</link>.
          </li>
          <li>
            Use a solid border on a suitable fo:block. This will work for horizontal and vertical lines only.
          </li>
          <li>
            Insert a graphic. GIF, PNG SVG, whatever.
          </li>
        </ul>
      </section>
      <section id="fo-validate">
        <title>Validating XSL-FO</title>
        <p>
          <link href="http://www.renderx.com">RenderX</link> has provided an <link href="http://www.renderx.com/Tests/validator/fo.dtd.html">Unofficial DTD for FO Documents</link>, which may be helpful in validating general FO issues.
        </p>
        <p>
          FOP also maintains an <link href="http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-fop/docs/foschema/fop.xsd?rev=HEAD&amp;content-type=text/plain">Unofficial FOP Schema</link> in the FOP CVS Repository.
 This document can be used either to validate against the FO standard, or against the actual FOP implementation.
 See the notes near the beginning of the document for instructions on how to use it.
          </p>
      </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>
  </body>
 </document>
--- a/src/documentation/content/xdocs/graphics.xml
+++ b/src/documentation/content/xdocs/graphics.xml
@@ -0,0 +1,256 @@
 <?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>FOP Graphics Formats</title>
  </header>
  <body>
    <section id="support-overview">
      <title>Overview of Graphics Support</title>
      <p>
        The table below summarizes the <em>theoretical</em> support for graphical formats within FOP. In other words, within the constraints of the limitations listed here, these formats <em>should</em> work. However, many of them have not been tested, and there may be limitations that have not yet been discovered or documented. The packages needed to support some formats are not included in the FOP distribution and must be installed separately. Follow the links in the "Support Thru" column for more details.
      </p>
      <table>
        <tr>
          <th>Format</th>
          <th>Type</th>
          <th>Support Thru</th>
        </tr>
        <tr>
          <td>BMP (Microsoft Windows Bitmap)</td>
          <td>bitmap</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>
        </tr>
        <tr>
          <td>GIF (Graphics Interchange Format)</td>
          <td>bitmap</td>
          <td><link href="#native">FOP native</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>PNG (Portable Network Graphic)</td>
          <td>bitmap</td>
          <td><link href="#jimi">JIMI</link> or <link href="#jai">JAI</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><link href="#tiff">TIFF</link> (Tag Image Format File)</td>
          <td>bitmap</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>
    <section id="packages">
      <title>Graphics Packages</title>
      <section id="native">
        <title>FOP Native</title>
        <p>
          FOP has native ability to handle some graphic file formats.
        </p>
      </section>
      <section id="jimi">
        <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 {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>
        <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, 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>
      <section id="batik">
        <title>Batik</title>
        <p>Current FOP distributions include a distribution of the Apache Software Foundation's <jump href="http://xml.apache.org/batik">Batik</jump> version 1.5beta4.
 It is automatically installed with FOP.
 Because Batik's API changes frequently, it is highly recommended that you use the version that ships with FOP, at least when running FOP.</p>
        <warning>Batik must be run in a graphical environment.</warning>
        <p>Batik must be run in a graphical environment.
 It uses AWT classes for rendering SVG, which in turn require an X server on Unixish systems.
 If you run a server without X, or if you can't connect to the X server due to security restrictions or policies (a so-called "headless" environment), SVG rendering will fail.</p>
        <p>Here are some workarounds:</p>
        <ul>
          <li>If you are using JDK 1.4, start it with the <code>-Djava.awt.headless=true</code> command line option.</li>
          <li>Install an X server which provides an in-memory framebuffer without actually using a screen device or any display hardware. One example is Xvfb.</li>
          <li>Install a toolkit which emulates AWT without the need for an underlying X server. One example is the <link href="http://www.eteks.com/pja/en">PJA toolkit</link>, which is free and comes with detailed installation instructions.</li>
        </ul>
      </section>
    </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>
      </ul>
    </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>
    </section>
    <section id="svg">
      <title>SVG</title>
      <section id="svg-intro">
        <title>Introduction</title>
        <p>FOP uses <link href="#batik">Batik</link> for SVG support.
 This format can be handled as an <code>fo:instream-foreign-object</code> or in a separate
 file referenced with <code>fo:external-graphic</code>.</p>
      <note>   
 Batik's SVG Rasterizer utility may also be used to convert standalone SVG
 documents into PDF.  For more information please see the
 <link href="http://xml.apache.org/batik/svgrasterizer.html">SVG Rasterizer documentation</link>
 on the Batik site.
      </note>
      </section>
      <section id="svg-pdf-graphics">
        <title>Placing SVG Graphics into PDF</title>
        <p>
 The SVG is rendered into PDF by using PDF commands to draw and fill
 lines and curves. This means that the graphical objects created with
 this remain as vector graphics.
        </p>
        <p>
 There are a number of SVG things that cannot be converted directly into
 PDF. Parts of the graphic such as effects, patterns and images are inserted
 into the PDF as a raster graphic. The resolution of this graphic may not
 be ideal depending on the FOP dpi (72dpi) and the scaling for that graphic.
 We hope to improve this in the future.</p>
        <p>
 Currently transparency is not supported in PDF so many svg images that
 contain effects or graphics with transparent areas will not be displayed
 correctly.
        </p>
      </section>
      <section id="svg-pdf-text">
        <title>Placing SVG Text into PDF</title>
        <p>If possible, Batik will use normal PDF text when inserting text. It does
 this by checking if the text can be drawn normally and the font is
 supported. This example svg <link href="dev/svg/text.svg">text.svg</link> /
 <link href="dev/svg/text.pdf">text.pdf</link>
 shows how various types and effects with text are handled.
 Note that tspan and outlined text are not yet implemented.</p>
        <p>
 Otherwise, text is converted and drawn as a set of shapes by batik, using the stroking text painter.
 This means that a typical character will
 have about 10 curves (each curve consists of at least 20 characters).
 This can make the pdf files large and when the pdf is viewed the
 viewer does not normally draw those fine curves very well (turning on
 Smooth Line Art in the Acrobat preferences will fix this).
 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.
        </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).
 This setting will not affect the printing of your document, which should be OK in any case, but will only affect the quality of the screen display.</p>
      </section>
      <section id="svg-scaling">
        <title>Scaling</title>
        <p>Currently, SVG images are rendered with the dimensions specified <em>in the SVG file</em>, within the viewport specified in the fo:external-graphic element.
 For everything to work properly, the two should be equal.
 The SVG standard leaves this issue as an implementation detail.
 FOP will probably implement a scaling mechanism in the future.</p>
      </section>
      <section id="svg-problems">
        <title>Known Problems</title>
        <ul>
          <li>
 soft mask transparency is combined with white so that it looks better
 on pdf 1.3 viewers but this causes the soft mask to be slightly lighter
 or darker on pdf 1.4 viewers
          </li>
          <li>
 there is some problem with a gradient inside a pattern causing a pdf
 error when viewed in acrobat 5
          </li>
          <li>
 text is not always handled correctly, it may select the wrong font
 especially if characters have multiple fonts in the font list
          </li>
          <li>
 more pdf text handling could be implemented
 It could draw the string using the attributed character iterator
 to handle tspans and other simple changes of text.
          </li>
          <li>
 JPEG images are not inserted directly into the pdf document
 This area has not been implemented yet since the appropriate
 method in batik is static
          </li>
          <li>
 Uniform transparency for images and other svg elements that are converted
 into a raster graphic are not drawn properly in PDF. The image is opaque.
          </li>
        </ul>
      </section>
    </section>
    <section id="tiff">
      <title>TIFF</title>
      <p>TIFF images with JPEG or CCITT content are passed through by FOP natively. Other TIFF subformats are handled by JAI.</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>
      <ul>
        <li>If no dimensions are given, FOP uses a default value of 72 dpi to compute the graphic's dimensions. For example, suppose a graphic 300 pixels wide and 400 pixels high. FOP will render the graphic at 4.167 inches wide, 5.555 inches high, with an apparent resolution of 72 dpi.</li>
        <li>If only one dimension is given, FOP by default uses the same aspect ratio to compute the other dimension (to avoid the appearance of stretching). For example, suppose a graphic 300 pixels wide and 400 pixels high, for which content-width = ".5in". FOP will compute the content-height = .667 inches, and will render the graphic at that size, with an apparent resolution of 600 dpi.</li>
        <li>If both dimensions are given, FOP simply renders the image in that space. For example, suppose a graphic 300 pixels wide and 400 pixels high, for which content-width = "3in" and content-height = "4in". FOP will render the graphic at that size, with an apparent resolution of 100 dpi.</li>
      </ul>
      <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/pdfencryption.xml
+++ b/src/documentation/content/xdocs/pdfencryption.xml
@@ -0,0 +1,118 @@
 <?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>PDF encryption.</title>
    <authors>
      <person name="J.Pietschmann" email="pietsch@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.
      </p>
      <p>
        For further information about features and restrictions regarding PDF
        encryption, look at the documentation coming with Adobe Acrobat or the
        technical documentation on the Adobe web site.
      </p>
    </section>
    <section>
      <title>Usage</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.
      </p>
      <p>
        If no owner password has been supplied but FOP was asked to apply some
        restrictions, a random password is used.
      </p>
      <p>
        A user password, supplied with the <code>-u</code> option, will
        cause the PDF display software to ask the reader for this password in
        order to view the contents of the document. If no user password was
        supplied, viewing the content is not restricted.
      </p>
      <p>
        Further restrictions can be imposed by using the <code>-noprint</code>,
        <code>-nocopy</code>, <code>-noedit</code> and
        <code>-noannotations</code> options, which disable printing, copying
        text, editing in Adobe Acrobat and making annotations, respectively.
      </p>
    </section>
    <section>
      <title>Environment</title>
      <p>
        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.
      </p>
      <p>
        Cryptography support must also be present at run time. In particular, a
        provider for the RC4 cipher is needed. Unfortunately, the sample JCE
        provider in Sun's JDK 1.4 does <strong>not</strong> provide RC4. If you
        get a message saying
      </p>
      <source>"Cannot find any provider supporting RC4"</source>
      <p>
        then you don't have the needed support.
      </p>
      <p>
        There are several commercial and a few Open Source packages which
        provide RC4. A pure Java implementation is produced by <link
        href="http://www.bouncycastle.org/">The Legion of the Bouncy
        Castle</link>. <link
        href="http://www.mozilla.org/projects/security/pki/jss/">Mozilla
        JSS</link> is an interface to a native implementation.
      </p>
    </section>
    <section id="install_crypto">
      <title>Installing a crypto provider</title>
      <p>
        The pure Java implementation from <link
        href="http://www.bouncycastle.org/">Bouncy Castle</link> is easy to
        install.
      </p>
      <ol>
        <li>
          Download the binary distribution for your JDK version. If you have JDK
          1.3 or earlier you must also download a JCE from the same page.
        </li>
        <li>
          Unpack the distribution. Add the jar file to your classpath. A
          convenient way to use the jar on Linux is to simply drop it into the
          FOP lib directory, it will be automatically picked up by
          <code>fop.sh</code>.  If you have JDK 1.3 or earlier don't forget to
          install the JCE as well.
        </li>
        <li>
          Open the <code>java.security</code> file and add<br/>
          <code>security.provider.6=org.bouncycastle.jce.provider.BouncyCastleProvider</code>,<br/>
          preferably at the end of the block defining the other crypto
          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>
    </section>
  </body>
 </document>
--- a/src/documentation/resources/stylesheets/compliance2fo.xsl
+++ b/src/documentation/resources/stylesheets/compliance2fo.xsl
@@ -0,0 +1,380 @@
 <?xml version="1.0" encoding="UTF-8"?>

 <!-- This stylesheet is based on the forrest document2fo.xsl and attempts
     to mimic its style-->

 <xsl:stylesheet
    version="1.0"
    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:fo="http://www.w3.org/1999/XSL/Format">

 <xsl:import href="../../skins/common/xslt/fo/document2fo.xsl"/>

 <xsl:output method="xml"/>

 <xsl:preserve-space elements="*"/>

 <xsl:variable name="cell-yes" select="'rgb(153, 204, 255)'"/>
 <xsl:variable name="cell-no" select="'rgb(255, 153, 204)'"/>
 <xsl:variable name="cell-partial" select="'rgb(192, 192, 192)'"/>
 <xsl:variable name="cell-normal" select="'transparent'"/>

 <xsl:template match="compliance">
 <!-- Contents of this template are copied verbatim from Forrest document2fo.xsl
 -->
 <!--  <xsl:template match="document"> -->
    <fo:title><xsl:value-of select="head/title"/></fo:title>

    <fo:static-content flow-name="first-footer">
      <fo:block
        border-top="0.25pt solid"
        padding-before="6pt"
        text-align="center">
        <xsl:apply-templates select="footer"/>
      </fo:block>
      <fo:block
        text-align="start">
        Page <fo:page-number/>
      </fo:block>
      <xsl:call-template name="info"/>
    </fo:static-content>

    <fo:static-content flow-name="even-header">
      <fo:block
        text-align="end"
        font-style="italic">
        <xsl:value-of select="header/title"/>
      </fo:block>
    </fo:static-content>

    <fo:static-content flow-name="even-footer">
      <fo:block
        border-top="0.25pt solid"
        padding-before="6pt"
        text-align="center">
        <xsl:apply-templates select="footer"/>
      </fo:block>
      <fo:block
        text-align="end">
        Page <fo:page-number/>
      </fo:block>
      <xsl:call-template name="info"/>
    </fo:static-content>

    <fo:static-content flow-name="odd-header">
      <fo:block
        text-align="start"
        font-style="italic">
        <xsl:value-of select="header/title"/>
      </fo:block>
    </fo:static-content>

    <fo:static-content flow-name="odd-footer">
      <fo:block
        border-top="0.25pt solid"
        padding-before="6pt"
        text-align="center">
        <xsl:apply-templates select="footer"/>
      </fo:block>
      <fo:block
        text-align="start">
        Page <fo:page-number/>
      </fo:block>
      <xsl:call-template name="info"/>
    </fo:static-content>

    <fo:flow flow-name="xsl-region-body">
      <fo:block
        padding-before="24pt"
        padding-after="24pt"
        font-size="24pt"
        font-weight="bold"
        id="{generate-id()}">

        <xsl:value-of select="header/title"/>
      </fo:block>

      <fo:block
        text-align="justify"
        padding-before="18pt"
        padding-after="18pt">
        <xsl:apply-templates/>
      </fo:block>
    </fo:flow>
  </xsl:template>
 <!-- End of material copied from Forrest document2fo.xsl -->

 <xsl:template match="head">
  <fo:block
      font-size="18pt"
      text-align="center">
    <xsl:value-of select="/compliance/head/title"/>
  </fo:block>
 </xsl:template>

 <xsl:template match="body">
  <xsl:apply-templates select="standard"/>
 </xsl:template>

 <xsl:template match="standard">
  <fo:block
      font-size="16pt"
      text-align="left">
    <xsl:value-of select="@name"/>
  </fo:block>
  <xsl:apply-templates select="explanatory"/>
 <!-- Comment out temporarily - FOP failing on build
  <xsl:apply-templates select="level-1"/>
 -->
 </xsl:template>

 <xsl:template match="level-1">
  <fo:block
      font-size="16pt"
      text-align="left">
    <xsl:value-of select="@name"/>
  </fo:block>
  <xsl:apply-templates select="explanatory"/>
  <fo:table table-layout="fixed" width="6.0in">
    <!-- FIXME: Apache FOP must have column widths specified at present,
         this section can be removed when this limitation is removed from Fop.
         Unfortunately, this means that each column is a fixed width,
         but at least the table displays! -->
    <fo:table-column column-width="1.5in"/>
    <fo:table-column column-width=".5in"/>
    <fo:table-column column-width=".5in"/>
    <fo:table-column column-width=".5in"/>
    <fo:table-column column-width="2.5in"/>

    <fo:table-header>
      <fo:table-row>
        <fo:table-cell number-rows-spanned="2">
          <fo:block>
            <xsl:value-of select="@compliance-item-desc"/>
          </fo:block>
        </fo:table-cell>
        <fo:table-cell number-columns-spanned="3">
          <fo:block>Support</fo:block>
        </fo:table-cell>
        <fo:table-cell number-rows-spanned="2">
          <fo:block>Comments</fo:block>
        </fo:table-cell>
      </fo:table-row>
      <fo:table-row>
        <fo:table-cell>
          <fo:block>
            <xsl:value-of select="/compliance/body/standard/@compliance-level-1-desc"/>
          </fo:block>
        </fo:table-cell>
        <fo:table-cell>
          <fo:block>
            <xsl:value-of select="/compliance/body/standard/@compliance-level-2-desc"/>
          </fo:block>
        </fo:table-cell>
        <fo:table-cell>
          <fo:block>
            <xsl:value-of select="/compliance/body/standard/@compliance-level-3-desc"/>
          </fo:block>
        </fo:table-cell>
      </fo:table-row>
    </fo:table-header>
    <fo:table-body>
    <xsl:apply-templates select="level-2"/>
    </fo:table-body>
  </fo:table>
 </xsl:template>

 <xsl:template match="explanatory">
  <xsl:for-each select="p">
    <fo:block>
      <xsl:apply-templates/>
    </fo:block>
  </xsl:for-each>
 </xsl:template>

 <xsl:template match="level-2">
  <fo:table-row>
    <fo:table-cell number-columns-spanned="5" background-color="rgb(255, 204, 102)">
      <fo:block>
        <xsl:value-of select="@name"/>
      </fo:block>
    </fo:table-cell>
  </fo:table-row>
  <xsl:apply-templates select="level-3"/>
 </xsl:template>

 <xsl:template match="level-3">
  <fo:table-row>
    <fo:table-cell>
      <fo:block>
        <xsl:value-of select="@name"/>
      </fo:block>
    </fo:table-cell>
    <xsl:variable name="cell-attributes-level-1">
      <xsl:choose>
        <xsl:when test="@comply='yes'">
          <xsl:value-of select="$cell-yes"/>
        </xsl:when>
        <xsl:when test="@comply='no'">
          <xsl:choose>
            <xsl:when test="@compliance-level > 1">
              <xsl:value-of select="$cell-yes"/>
            </xsl:when>
            <xsl:otherwise>
              <xsl:value-of select="$cell-no"/>
            </xsl:otherwise>
          </xsl:choose>
        </xsl:when>
        <xsl:when test="@comply='partial'">
          <xsl:choose>
            <xsl:when test="@compliance-level > 1">
              <xsl:value-of select="$cell-yes"/>
            </xsl:when>
            <xsl:otherwise>
              <xsl:value-of select="$cell-partial"/>
            </xsl:otherwise>
          </xsl:choose>
        </xsl:when>
        <xsl:otherwise>
          <xsl:value-of select="$cell-normal"/>
        </xsl:otherwise>
      </xsl:choose>
    </xsl:variable>
    <fo:table-cell>
      <xsl:attribute name="background-color">
        <xsl:value-of select="$cell-attributes-level-1"/>
      </xsl:attribute>
      <fo:block>
        <xsl:choose>
          <xsl:when test="@compliance-level=1">
            <xsl:value-of select="@comply"/>
          </xsl:when>
          <xsl:otherwise>
            <xsl:text>.</xsl:text>
          </xsl:otherwise>
        </xsl:choose>
      </fo:block>
    </fo:table-cell>
    <xsl:variable name="cell-attributes-level-2">
      <xsl:choose>
        <xsl:when test="@comply='yes'">
          <xsl:value-of select="$cell-yes"/>
        </xsl:when>
        <xsl:when test="@comply='no'">
          <xsl:choose>
            <xsl:when test="@compliance-level > 2">
              <xsl:value-of select="$cell-yes"/>
            </xsl:when>
            <xsl:otherwise>
              <xsl:value-of select="$cell-no"/>
            </xsl:otherwise>
          </xsl:choose>
        </xsl:when>
        <xsl:when test="@comply='partial'">
          <xsl:choose>
            <xsl:when test="@compliance-level > 2">
              <xsl:value-of select="$cell-yes"/>
            </xsl:when>
            <xsl:otherwise>
              <xsl:value-of select="$cell-partial"/>
            </xsl:otherwise>
          </xsl:choose>
        </xsl:when>
        <xsl:otherwise>
          <xsl:value-of select="$cell-normal"/>
        </xsl:otherwise>
      </xsl:choose>
    </xsl:variable>
    <fo:table-cell>
      <xsl:attribute name="background-color">
        <xsl:value-of select="$cell-attributes-level-2"/>
      </xsl:attribute>
      <fo:block>
        <xsl:choose>
          <xsl:when test="@compliance-level=2">
            <xsl:value-of select="@comply"/>
          </xsl:when>
          <xsl:otherwise>
            <xsl:text>.</xsl:text>
          </xsl:otherwise>
        </xsl:choose>
      </fo:block>
    </fo:table-cell>
    <xsl:variable name="cell-attributes-level-3">
      <xsl:choose>
        <xsl:when test="@comply='yes'">
          <xsl:value-of select="$cell-yes"/>
        </xsl:when>
        <xsl:when test="@comply='no'">
          <xsl:choose>
            <xsl:when test="@compliance-level > 3">
              <xsl:value-of select="$cell-yes"/>
            </xsl:when>
            <xsl:otherwise>
              <xsl:value-of select="$cell-no"/>
            </xsl:otherwise>
          </xsl:choose>
        </xsl:when>
        <xsl:when test="@comply='partial'">
          <xsl:choose>
            <xsl:when test="@compliance-level > 3">
              <xsl:value-of select="$cell-yes"/>
            </xsl:when>
            <xsl:otherwise>
              <xsl:value-of select="$cell-partial"/>
            </xsl:otherwise>
          </xsl:choose>
        </xsl:when>
        <xsl:otherwise>
          <xsl:value-of select="$cell-normal"/>
        </xsl:otherwise>
      </xsl:choose>
    </xsl:variable>
    <fo:table-cell>
      <xsl:attribute name="background-color">
        <xsl:value-of select="$cell-attributes-level-3"/>
      </xsl:attribute>
      <fo:block>
        <xsl:choose>
          <xsl:when test="@compliance-level=3">
            <xsl:value-of select="@comply"/>
          </xsl:when>
          <xsl:otherwise>
            <xsl:text>.</xsl:text>
          </xsl:otherwise>
        </xsl:choose>
      </fo:block>
    </fo:table-cell>
    <xsl:choose>
      <xsl:when test="count(comment) > 0">
        <fo:table-cell text-align="left">
          <fo:list-block>
            <xsl:for-each select="comment">
              <fo:list-item>
                <fo:list-item-label>
                  <fo:block>*</fo:block>
                </fo:list-item-label>
                <fo:list-item-body>
                  <fo:block>
                    <xsl:value-of select="."/>
                  </fo:block>
                </fo:list-item-body>
             </fo:list-item>
           </xsl:for-each>
          </fo:list-block>
        </fo:table-cell>
      </xsl:when>
      <xsl:otherwise>
        <fo:table-cell text-align="center">
          <fo:block>
            <xsl:text>.</xsl:text>
          </fo:block>
        </fo:table-cell>
      </xsl:otherwise>
    </xsl:choose>
  </fo:table-row>
 </xsl:template>

 </xsl:stylesheet>

 <!-- Last Line of $RCSfile$ -->
--- a/src/documentation/resources/stylesheets/compliance2html.xsl
+++ b/src/documentation/resources/stylesheets/compliance2html.xsl
@@ -0,0 +1,421 @@
 <?xml version="1.0" encoding="UTF-8"?>

 <!-- $Id$ -->

 <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

 <xsl:preserve-space elements="*"/>

 <xsl:template match="/compliance">
 <!-- Forrest/Cocoon will place the output from this stylesheet inside of a
     larger html document. The output here is all within one <div> tag. -->
  <div class="content">
  <xsl:apply-templates select="head"/>
  <xsl:apply-templates select="body"/>
  </div>
 </xsl:template>

 <xsl:template match="head">
      <head>
      <meta http-equiv="Content-Language" content="en-us"/>
      <meta http-equiv="Content-Type" content="text/html; charset=windows-1252"/>
      <link type="text/css" href="skin/page.css" rel="stylesheet"/>
      <style>
      &lt;!--
      .yes         { background-color: #99CCFF }
      .no          { background-color: #FF99CC }
      .partial     { background-color: #C0C0C0 }
      .category    { background-color: #FFCC66;
                     font-size: 1.2em }
      --&gt;
      </style>
      </head>
 </xsl:template>

 <xsl:template match="body">
  <table class="title" summary="">
    <tr>
    <td valign="middle">
      <h1><xsl:value-of select="/compliance/head/title"/></h1>
    </td>
    <td nowrap="nowrap" width="40" align="center">
      <a class="dida" href="compliance.pdf"><img alt="PDF" src="skin/images/printer.gif" border="0"/><br/>PDF</a>
    </td>
  </tr>
  </table>
  <ul class="minitoc">
    <xsl:for-each select="standard">
      <a>
        <xsl:attribute name="href">
          <xsl:text>#</xsl:text>
          <xsl:value-of select="@ref-name"/>
        </xsl:attribute>
        <li><xsl:value-of select="@name"/></li>
      </a>
    </xsl:for-each>
  </ul>
  <xsl:apply-templates select="standard"/>
 </xsl:template>

 <xsl:template match="standard">
  <h2>
    <a>
      <xsl:attribute name="target">
        <xsl:value-of select="@baseURL"/>
      </xsl:attribute>
      <xsl:attribute name="href">
        <xsl:value-of select="@baseURL"/>
      </xsl:attribute>
      <xsl:attribute name="name">
        <xsl:value-of select="@ref-name"/>
      </xsl:attribute>
      <xsl:value-of select="@name"/>
    </a>
  </h2>
  <xsl:apply-templates select="explanatory"/>
  <ul class="minitoc">
    <xsl:for-each select="/compliance/body/standard/level-1">
      <li>
        <xsl:variable name="href-level-1">
          <xsl:text>#</xsl:text>
          <xsl:value-of select="../@ref-name"/>
          <xsl:text>-</xsl:text>
          <xsl:value-of select="@ref-name"/>
        </xsl:variable>
        <a>
          <xsl:attribute name="href">
            <xsl:value-of select="$href-level-1"/>
          </xsl:attribute>
          <xsl:value-of select="@name"/>
        </a>
      </li>
      <ul>
        <xsl:for-each select="level-2">
          <li>
            <xsl:variable name="href-level-2">
              <xsl:text>#</xsl:text>
              <xsl:value-of select="../../@ref-name"/>
              <xsl:text>-</xsl:text>
              <xsl:value-of select="../@ref-name"/>
              <xsl:text>-</xsl:text>
              <xsl:value-of select="@ref-name"/>
            </xsl:variable>
            <strong>
            <a>
              <xsl:attribute name="href">
                <xsl:value-of select="$href-level-2"/>
              </xsl:attribute>
              <xsl:value-of select="@name"/>
            </a>
            <xsl:text>: </xsl:text>
            </strong>
            <xsl:for-each select="level-3">
              <xsl:variable name="href-level-3">
                <xsl:text>#</xsl:text>
                <xsl:value-of select="../../../@ref-name"/>
                <xsl:text>-</xsl:text>
                <xsl:value-of select="../../@ref-name"/>
                <xsl:text>-</xsl:text>
                <xsl:value-of select="@name"/>
              </xsl:variable>
              <a>
                <xsl:attribute name="href">
                  <xsl:value-of select="$href-level-3"/>
                </xsl:attribute>
                <xsl:value-of select="@name"/>
              </a>
              <xsl:choose>
                <xsl:when test="position()=last()"></xsl:when>
                <xsl:otherwise><xsl:text>, </xsl:text></xsl:otherwise>
              </xsl:choose>
            </xsl:for-each>
          </li>
        </xsl:for-each>
      </ul>
    </xsl:for-each>
  </ul>
  <xsl:apply-templates select="level-1"/>
 </xsl:template>

 <xsl:template match="level-1">
  <h3>
    <xsl:variable name="target-level-1">
      <xsl:text>#</xsl:text>
      <xsl:value-of select="../@ref-name"/>
      <xsl:text>-</xsl:text>
      <xsl:value-of select="@ref-name"/>
    </xsl:variable>
    <a>
      <xsl:attribute name="name">
        <xsl:value-of select="$target-level-1"/>
      </xsl:attribute>
      <xsl:value-of select="@name"/>
    </a>
    <xsl:if test="@citation">
      <xsl:text> (</xsl:text>
      <a>
        <xsl:attribute name="target">
          <xsl:apply-templates select="../@baseURL"/>
        </xsl:attribute>
        <xsl:attribute name="href">
          <xsl:apply-templates select="../@baseURL"/>/<xsl:apply-templates select="@extURL"/>
        </xsl:attribute>
        <xsl:value-of select="@citation"/>
      </a>
      <xsl:text>)</xsl:text>
    </xsl:if>
  </h3>
  <xsl:apply-templates select="explanatory"/>
  <table border="1">
  <tr>
    <th rowspan="2">
      <p><xsl:value-of select="@compliance-item-desc"/></p>
    </th>
    <th align="center" rowspan="2">
      Citation
    </th>
    <th align="center" colspan="3">
      Support
    </th>
    <th rowspan="2">
      Comments
    </th>
  </tr>
  <tr>
    <th align="center">
      <xsl:value-of select="/compliance/body/standard/@compliance-level-1-desc"/>
    </th>
    <th align="center">
      <xsl:value-of select="/compliance/body/standard/@compliance-level-2-desc"/>
    </th>
    <th align="center">
      <xsl:value-of select="/compliance/body/standard/@compliance-level-3-desc"/>
    </th>
  </tr>
  <xsl:apply-templates select="level-2"/>
  </table>
 </xsl:template>

 <xsl:template match="explanatory">
  <xsl:for-each select="p">
    <p>
      <xsl:apply-templates/>
    </p>
  </xsl:for-each>
 </xsl:template>

 <xsl:template match="level-2">
  <tr>
    <td colspan="6" class="category">
      <xsl:variable name="target-level-2">
        <xsl:text>#</xsl:text>
        <xsl:value-of select="../../@ref-name"/>
        <xsl:text>-</xsl:text>
        <xsl:value-of select="../@ref-name"/>
        <xsl:text>-</xsl:text>
        <xsl:value-of select="@ref-name"/>
      </xsl:variable>
      <a>
        <xsl:attribute name="name">
          <xsl:value-of select="$target-level-2"/>
        </xsl:attribute>
        <xsl:value-of select="@name"/>
      </a>
    <xsl:if test="@citation">
      <xsl:text> (</xsl:text>
      <a>
        <xsl:attribute name="target">
          <xsl:apply-templates select="../../@baseURL"/>
        </xsl:attribute>
        <xsl:attribute name="href">
          <xsl:apply-templates select="../../@baseURL"/>/<xsl:apply-templates select="@extURL"/>
        </xsl:attribute>
        <xsl:value-of select="@citation"/>
      </a>
      <xsl:text>)</xsl:text>
    </xsl:if>
    </td>
  </tr>
  <xsl:apply-templates select="level-3"/>
 </xsl:template>

 <xsl:template match="level-3">
  <tr>
    <td>
      <xsl:variable name="target-name">
        <xsl:text>#</xsl:text>
        <xsl:value-of select="../../../@ref-name"/>
        <xsl:text>-</xsl:text>
        <xsl:value-of select="../../@ref-name"/>
        <xsl:text>-</xsl:text>
        <xsl:value-of select="@name"/>
      </xsl:variable>
      <a>
        <xsl:attribute name="name">
          <xsl:value-of select="$target-name"/>
        </xsl:attribute>
        <xsl:value-of select="@name"/>
      </a>
    </td>
    <td align="center">
      <xsl:choose>
        <xsl:when test="@citation">
          <a>
            <xsl:attribute name="target">
              <xsl:apply-templates select="../../../@baseURL"/>
            </xsl:attribute>
            <xsl:attribute name="href">
              <xsl:apply-templates select="../../../@baseURL"/>/<xsl:apply-templates select="@extURL"/>
            </xsl:attribute>
            <xsl:value-of select="@citation"/>
          </a>
        </xsl:when>
        <xsl:otherwise>
          <xsl:text>.</xsl:text>
        </xsl:otherwise>
      </xsl:choose>
    </td>
    <td align="center">
      <xsl:attribute name="class">
        <xsl:choose>
          <xsl:when test="@comply='yes'">
            <xsl:text>yes</xsl:text>
          </xsl:when>
          <xsl:when test="@comply='no'">
            <xsl:choose>
              <xsl:when test="@compliance-level > 1">
                <xsl:text>yes</xsl:text>
              </xsl:when>
              <xsl:otherwise>
                <xsl:text>no</xsl:text>
              </xsl:otherwise>
            </xsl:choose>
          </xsl:when>
          <xsl:when test="@comply='partial'">
            <xsl:choose>
              <xsl:when test="@compliance-level > 1">
                <xsl:text>yes</xsl:text>
              </xsl:when>
              <xsl:otherwise>
                <xsl:text>partial</xsl:text>
              </xsl:otherwise>
            </xsl:choose>
          </xsl:when>
          <xsl:otherwise>
            <xsl:text></xsl:text>
          </xsl:otherwise>
        </xsl:choose>
      </xsl:attribute>
      <xsl:choose>
        <xsl:when test="@compliance-level=1">
          <xsl:value-of select="@comply"/>
        </xsl:when>
        <xsl:otherwise>
          <xsl:text>.</xsl:text>
        </xsl:otherwise>
      </xsl:choose>
    </td>
    <td align="center">
      <xsl:attribute name="class">
        <xsl:choose>
          <xsl:when test="@comply='yes'">
            <xsl:text>yes</xsl:text>
          </xsl:when>
          <xsl:when test="@comply='no'">
            <xsl:choose>
              <xsl:when test="@compliance-level > 2">
                <xsl:text>yes</xsl:text>
              </xsl:when>
              <xsl:otherwise>
                <xsl:text>no</xsl:text>
              </xsl:otherwise>
            </xsl:choose>
          </xsl:when>
          <xsl:when test="@comply='partial'">
            <xsl:choose>
              <xsl:when test="@compliance-level > 2">
                <xsl:text>yes</xsl:text>
              </xsl:when>
              <xsl:otherwise>
                <xsl:text>partial</xsl:text>
              </xsl:otherwise>
            </xsl:choose>
          </xsl:when>
          <xsl:otherwise>
            <xsl:text></xsl:text>
          </xsl:otherwise>
        </xsl:choose>
      </xsl:attribute>
      <xsl:choose>
        <xsl:when test="@compliance-level=2">
          <xsl:value-of select="@comply"/>
        </xsl:when>
        <xsl:otherwise>
          <xsl:text>.</xsl:text>
        </xsl:otherwise>
      </xsl:choose>
    </td>
    <td align="center">
      <xsl:attribute name="class">
        <xsl:choose>
          <xsl:when test="@comply='yes'">
            <xsl:text>yes</xsl:text>
          </xsl:when>
          <xsl:when test="@comply='no'">
            <xsl:choose>
              <xsl:when test="@compliance-level > 3">
                <xsl:text>yes</xsl:text>
              </xsl:when>
              <xsl:otherwise>
                <xsl:text>no</xsl:text>
              </xsl:otherwise>
            </xsl:choose>
          </xsl:when>
          <xsl:when test="@comply='partial'">
            <xsl:choose>
              <xsl:when test="@compliance-level > 3">
                <xsl:text>yes</xsl:text>
              </xsl:when>
              <xsl:otherwise>
                <xsl:text>partial</xsl:text>
              </xsl:otherwise>
            </xsl:choose>
          </xsl:when>
          <xsl:otherwise>
            <xsl:text></xsl:text>
          </xsl:otherwise>
        </xsl:choose>
      </xsl:attribute>
      <xsl:choose>
        <xsl:when test="@compliance-level=3">
          <xsl:value-of select="@comply"/>
        </xsl:when>
        <xsl:otherwise>
          <xsl:text>.</xsl:text>
        </xsl:otherwise>
      </xsl:choose>
    </td>
    <xsl:choose>
      <xsl:when test="count(comment) > 0">
        <td align="left">
          <ul>
            <xsl:for-each select="comment">
              <li>
                <xsl:value-of select="."/>
             </li>
           </xsl:for-each>
          </ul>
        </td>
      </xsl:when>
      <xsl:otherwise>
        <td align="center">
          <xsl:text>.</xsl:text>
        </td>
      </xsl:otherwise>
    </xsl:choose>
  </tr>
 </xsl:template>

 </xsl:stylesheet>

 <!-- Last Line of $RCSFile -->