updated docs from head (for 0.20.50rc3)

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

src/documentation/content/xdocs/book.xml

@@ -9,46 +9,43 @@
         xmlns:xlink="http://www.w3.org/1999/xlink">
 
         <menu label="About">
-          <menu-item label="Index" href="index.html"/>
+          <menu-item label="Home" href="index.html"/>
           <menu-item label="News" href="news.html"/>
           <menu-item label="Logo contest" href="logocontest.html"/>
-          <menu-item label="FAQs" href="faq.html"/>
-          <menu-item label="Download" href="download.html"/>
-          <menu-item label="Release Notes" href="relnotes.html"/>
-          <menu-item label="Getting Help" href="gethelp.html"/>
-          <menu-item label="Examples" href="examples.html"/>
         </menu>
 
         <menu label="Project">
           <menu-item label="Status" href="status.html"/>
+          <menu-item label="Changes" href="changes.html"/>
+          <menu-item label="Todo" href="todo.html"/>
         </menu>
 
         <menu label="Using FOP">
-          <menu-item label="Running" href="running.html"/>
-          <menu-item label="Embedding" href="embedding.html"/>
-          <menu-item label="Output Formats" href="output.html"/>
-          <menu-item label="Compliance" href="compliance.html"/>
-          <menu-item label="Implemented" href="implemented.html"/>
-          <menu-item label="Limitations" href="limitations.html"/>
+          <menu-item label="Release Notes" href="relnotes.html"/>
+          <menu-item label="Download" href="download.html"/>
+          <menu-item label="Build" href="compiling.html"/>
+          <menu-item label="Configure" href="configuration.html"/>
+          <menu-item label="Run" href="running.html"/>
+          <menu-item label="Embed" href="embedding.html"/>
+          <menu-item label="Ant task" href="anttask.html"/>
         </menu>
 
-        <menu label="Extras">
-          <menu-item label="SVG" href="svg.html"/>
-          <menu-item label="Extensions" href="extensions.html"/>
+        <menu label="Features">
+          <menu-item label="Compliance" href="compliance.html"/>
+          <menu-item label="Output Targets" href="output.html"/>
+          <menu-item label="PDF encryption" href="pdfencryption.html"/>
+          <menu-item label="Graphics" href="graphics.html"/>
           <menu-item label="Fonts" href="fonts.html"/>
-          <menu-item label="Configuration" href="configuration.html"/>
-        </menu>
-
-        <menu label="Developing">
-          <menu-item label="Getting Involved" href="involved.html"/>
-          <menu-item label="Compiling" href="compiling.html"/>
-          <menu-item label="Testing" href="testing.html"/>
+          <menu-item label="Extensions" href="extensions.html"/>
         </menu>
 
         <menu label="Resources">
+          <menu-item label="Getting Help" href="gethelp.html"/>
+          <menu-item label="FAQs" href="faq.html"/>
+          <menu-item label="XSL-FO" href="fo.html"/>
+          <menu-item label="Examples" href="examples.html"/>
           <menu-item label="Bugs" href="bugs.html"/>
-          <menu-item label="Resources" href="resources.html"/>
           <menu-item label="License" href="license.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-item label="Other" href="resources.html"/>
         </menu>
     </book>

src/documentation/content/xdocs/bugs.xml

@@ -4,57 +4,46 @@
 
 <document>
   <header>
-    <title>Bugs</title>
+    <title>Bugs and Other Trackable Issues</title>
   </header>
   <body>
-    <section>
-      <title>Bugs Already Reported</title>
+    <p>
+      Information on this page applies to enhancement requests and other trackable
+issues as well as bugs.
+    </p>
+    <section id="issues_existing">
+      <title>Reported Issues</title>
       <p>A list of unresolved reported bugs can be found at
 <link 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">FOP
-Open Bugs (Bugzilla)</link>.</p>
+Open Bugs (Bugzilla)</link>. If you have an interest in an issue already
+reported, please consider the following:
+      </p>
+      <ul>
+        <li>If you have insight that may help developers solve an existing problem,
+please add comments and/or file attachments to the existing issue.</li>
+        <li>If you would like to track the status of the issue, consider adding
+your email address to the list of "CC" recipients, so that you will receive
+an email as changes are made to the issue.</li>
+      </ul>
     </section>
-    <section>
-      <title>Reporting New Bugs</title>
+    <section id="issues_new">
+      <title>Unreported Issues (Reporting New Issues)</title>
       <p>User reports of bugs and requests for enhancements are extremely
 important parts of FOP development, and we appreciate the time you take to help
-us track these issues down.
-To help us ensure that the bug database is as useful as it should be, please
-use the following checklist if you are considering reporting a new bug:</p>
-        <ul>
-          <li>Is your issue really a request to comply with some aspect of the
-XSL-FO standard?
-If so, please do not enter a bug report.
-The developers already carefully track which standard requirements have been
-implemented.
-Other enhancement requests are welcome (although they are not technically
-"bugs", they are entered and tracked in the same system -- just be sure to mark
-the issue as an enhancement).</li>
-          <li>Is your issue addressed by an <link
-href="http://xml.apache.org/fop/faq.html">FAQ</link>? If so, please do not
-enter a bug report unless the FAQ did not adequately address your issue.</li>
-          <li>Has this bug already been reported?
-See section above for a list of bugs that have already been reported.
-If the bug has already been reported, please do not open a new bug report.
-Reporting the same bug twice will only slow the development team down.
-However, if you have insight that may help developers track an existing problem,
-please add comments and/or file attachments to the existing bug.</li>
-          <li>Do you know how to write a good bug report?
-Please review the
-<link href="http://nagoya.apache.org/bugzilla/bugwritinghelp.html">Apache Bug
-Writing Guidelines</link> before submitting your report.</li>
-          <li>If, and only if, you have passed all of the above steps, please
-enter a new bug report at
-<link href="http://nagoya.apache.org/bugzilla/enter_bug.cgi?product=Fop">The
-FOP bug database (Bugzilla)</link>.
+us track these issues down.</p>
+      <ul>
+        <li>To help us ensure that the bug database is as useful as it should be, please
+use the <link href="gethelp.html">Getting Help</link> checklist to determine whether a bug report should be entered.</li>
+        <li>Review the <link href="http://nagoya.apache.org/bugzilla/bugwritinghelp.html">Apache Bug Writing Guidelines</link> before submitting your report.</li>
+        <li>Enter a new issue report at <link href="http://nagoya.apache.org/bugzilla/enter_bug.cgi?product=Fop">The FOP issue database (Bugzilla)</link>.
 You will be asked to login to an existing Bugzilla account or to create a new
 one.
 When entering the bug report, please make your description complete and concise.
 If appropriate, attach a minimal fo file to your report which demonstrates the
 problem.</li>
-          <li>After submission, a copy of your bug report will be automatically
+        <li>After submission, a copy of your bug report will be automatically
 sent to the FOP developer discussion list.</li>
-        </ul>
+      </ul>
     </section>
   </body>
 </document>
-

src/documentation/content/xdocs/compiling.xml

@@ -4,44 +4,71 @@
 
 <document>
   <header>
-    <title>Compiling FOP</title>
+    <title>FOP: Building from Source Code</title>
   </header>
   <body>
     <section>
-    <title>Compiling FOP</title>
-    <p>Compilation is started by executing build, either as a batch file on win32 (build.bat) or as a shell script on unix. Before you
-       can start one of these scripts, you have to setup your classpath and the environment variable JAVA_HOME (see below).</p>
-     <p> The compilation uses Ant,
-       a replacement of make (you can find more information about Ant at
-       <link href="http://jakarta.apache.org/ant/">jakarta.apache.org</link>).
-        build.xml is the replacement of makefile. Look there for detailed information on the build
-        process and different targets. </p>
-       <p>A help screen is shown by calling "build usage".</p>
-       <p>If you only want to use FOP, you don't need to build it. A fop.jar comes with the distribution.</p>
-   <section>
-     <title>Setting up your classpath</title>
-     <note>You don't have to setup your classpath; all libraries needed to compile FOP are coming with
-              the distribution and are referenced by the build script, so you only need to care about them,
-              if you build FOP in any other way. See build.bat/build.sh for details. </note>
+      <title>Do You Need To Build?</title>
+      <p>FOP distributions are either pre-compiled binary or source.
+If you are using a binary distribution, it is already built and there is no need to build it again. See the <link href="download.html">Download Instructions</link> for information about whether a binary or source distribution is best for your needs.
+      </p>
     </section>
     <section>
-      <title>Setting of JAVA_HOME</title>
-      <p>You have to set the enviroment variable JAVA_HOME. It must point to your local JDK
-      root directory. This is true, even if you use JDK 1.2 or above, which normally don't need this
-      setting. It is used by Ant, the compilation software.</p>
-    </section>
+      <title>Set Up Your Environment</title>
+      <section>
+        <title>JDK</title>
+          <p>
+            Building FOP requires a minimum Java Development Kit (JDK) of 1.3.
+          </p>
+      </section>
+      <section>
+        <title>CLASSPATH</title>
+        <p>There is no generally no need to setup a classpath.
+All libraries needed to compile FOP are included in the source distribution and are referenced by the build script.
+You will only need to adjust the classpath if you build FOP in some other way. See the build scripts (build.bat for Windows, and build.sh for Unix) for details.</p>
+      </section>
+      <section>
+        <title>JAVA_HOME</title>
+        <p>Ant, which is used by the build script, requires that the environment variable JAVA_HOME point to your local JDK root directory.
+This is true even if you use JDK 1.2 or above, which normally don't need this setting.</p>
+      </section>
+  </section>
+  <section>
+    <title>Run the "build" Script</title>
+    <p>Build FOP by executing the "build" script, which is located in the FOP root directory.
+The Windows batch file is build.bat, and the Unix shell script is build.sh.
+The examples below are for running the shell script, but except for the build file extension, the syntax is identical.</p>
+    <p>The build script uses <link href="http://jakarta.apache.org/ant/">Ant</link>, a popular java-based build tool.
+The file build.xml in the FOP root directory is the blueprint that Ant uses for the build.
+It contains information for numerous build targets, many of which are building blocks to more useful target, and others which are primarily used by the FOP developers.
+You may benefit from looking through this file to learn more about the various build targets.
+To obtain a complete list of useful build targets:</p>
+    <source>build.sh -projecthelp</source>
+    <p>The most useful targets are:</p>
+    <ul>
+      <li><strong>package</strong>: Generates the jar files (default). This is the normal build that produces a jar file usable for running FOP.</li>
+      <li><strong>clean </strong>: Cleans the build directory. This is useful for making sure that any build errors are cleaned up before starting a new build. It should not ordinarily be needed, but may be helpful if you are having problems with the build process itself.</li>
+      <li><strong>javadocs</strong>: Generates javadocs. This creates the FOP API documentation.</li>
+    </ul>
+    <p>To run the build:</p>
+    <source>build.sh [target ...]</source>
+    <p>For example to do a normal build for the package target (which is the default):</p>
+    <source>build.sh</source>
+    <p>OR</p>
+    <source>build.sh package</source>
+    <p>To clean the build directory first:</p>
+    <source>build.sh clean package</source>
+  </section>
   <section>
-    <title>Problems</title>
-    <p>If you have problems compiling FOP, please try this first: </p>
+    <title>Troubleshooting</title>
+    <p>If you have problems building FOP, please try the following:</p>
     <ul>
-      <li>delete the build directory completely and try a new build from scratch</li>
-      <li>check, whether you have an older version of xerces.jar, xalan.jar, batik.jar somewhere in
-          you classpath.</li>
-      </ul>
-      <p>If you still have problems, please look at the
-         page <link href="bugs.html">bugs</link>, for further help.</p>
+      <li>Run the build with the target of "clean", then rerun the build.</li>
+      <li>Delete the build directory completely, then rerun the build.</li>
+      <li>Make sure you do not have a non-FOP version of xerces.jar, xalan.jar, batik.jar, or another dependency product somewhere in your CLASSPATH.</li>
+      <li>If the build still fails, see the <link href="gethelp.html">Getting Help</link> page for further help.</li>
+    </ul>
   </section>
-</section>
-</body>
+  </body>
 </document>
 

src/documentation/content/xdocs/compliance.xml

@@ -1,21 +1,26 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE compliance PUBLIC "-//APACHE//DTD Compliance V1.0//EN"
-    "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-fop/src/documentation/resources/schema/dtd/compliance-v10.dtd?rev=1.3">
+    "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-fop/src/documentation/resources/schema/dtd/compliance-v10.dtd?rev=1.6">
 
 <compliance>
   <head>
     <title>FOP 0.20.4 Standards Compliance</title>
+    <subtitle>Progress Report on Standard Features Implemented</subtitle>
   </head>
   <body>
-    <standard name="W3C XSL-FO 1.0 Standard" baseURL="http://www.w3.org/TR/xsl/" compliance-level-1-desc="Basic" compliance-level-2-desc="Extended" compliance-level-3-desc="Complete">
+    <standard name="W3C XSL-FO 1.0 Standard" baseURL="http://www.w3.org/TR/xsl" compliance-level-1-desc="Basic" compliance-level-2-desc="Extended" compliance-level-3-desc="Complete" ref-name="fo">
       <explanatory>
-        <p>FOP's goal is to be compliant with the W3C XSL-FO 1.0 standard. There are three levels of compliance specified in the standard: basic, extended, and complete. In the tables below, blue indicates support at the specified level of compliance, and red indicates a lack of support.</p>
+        <p>One of FOP's design goals is conformance to the W3C XSL-FO 1.0 standard, which specifies three levels of "conformance": basic, extended, and complete.
+Although FOP does not currently conform to any of these levels, it is nevertheless a useful work-in-progress for many applications.
+The information presented here demonstrates FOP's progress toward the goal of conformance, which progress consists of implementation of specific objects and properties in the standard.
+The information presented is useful not only to the developers as a sort of "to do" list, but also for setting proper expectations for users and potential users.</p>
+        <p>In the tables below, blue indicates support at the specified level of conformance, and red indicates a lack of support.</p>
       </explanatory>
-      <level-1 name="XSL-FO Object Support" citation="§6" extURL="slice6.html#fo-section" compliance-item-desc="Object Name">
+      <level-1 name="XSL-FO Object Support" citation="§6" extURL="slice6.html#fo-section" compliance-item-desc="Object Name" ref-name="object">
         <explanatory>
           <p>The following is a summary of FOP's current support for the standard XSL-FO objects.</p>
         </explanatory>
-        <level-2 name="Declarations and Pagination and Layout Formatting Objects" citation="§6.4" extURL="slice6.html#section-N10029-Declarations-and-Pagination-and-Layout-Formatting-Objects">
+        <level-2 name="Declarations and Pagination and Layout Formatting Objects" citation="§6.4" extURL="slice6.html#section-N10029-Declarations-and-Pagination-and-Layout-Formatting-Objects" ref-name="decl">
           <level-3 name="root" citation="§6.4.2" extURL="slice6.html#fo_root" compliance-level="1" comply="yes"/>
           <level-3 name="declarations" citation="§6.4.3" extURL="slice6.html#fo_declarations" compliance-level="1" comply="no"/>
           <level-3 name="color-profile" citation="§6.4.4" extURL="slice6.html#fo_color-profile" compliance-level="2" comply="no"/>
@@ -36,11 +41,11 @@
           <level-3 name="static-content" citation="§6.4.19" extURL="slice6.html#fo_static-content" compliance-level="2" comply="yes"/>
           <level-3 name="title" citation="§6.4.20" extURL="slice6.html#fo_title" compliance-level="2" comply="no"/>
         </level-2>
-        <level-2 name="Block Formatting Objects" citation="§6.5" extURL="slice6.html#section-N12764-Block-level-Formatting-Objects">
+        <level-2 name="Block Formatting Objects" citation="§6.5" extURL="slice6.html#section-N12764-Block-level-Formatting-Objects" ref-name="block">
           <level-3 name="block" citation="§6.5.2" extURL="slice6.html#fo_block" compliance-level="1" comply="yes"/>
           <level-3 name="block-container" citation="§6.5.3" extURL="slice6.html#fo_block-container" compliance-level="2" comply="partial"/>
         </level-2>
-        <level-2 name="Inline Formatting Objects" citation="§6.6" extURL="slice6.html#section-N13277-Inline-level-Formatting-Objects">
+        <level-2 name="Inline Formatting Objects" citation="§6.6" extURL="slice6.html#section-N13277-Inline-level-Formatting-Objects" ref-name="inline">
           <level-3 name="bidi-override" citation="§6.6.2" extURL="slice6.html#fo_bidi-override" compliance-level="2" comply="no"/>
           <level-3 name="character" citation="§6.6.3" extURL="slice6.html#fo_character" compliance-level="1" comply="yes"/>
           <level-3 name="initial-property-set" citation="§6.6.4" extURL="slice6.html#fo_initial-property-set" compliance-level="2" comply="no"/>
@@ -57,7 +62,7 @@ the same line and after the page-number might not appear exactly where you
 want it to.</comment>
           </level-3>
         </level-2>
-        <level-2 name="Table Formatting Objects" citation="§6.7" extURL="slice6.html#section-N15442-Formatting-Objects-for-Tables">
+        <level-2 name="Table Formatting Objects" citation="§6.7" extURL="slice6.html#section-N15442-Formatting-Objects-for-Tables" ref-name="table">
           <level-3 name="table-and-caption" citation="§6.7.2" extURL="slice6.html#fo_table-and-caption" compliance-level="1" comply="no"/>
           <level-3 name="table" citation="§6.7.3" extURL="slice6.html#fo_table" compliance-level="1" comply="yes"/>
           <level-3 name="table-column" citation="§6.7.4" extURL="slice6.html#fo_table-column" compliance-level="1" comply="yes">
@@ -69,16 +74,16 @@ want it to.</comment>
           <level-3 name="table-body" citation="§6.7.8" extURL="slice6.html#fo_table-body" compliance-level="1" comply="yes"/>
           <level-3 name="table-row" citation="§6.7.9" extURL="slice6.html#fo_table-row" compliance-level="1" comply="yes"/>
           <level-3 name="table-cell" citation="§6.7.10" extURL="slice6.html#fo_table-cell" compliance-level="1" comply="yes">
-            <comment>must contain block-level FOs (cannot contain straight character data</comment>
+            <comment>must contain block-level FOs (cannot contain straight character data)</comment>
           </level-3>
         </level-2>
-        <level-2 name="List Formatting Objects" citation="§6.8" extURL="slice6.html#section-N17076-Formatting-Objects-for-Lists">
+        <level-2 name="List Formatting Objects" citation="§6.8" extURL="slice6.html#section-N17076-Formatting-Objects-for-Lists" ref-name="list">
           <level-3 name="list-block" citation="§6.8.2" extURL="slice6.html#fo_list-block" compliance-level="1" comply="yes"/>
           <level-3 name="list-item" citation="§6.8.3" extURL="slice6.html#fo_list-item" compliance-level="1" comply="yes"/>
           <level-3 name="list-item-body" citation="§6.8.4" extURL="slice6.html#fo_list-item-body" compliance-level="1" comply="yes"/>
           <level-3 name="list-item-label" citation="§6.8.5" extURL="slice6.html#fo_list-item-label" compliance-level="2" comply="yes"/>
         </level-2>
-        <level-2 name="Link and Multi Formatting Objects" citation="§6.9" extURL="slice6.html#section-N17805-Dynamic-Effects:-Link-and-Multi-Formatting-Objects">
+        <level-2 name="Link and Multi Formatting Objects" citation="§6.9" extURL="slice6.html#section-N17805-Dynamic-Effects:-Link-and-Multi-Formatting-Objects" ref-name="link">
           <level-3 name="basic-link" citation="§6.9.2" extURL="slice6.html#fo_basic-link" compliance-level="2" comply="yes">
             <comment>both internal and external supported</comment>
           </level-3>
@@ -88,373 +93,405 @@ want it to.</comment>
           <level-3 name="multi-properties" citation="§6.9.6" extURL="slice6.html#fo_multi-properties" compliance-level="2" comply="no"/>
           <level-3 name="multi-property-set" citation="§6.9.7" extURL="slice6.html#fo_multi-property-set" compliance-level="2" comply="no"/>
         </level-2>
-        <level-2 name="Out-of-line Formatting Objects" citation="§6.10" extURL="slice6.html#section-N18509-Out-of-Line-Formatting-Objects">
+        <level-2 name="Out-of-line Formatting Objects" citation="§6.10" extURL="slice6.html#section-N18509-Out-of-Line-Formatting-Objects" ref-name="outofline">
           <level-3 name="float" citation="§6.10.2" extURL="slice6.html#fo_float" compliance-level="2" comply="no"/>
           <level-3 name="footnote" citation="§6.10.3" extURL="slice6.html#fo_footnote" compliance-level="2" comply="yes"/>
           <level-3 name="footnote-body" citation="§6.10.4" extURL="slice6.html#fo_footnote-body" compliance-level="2" comply="yes"/>
         </level-2>
-        <level-2 name="Other Formatting Objects" citation="§6.11" extURL="slice6.html#section-N19019-Other-Formatting-Objects">
+        <level-2 name="Other Formatting Objects" citation="§6.11" extURL="slice6.html#section-N19019-Other-Formatting-Objects" ref-name="other">
           <level-3 name="wrapper" citation="§6.11.2" extURL="slice6.html#fo_wrapper" compliance-level="1" comply="yes"/>
           <level-3 name="marker" citation="§6.11.3" extURL="slice6.html#fo_marker" compliance-level="2" comply="yes"/>
           <level-3 name="retrieve-marker" citation="§6.11.4" extURL="slice6.html#fo_retrieve-marker" compliance-level="2" comply="yes"/>
         </level-2>
       </level-1>
-      <level-1 name="XSL-FO Property Support" compliance-item-desc="Property Name">
+      <level-1 name="XSL-FO Property Support" citation="§7" extURL="slice7.html#pr-section" compliance-item-desc="Property Name" ref-name="property">
         <explanatory>
           <p>The following is a summary of FOP's current support for the standard XSL-FO properties. Please note that a number of properties and categories of properties are not supported because they do not apply to documents in visual formats.</p>
         </explanatory>
-        <level-2 name="Common Accessibility Properties">
-          <level-3 name="source-document" compliance-level="1" comply="na"/>
-          <level-3 name="role" compliance-level="1" comply="na"/>
-        </level-2>
-        <level-2 name="Common Absolute Position Properties">
-          <level-3 name="absolute-position" compliance-level="3" comply="no"/>
-          <level-3 name="top" compliance-level="2" comply="yes"/>
-          <level-3 name="right" compliance-level="2" comply="yes"/>
-          <level-3 name="bottom" compliance-level="2" comply="yes"/>
-          <level-3 name="left" compliance-level="2" comply="yes"/>
-        </level-2>
-        <level-2 name="Common Aural Properties">
-          <level-3 name="azimuth" compliance-level="1" comply="na"/>
-          <level-3 name="cue-after" compliance-level="1" comply="na"/>
-          <level-3 name="cue-before" compliance-level="1" comply="na"/>
-          <level-3 name="elevation" compliance-level="1" comply="na"/>
-          <level-3 name="pause-after" compliance-level="1" comply="na"/>
-          <level-3 name="pause-before" compliance-level="1" comply="na"/>
-          <level-3 name="pitch" compliance-level="1" comply="na"/>
-          <level-3 name="pitch-range" compliance-level="1" comply="na"/>
-          <level-3 name="play-during" compliance-level="1" comply="na"/>
-          <level-3 name="richness" compliance-level="1" comply="na"/>
-          <level-3 name="speak" compliance-level="1" comply="na"/>
-          <level-3 name="speak-header" compliance-level="1" comply="na"/>
-          <level-3 name="speak-numeral" compliance-level="1" comply="na"/>
-          <level-3 name="speak-punctuation" compliance-level="1" comply="na"/>
-          <level-3 name="speech-rate" compliance-level="1" comply="na"/>
-          <level-3 name="stress" compliance-level="1" comply="na"/>
-          <level-3 name="voice-family" compliance-level="1" comply="na"/>
-          <level-3 name="volume" compliance-level="1" comply="na"/>
-        </level-2>
-        <level-2 name="Common Border, Padding, and Background Properties">
-          <level-3 name="background-attachment" compliance-level="2" comply="no"/>
-          <level-3 name="background-color" compliance-level="1" comply="yes"/>
-          <level-3 name="background-image" compliance-level="2" comply="yes"/>
-          <level-3 name="background-repeat" compliance-level="2" comply="no"/>
-          <level-3 name="background-position-horizontal" compliance-level="2" comply="no"/>
-          <level-3 name="background-position-vertical" compliance-level="2" comply="no"/>
-          <level-3 name="border-before-color" compliance-level="1" comply="yes"/>
-          <level-3 name="border-before-style" compliance-level="1" comply="yes"/>
-          <level-3 name="border-before-width" compliance-level="1" comply="yes"/>
-          <level-3 name="border-after-color" compliance-level="1" comply="yes"/>
-          <level-3 name="border-after-style" compliance-level="1" comply="yes"/>
-          <level-3 name="border-after-width" compliance-level="1" comply="yes"/>
-          <level-3 name="border-start-color" compliance-level="1" comply="yes"/>
-          <level-3 name="border-start-style" compliance-level="1" comply="yes"/>
-          <level-3 name="border-start-width" compliance-level="1" comply="yes"/>
-          <level-3 name="border-end-color" compliance-level="1" comply="yes"/>
-          <level-3 name="border-end-style" compliance-level="1" comply="yes"/>
-          <level-3 name="border-end-width" compliance-level="1" comply="yes"/>
-          <level-3 name="border-top-color" compliance-level="1" comply="yes"/>
-          <level-3 name="border-top-style" compliance-level="1" comply="yes"/>
-          <level-3 name="border-top-width" compliance-level="1" comply="yes"/>
-          <level-3 name="border-bottom-color" compliance-level="1" comply="yes"/>
-          <level-3 name="border-bottom-style" compliance-level="1" comply="yes"/>
-          <level-3 name="border-bottom-width" compliance-level="1" comply="yes"/>
-          <level-3 name="border-left-color" compliance-level="1" comply="yes"/>
-          <level-3 name="border-left-style" compliance-level="1" comply="yes"/>
-          <level-3 name="border-left-width" compliance-level="1" comply="yes"/>
-          <level-3 name="border-right-color" compliance-level="1" comply="yes"/>
-          <level-3 name="border-right-style" compliance-level="1" comply="yes"/>
-          <level-3 name="border-right-width" compliance-level="1" comply="yes"/>
-          <level-3 name="padding-before" compliance-level="1" comply="yes">
+        <level-2 name="Common Accessibility Properties" citation="§7.4" extURL="slice7.html#common-accessibility-properties" ref-name="commonaccess">
+          <level-3 name="source-document" citation="§7.4.1" extURL="slice7.html#source-document" compliance-level="1" comply="na"/>
+          <level-3 name="role" citation="§7.4.2" extURL="slice7.html#role" compliance-level="1" comply="na"/>
+        </level-2>
+        <level-2 name="Common Absolute Position Properties" citation="§7.5" extURL="slice7.html#common-absolute-position-properties" ref-name="commonabspos">
+          <level-3 name="absolute-position" citation="§7.5.1" extURL="slice7.html#absolute-position" compliance-level="3" comply="no"/>
+          <level-3 name="top" citation="§7.5.2" extURL="slice7.html#top" compliance-level="2" comply="yes"/>
+          <level-3 name="right" citation="§7.5.3" extURL="slice7.html#right" compliance-level="2" comply="yes"/>
+          <level-3 name="bottom" citation="§7.5.4" extURL="slice7.html#bottom" compliance-level="2" comply="yes"/>
+          <level-3 name="left" citation="§7.5.5" extURL="slice7.html#left" compliance-level="2" comply="yes"/>
+        </level-2>
+        <level-2 name="Common Aural Properties" citation="§7.6" extURL="slice7.html#common-aural-properties" ref-name="commonaural">
+          <level-3 name="azimuth" citation="§7.6.1" extURL="slice7.html#azimuth" compliance-level="1" comply="na"/>
+          <level-3 name="cue-after" citation="§7.6.2" extURL="slice7.html#cue-after" compliance-level="1" comply="na"/>
+          <level-3 name="cue-before" citation="§7.6.3" extURL="slice7.html#cue-before" compliance-level="1" comply="na"/>
+          <level-3 name="elevation" citation="§7.6.4" extURL="slice7.html#elevation" compliance-level="1" comply="na"/>
+          <level-3 name="pause-after" citation="§7.6.5" extURL="slice7.html#pause-after" compliance-level="1" comply="na"/>
+          <level-3 name="pause-before" citation="§7.6.6" extURL="slice7.html#pause-before" compliance-level="1" comply="na"/>
+          <level-3 name="pitch" citation="§7.6.7" extURL="slice7.html#pitch" compliance-level="1" comply="na"/>
+          <level-3 name="pitch-range" citation="§7.6.8" extURL="slice7.html#pitch-range" compliance-level="1" comply="na"/>
+          <level-3 name="play-during" citation="§7.6.9" extURL="slice7.html#play-during" compliance-level="1" comply="na"/>
+          <level-3 name="richness" citation="§7.6.10" extURL="slice7.html#richness" compliance-level="1" comply="na"/>
+          <level-3 name="speak" citation="§7.6.11" extURL="slice7.html#speak" compliance-level="1" comply="na"/>
+          <level-3 name="speak-header" citation="§7.6.12" extURL="slice7.html#speak-header" compliance-level="1" comply="na"/>
+          <level-3 name="speak-numeral" citation="§7.6.13" extURL="slice7.html#speak-numeral" compliance-level="1" comply="na"/>
+          <level-3 name="speak-punctuation" citation="§7.6.14" extURL="slice7.html#speak-punctuation" compliance-level="1" comply="na"/>
+          <level-3 name="speech-rate" citation="§7.6.15" extURL="slice7.html#speech-rate" compliance-level="1" comply="na"/>
+          <level-3 name="stress" citation="§7.6.16" extURL="slice7.html#stress" compliance-level="1" comply="na"/>
+          <level-3 name="voice-family" citation="§7.6.17" extURL="slice7.html#voice-family" compliance-level="1" comply="na"/>
+          <level-3 name="volume" citation="§7.6.18" extURL="slice7.html#volume" compliance-level="1" comply="na"/>
+        </level-2>
+        <level-2 name="Common Border, Padding, and Background Properties" citation="§7.7" extURL="slice7.html#common-border-padding-and-background-properties" ref-name="commonenv">
+          <level-3 name="background-attachment" citation="§7.7.1" extURL="slice7.html#background-attachment" compliance-level="2" comply="no"/>
+          <level-3 name="background-color" citation="§7.7.2" extURL="slice7.html#background-color" compliance-level="1" comply="yes"/>
+          <level-3 name="background-image" citation="§7.7.3" extURL="slice7.html#background-image" compliance-level="2" comply="yes"/>
+          <level-3 name="background-repeat" citation="§7.7.4" extURL="slice7.html#background-repeat" compliance-level="2" comply="no"/>
+          <level-3 name="background-position-horizontal" citation="§7.7.5" extURL="slice7.html#background-position-horizontal" compliance-level="2" comply="no"/>
+          <level-3 name="background-position-vertical" citation="§7.7.6" extURL="slice7.html#background-position-vertical" compliance-level="2" comply="no"/>
+          <level-3 name="border-before-color" citation="§7.7.7" extURL="slice7.html#border-before-color" compliance-level="1" comply="yes"/>
+          <level-3 name="border-before-style" citation="§7.7.8" extURL="slice7.html#border-before-style" compliance-level="1" comply="yes">
+          	<comment>only "solid" works</comment>
+          </level-3>
+          <level-3 name="border-before-width" citation="§7.7.9" extURL="slice7.html#border-before-width" compliance-level="1" comply="yes"/>
+          <level-3 name="border-after-color" citation="§7.7.10" extURL="slice7.html#border-after-color" compliance-level="1" comply="yes"/>
+          <level-3 name="border-after-style" citation="§7.7.11" extURL="slice7.html#border-after-style" compliance-level="1" comply="yes">
+          	<comment>only "solid" works</comment>
+          </level-3>
+          <level-3 name="border-after-width" citation="§7.7.12" extURL="slice7.html#border-after-width" compliance-level="1" comply="yes"/>
+          <level-3 name="border-start-color" citation="§7.7.13" extURL="slice7.html#border-start-color" compliance-level="1" comply="yes"/>
+          <level-3 name="border-start-style" citation="§7.7.14" extURL="slice7.html#border-start-style" compliance-level="1" comply="yes">
+          	<comment>only "solid" works</comment>
+          </level-3>
+          <level-3 name="border-start-width" citation="§7.7.15" extURL="slice7.html#border-start-width" compliance-level="1" comply="yes"/>
+          <level-3 name="border-end-color" citation="§7.7.16" extURL="slice7.html#border-end-color" compliance-level="1" comply="yes"/>
+          <level-3 name="border-end-style" citation="§7.7.17" extURL="slice7.html#border-end-style" compliance-level="1" comply="yes">
+          	<comment>only "solid" works</comment>
+          </level-3>
+          <level-3 name="border-end-width" citation="§7.7.18" extURL="slice7.html#border-end-width" compliance-level="1" comply="yes"/>
+          <level-3 name="border-top-color" citation="§7.7.19" extURL="slice7.html#border-top-color" compliance-level="1" comply="yes"/>
+          <level-3 name="border-top-style" citation="§7.7.20" extURL="slice7.html#border-top-style" compliance-level="1" comply="yes">
+          	<comment>only "solid" works</comment>
+          </level-3>
+          <level-3 name="border-top-width" citation="§7.7.21" extURL="slice7.html#border-top-width" compliance-level="1" comply="yes"/>
+          <level-3 name="border-bottom-color" citation="§7.7.22" extURL="slice7.html#border-bottom-color" compliance-level="1" comply="yes"/>
+          <level-3 name="border-bottom-style" citation="§7.7.23" extURL="slice7.html#border-bottom-style" compliance-level="1" comply="yes">
+          	<comment>only "solid" works</comment>
+          </level-3>
+          <level-3 name="border-bottom-width" citation="§7.7.24" extURL="slice7.html#border-bottom-width" compliance-level="1" comply="yes"/>
+          <level-3 name="border-left-color" citation="§7.7.25" extURL="slice7.html#border-left-color" compliance-level="1" comply="yes"/>
+          <level-3 name="border-left-style" citation="§7.7.26" extURL="slice7.html#border-left-style" compliance-level="1" comply="yes">
+          	<comment>only "solid" works</comment>
+          </level-3>
+          <level-3 name="border-left-width" citation="§7.7.27" extURL="slice7.html#border-left-width" compliance-level="1" comply="yes"/>
+          <level-3 name="border-right-color" citation="§7.7.28" extURL="slice7.html#border-right-color" compliance-level="1" comply="yes"/>
+          <level-3 name="border-right-style" citation="§7.7.29" extURL="slice7.html#border-right-style" compliance-level="1" comply="yes">
+          	<comment>only "solid" works</comment>
+          </level-3>
+          <level-3 name="border-right-width" citation="§7.7.30" extURL="slice7.html#border-right-width" compliance-level="1" comply="yes"/>
+          <level-3 name="padding-before" citation="§7.7.31" extURL="slice7.html#padding-before" compliance-level="1" comply="yes">
             <comment>only one value allowed</comment>
             <comment>only implemented for blocks</comment>
             <comment>can't be used to make extra space (use indents + spaces instead)</comment>
             <comment>can be used to control how much the background-color extends beyond the content rectangle</comment>
           </level-3>
-          <level-3 name="padding-after" compliance-level="1" comply="yes">
+          <level-3 name="padding-after" citation="§7.7.32" extURL="slice7.html#padding-after" compliance-level="1" comply="yes">
             <comment>same limitations as padding-before</comment>
           </level-3>
-          <level-3 name="padding-start" compliance-level="1" comply="yes">
+          <level-3 name="padding-start" citation="§7.7.33" extURL="slice7.html#padding-start" compliance-level="1" comply="yes">
             <comment>same limitations as padding-before</comment>
           </level-3>
-          <level-3 name="padding-end" compliance-level="1" comply="yes">
+          <level-3 name="padding-end" citation="§7.7.34" extURL="slice7.html#padding-end" compliance-level="1" comply="yes">
             <comment>same limitations as padding-before</comment>
           </level-3>
-          <level-3 name="padding-top" compliance-level="1" comply="yes">
+          <level-3 name="padding-top" citation="§7.7.35" extURL="slice7.html#padding-top" compliance-level="1" comply="yes">
             <comment>same limitations as padding-before</comment>
           </level-3>
-          <level-3 name="padding-bottom" compliance-level="1" comply="yes">
+          <level-3 name="padding-bottom" citation="§7.7.36" extURL="slice7.html#padding-bottom" compliance-level="1" comply="yes">
             <comment>same limitations as padding-before</comment>
           </level-3>
-          <level-3 name="padding-left" compliance-level="1" comply="yes">
+          <level-3 name="padding-left" citation="§7.7.37" extURL="slice7.html#padding-left" compliance-level="1" comply="yes">
             <comment>same limitations as padding-before</comment>
           </level-3>
-          <level-3 name="padding-right" compliance-level="1" comply="yes">
+          <level-3 name="padding-right" citation="§7.7.38" extURL="slice7.html#padding-right" compliance-level="1" comply="yes">
             <comment>same limitations as padding-before</comment>
           </level-3>
         </level-2>
-        <level-2 name="Common Font Properties">
-          <level-3 name="font-family" compliance-level="1" comply="yes"/>
-          <level-3 name="font-selection-strategy" compliance-level="3" comply="no"/>
-          <level-3 name="font-size" compliance-level="1" comply="yes"/>
-          <level-3 name="font-stretch" compliance-level="2" comply="no"/>
-          <level-3 name="font-size-adjust" compliance-level="2" comply="no"/>
-          <level-3 name="font-style" compliance-level="1" comply="yes"/>
-          <level-3 name="font-variant" compliance-level="1" comply="no"/>
-          <level-3 name="font-weight" compliance-level="1" comply="yes"/>
-        </level-2>
-        <level-2 name="Common Hyphenation Properties">
-          <level-3 name="country" compliance-level="2" comply="yes"/>
-          <level-3 name="language" compliance-level="2" comply="yes"/>
-          <level-3 name="script" compliance-level="2" comply="no"/>
-          <level-3 name="hyphenate" compliance-level="2" comply="yes"/>
-          <level-3 name="hyphenation-character" compliance-level="2" comply="yes"/>
-          <level-3 name="hyphenation-push-character-count" compliance-level="2" comply="yes"/>
-          <level-3 name="hyphenation-remain-character-count" compliance-level="2" comply="yes"/>
-        </level-2>
-        <level-2 name="Common Margin Properties - Block">
-          <level-3 name="margin-top" compliance-level="1" comply="partial">
+        <level-2 name="Common Font Properties" citation="§7.8" extURL="slice7.html#common-font-properties" ref-name="commonfont">
+          <level-3 name="font-family" citation="§7.8.2" extURL="slice7.html#font-family" compliance-level="1" comply="yes">
+          	<comment>font-family lists are not suppported, use a single font-family name</comment>
+          </level-3>
+          <level-3 name="font-selection-strategy" citation="§7.8.3" extURL="slice7.html#font-selection-strategy" compliance-level="3" comply="no"/>
+          <level-3 name="font-size" citation="§7.8.4" extURL="slice7.html#font-size" compliance-level="1" comply="yes"/>
+          <level-3 name="font-stretch" citation="§7.8.5" extURL="slice7.html#font-stretch" compliance-level="2" comply="no"/>
+          <level-3 name="font-size-adjust" citation="§7.8.6" extURL="slice7.html#font-size-adjust" compliance-level="2" comply="no"/>
+          <level-3 name="font-style" citation="§7.8.7" extURL="slice7.html#font-style" compliance-level="1" comply="yes"/>
+          <level-3 name="font-variant" citation="§7.8.8" extURL="slice7.html#font-variant" compliance-level="1" comply="no"/>
+          <level-3 name="font-weight" citation="§7.8.9" extURL="slice7.html#font-weight" compliance-level="1" comply="yes"/>
+        </level-2>
+        <level-2 name="Common Hyphenation Properties" citation="§7.9" extURL="slice7.html#common-hyphenation-properties" ref-name="commonhyphen">
+          <level-3 name="country" citation="§7.9.1" extURL="slice7.html#country" compliance-level="2" comply="yes"/>
+          <level-3 name="language" citation="§7.9.2" extURL="slice7.html#language" compliance-level="2" comply="yes"/>
+          <level-3 name="script" citation="§7.9.3" extURL="slice7.html#script" compliance-level="2" comply="no"/>
+          <level-3 name="hyphenate" citation="§7.9.4" extURL="slice7.html#hyphenate" compliance-level="2" comply="yes"/>
+          <level-3 name="hyphenation-character" citation="§7.9.5" extURL="slice7.html#hyphenation-character" compliance-level="2" comply="yes"/>
+          <level-3 name="hyphenation-push-character-count" citation="§7.9.6" extURL="slice7.html#hyphenation-push-character-count" compliance-level="2" comply="yes"/>
+          <level-3 name="hyphenation-remain-character-count" citation="§7.9.7" extURL="slice7.html#hyphenation-remain-character-count" compliance-level="2" comply="yes"/>
+        </level-2>
+        <level-2 name="Common Margin Properties - Block" citation="§7.10" extURL="slice7.html#common-margin-properties-block" ref-name="commonmarginblock">
+          <level-3 name="margin-top" citation="§7.10.1" extURL="slice7.html#margin-top" compliance-level="1" comply="partial">
             <comment>only on pages and regions</comment>
           </level-3>
-          <level-3 name="margin-bottom" compliance-level="1" comply="partial">
+          <level-3 name="margin-bottom" citation="§7.10.2" extURL="slice7.html#margin-bottom" compliance-level="1" comply="partial">
             <comment>only on pages and regions</comment>
           </level-3>
-          <level-3 name="margin-left" compliance-level="1" comply="partial">
+          <level-3 name="margin-left" citation="§7.10.3" extURL="slice7.html#margin-left" compliance-level="1" comply="partial">
             <comment>only on pages and regions</comment>
           </level-3>
-          <level-3 name="margin-right" compliance-level="1" comply="partial">
+          <level-3 name="margin-right" citation="§7.10.4" extURL="slice7.html#margin-right" compliance-level="1" comply="partial">
             <comment>only on pages and regions</comment>
           </level-3>
-          <level-3 name="space-before" compliance-level="1" comply="partial">
+          <level-3 name="space-before" citation="§7.10.5" extURL="slice7.html#space-before" compliance-level="1" comply="partial">
             <comment>space-before.optimum supported</comment>
           </level-3>
-          <level-3 name="space-after" compliance-level="1" comply="partial">
+          <level-3 name="space-after" citation="§7.10.6" extURL="slice7.html#space-after" compliance-level="1" comply="partial">
             <comment>space-after.optimum supported</comment>
           </level-3>
-          <level-3 name="start-indent" compliance-level="1" comply="yes"/>
-          <level-3 name="end-indent" compliance-level="1" comply="yes"/>
-        </level-2>
-        <level-2 name="Common Margin Properties - Inline">
-          <level-3 name="space-end" compliance-level="1" comply="no"/>
-          <level-3 name="space-start" compliance-level="1" comply="no"/>
-        </level-2>
-        <level-2 name="Common Relative Position Properties">
-          <level-3 name="relative-position" compliance-level="2" comply="no"/>
-        </level-2>
-        <level-2 name="Area Alignment Properties">
-          <level-3 name="alignment-adjust" compliance-level="1" comply="no"/>
-          <level-3 name="alignment-baseline" compliance-level="1" comply="no"/>
-          <level-3 name="baseline-shift" compliance-level="1" comply="no"/>
-          <level-3 name="display-align" compliance-level="2" comply="no"/>
-          <level-3 name="dominant-baseline" compliance-level="1" comply="no"/>
-          <level-3 name="relative-align" compliance-level="2" comply="no"/>
-        </level-2>
-        <level-2 name="Area Dimension Properties">
-          <level-3 name="block-progression-dimension" compliance-level="1" comply="no"/>
-          <level-3 name="content-height" compliance-level="2" comply="no"/>
-          <level-3 name="content-width" compliance-level="2" comply="no"/>
-          <level-3 name="height" compliance-level="1" comply="yes"/>
-          <level-3 name="inline-progression-dimension" compliance-level="1" comply="no"/>
-          <level-3 name="max-height" compliance-level="3" comply="no"/>
-          <level-3 name="max-width" compliance-level="3" comply="no"/>
-          <level-3 name="min-height" compliance-level="3" comply="no"/>
-          <level-3 name="min-width" compliance-level="3" comply="no"/>
-          <level-3 name="scaling" compliance-level="2" comply="no"/>
-          <level-3 name="scaling-method" compliance-level="2" comply="no"/>
-          <level-3 name="width" compliance-level="1" comply="yes"/>
-        </level-2>
-        <level-2 name="Block and Line-related Properties">
-          <level-3 name="hyphenation-keep" compliance-level="2" comply="no"/>
-          <level-3 name="hyphenation-ladder-count" compliance-level="2" comply="no"/>
-          <level-3 name="last-line-end-indent" compliance-level="2" comply="no"/>
-          <level-3 name="line-height" compliance-level="1" comply="yes"/>
-          <level-3 name="line-height-shift-adjustment" compliance-level="2" comply="no"/>
-          <level-3 name="line-stacking-strategy" compliance-level="1" comply="no"/>
-          <level-3 name="linefeed-treatment" compliance-level="2" comply="no"/>
-          <level-3 name="text-align" compliance-level="1" comply="yes"/>
-          <level-3 name="text-align-last" compliance-level="2" comply="yes"/>
-          <level-3 name="text-indent" compliance-level="1" comply="yes"/>
-          <level-3 name="white-space-collapse" compliance-level="2" comply="yes"/>
-          <level-3 name="white-space-treatment" compliance-level="2" comply="no"/>
-          <level-3 name="wrap-option" compliance-level="1" comply="yes"/>
-        </level-2>
-        <level-2 name="Character Properties">
-          <level-3 name="character" compliance-level="1" comply="yes"/>
-          <level-3 name="letter-spacing" compliance-level="2" comply="yes"/>
-          <level-3 name="suppress-at-line-break" compliance-level="2" comply="no"/>
-          <level-3 name="text-decoration" compliance-level="2" comply="yes"/>
-          <level-3 name="text-shadow" compliance-level="2" comply="no"/>
-          <level-3 name="text-transform" compliance-level="2" comply="no"/>
-          <level-3 name="treat-as-word-space" compliance-level="2" comply="no"/>
-          <level-3 name="word-spacing" compliance-level="2" comply="no"/>
-        </level-2>
-        <level-2 name="Color-related Properties">
-          <level-3 name="color" compliance-level="1" comply="yes"/>
-          <level-3 name="color-profile-name" compliance-level="2" comply="no"/>
-          <level-3 name="rendering-intent" compliance-level="2" comply="no"/>
-        </level-2>
-        <level-2 name="Float-related Properties">
-          <level-3 name="clear" compliance-level="2" comply="no"/>
-          <level-3 name="float" compliance-level="2" comply="no"/>
-          <level-3 name="intrusion-displace" compliance-level="2" comply="no"/>
-        </level-2>
-        <level-2 name="Keeps and Breaks Properties">
-          <level-3 name="break-after" compliance-level="1" comply="yes"/>
-          <level-3 name="break-before" compliance-level="1" comply="yes"/>
-          <level-3 name="keep-together" compliance-level="2" comply="partial">
+          <level-3 name="start-indent" citation="§7.10.7" extURL="slice7.html#start-indent" compliance-level="1" comply="yes"/>
+          <level-3 name="end-indent" citation="§7.10.8" extURL="slice7.html#end-indent" compliance-level="1" comply="yes"/>
+        </level-2>
+        <level-2 name="Common Margin Properties - Inline" citation="§7.11" extURL="slice7.html#common-margin-properties-inline" ref-name="commonmargininline">
+          <level-3 name="space-end" citation="§7.11.1" extURL="slice7.html#space-end" compliance-level="1" comply="no"/>
+          <level-3 name="space-start" citation="§7.11.2" extURL="slice7.html#space-start" compliance-level="1" comply="no"/>
+        </level-2>
+        <level-2 name="Common Relative Position Properties" citation="§7.12" extURL="slice7.html#common-relative-position-properties" ref-name="commonrelpos">
+          <level-3 name="relative-position" citation="§7.12.1" extURL="slice7.html#relative-position" compliance-level="2" comply="no"/>
+        </level-2>
+        <level-2 name="Area Alignment Properties" citation="§7.13" extURL="slice7.html#area-alignment" ref-name="areaalign">
+          <level-3 name="alignment-adjust" citation="§7.13.1" extURL="slice7.html#alignment-adjust" compliance-level="1" comply="no"/>
+          <level-3 name="alignment-baseline" citation="§7.13.2" extURL="slice7.html#alignment-baseline" compliance-level="1" comply="no"/>
+          <level-3 name="baseline-shift" citation="§7.13.3" extURL="slice7.html#baseline-shift" compliance-level="1" comply="no"/>
+          <level-3 name="display-align" citation="§7.13.4" extURL="slice7.html#display-align" compliance-level="2" comply="partial">
+            <comment>Implemented only for table-cell and block-container.</comment>
+            <comment>For table-cell, the "height" attribute must be set for the parent table-row; setting the height of the table or the table-cell results in vertical centering having no effect.
+</comment>
+          </level-3>
+          <level-3 name="dominant-baseline" citation="§7.13.5" extURL="slice7.html#dominant-baseline" compliance-level="1" comply="no"/>
+          <level-3 name="relative-align" citation="§7.13.6" extURL="slice7.html#relative-align" compliance-level="2" comply="no"/>
+        </level-2>
+        <level-2 name="Area Dimension Properties" citation="§7.14" extURL="slice7.html#section-N36094-Area-Dimension-Properties" ref-name="areadim">
+          <level-3 name="block-progression-dimension" citation="§7.14.1" extURL="slice7.html#block-progression-dimension" compliance-level="1" comply="no"/>
+          <level-3 name="content-height" citation="§7.14.2" extURL="slice7.html#content-height" compliance-level="2" comply="no"/>
+          <level-3 name="content-width" citation="§7.14.3" extURL="slice7.html#content-width" compliance-level="2" comply="no"/>
+          <level-3 name="height" citation="§7.14.4" extURL="slice7.html#height" compliance-level="1" comply="yes"/>
+          <level-3 name="inline-progression-dimension" citation="§7.14.5" extURL="slice7.html#inline-progression-dimension" compliance-level="1" comply="no"/>
+          <level-3 name="max-height" citation="§7.14.6" extURL="slice7.html#max-height" compliance-level="3" comply="no"/>
+          <level-3 name="max-width" citation="§7.14.7" extURL="slice7.html#max-width" compliance-level="3" comply="no"/>
+          <level-3 name="min-height" citation="§7.14.8" extURL="slice7.html#min-height" compliance-level="3" comply="no"/>
+          <level-3 name="min-width" citation="§7.14.9" extURL="slice7.html#min-width" compliance-level="3" comply="no"/>
+          <level-3 name="scaling" citation="§7.14.10" extURL="slice7.html#scaling" compliance-level="2" comply="no"/>
+          <level-3 name="scaling-method" citation="§7.14.11" extURL="slice7.html#scaling-method" compliance-level="2" comply="no"/>
+          <level-3 name="width" citation="§7.14.12" extURL="slice7.html#width" compliance-level="1" comply="yes"/>
+        </level-2>
+        <level-2 name="Block and Line-related Properties" citation="§7.15" extURL="slice7.html#section-N38191-Block-and-Line-related-Properties" ref-name="blockandline">
+          <level-3 name="hyphenation-keep" citation="§7.15.1" extURL="slice7.html#hyphenation-keep" compliance-level="2" comply="no"/>
+          <level-3 name="hyphenation-ladder-count" citation="§7.15.2" extURL="slice7.html#hyphenation-ladder-count" compliance-level="2" comply="no"/>
+          <level-3 name="last-line-end-indent" citation="§7.15.3" extURL="slice7.html#last-line-end-indent" compliance-level="2" comply="no"/>
+          <level-3 name="line-height" citation="§7.15.4" extURL="slice7.html#line-height" compliance-level="1" comply="yes"/>
+          <level-3 name="line-height-shift-adjustment" citation="§7.15.5" extURL="slice7.html#line-height-shift-adjustment" compliance-level="2" comply="no"/>
+          <level-3 name="line-stacking-strategy" citation="§7.15.6" extURL="slice7.html#line-stacking-strategy" compliance-level="1" comply="no"/>
+          <level-3 name="linefeed-treatment" citation="§7.15.7" extURL="slice7.html#linefeed-treatment" compliance-level="2" comply="no"/>
+          <level-3 name="white-space-treatment" citation="§7.15.8" extURL="slice7.html#white-space-treatment" compliance-level="2" comply="no"/>
+          <level-3 name="text-align" citation="§7.15.9" extURL="slice7.html#text-align" compliance-level="1" comply="yes"/>
+          <level-3 name="text-align-last" citation="§7.15.10" extURL="slice7.html#text-align-last" compliance-level="2" comply="yes"/>
+          <level-3 name="text-indent" citation="§7.15.11" extURL="slice7.html#text-indent" compliance-level="1" comply="yes"/>
+          <level-3 name="white-space-collapse" citation="§7.15.12" extURL="slice7.html#white-space-collapse" compliance-level="2" comply="yes"/>
+          <level-3 name="wrap-option" citation="§7.15.13" extURL="slice7.html#wrap-option" compliance-level="1" comply="yes"/>
+        </level-2>
+        <level-2 name="Character Properties" citation="§7.16" extURL="slice7.html#section-N40545-Character-Properties" ref-name="char">
+          <level-3 name="character" citation="§7.16.1" extURL="slice7.html#character" compliance-level="1" comply="yes"/>
+          <level-3 name="letter-spacing" citation="§7.16.2" extURL="slice7.html#letter-spacing" compliance-level="2" comply="yes"/>
+          <level-3 name="suppress-at-line-break" citation="§7.16.3" extURL="slice7.html#suppress-at-line-break" compliance-level="2" comply="no"/>
+          <level-3 name="text-decoration" citation="§7.16.4" extURL="slice7.html#text-decoration" compliance-level="2" comply="yes"/>
+          <level-3 name="text-shadow" citation="§7.16.5" extURL="slice7.html#text-shadow" compliance-level="2" comply="no"/>
+          <level-3 name="text-transform" citation="§7.16.6" extURL="slice7.html#text-transform" compliance-level="2" comply="no"/>
+          <level-3 name="treat-as-word-space" citation="§7.16.7" extURL="slice7.html#treat-as-word-space" compliance-level="2" comply="no"/>
+          <level-3 name="word-spacing" citation="§7.16.8" extURL="slice7.html#word-spacing" compliance-level="2" comply="no"/>
+        </level-2>
+        <level-2 name="Color-related Properties" citation="§7.17" extURL="slice7.html#section-N42081-Color-related-Properties" ref-name="color">
+          <level-3 name="color" citation="§7.17.1" extURL="slice7.html#color" compliance-level="1" comply="yes"/>
+          <level-3 name="color-profile-name" citation="§7.17.2" extURL="slice7.html#color-profile-name" compliance-level="2" comply="no"/>
+          <level-3 name="rendering-intent" citation="§7.17.3" extURL="slice7.html#rendering-intent" compliance-level="2" comply="no"/>
+        </level-2>
+        <level-2 name="Float-related Properties" citation="§7.18" extURL="slice7.html#section-N42546-Float-related-Properties" ref-name="float">
+          <level-3 name="clear" citation="§7.18.1" extURL="slice7.html#clear" compliance-level="2" comply="no"/>
+          <level-3 name="float" citation="§7.18.2" extURL="slice7.html#float" compliance-level="2" comply="no"/>
+          <level-3 name="intrusion-displace" citation="§7.18.3" extURL="slice7.html#intrusion-displace" compliance-level="2" comply="no"/>
+        </level-2>
+        <level-2 name="Keeps and Breaks Properties" citation="§7.19" extURL="slice7.html#section-N43268-Keeps-and-Breaks-Properties" ref-name="keepsbreaks">
+          <level-3 name="break-after" citation="§7.19.1" extURL="slice7.html#break-after" compliance-level="1" comply="yes"/>
+          <level-3 name="break-before" citation="§7.19.2" extURL="slice7.html#break-before" compliance-level="1" comply="yes"/>
+          <level-3 name="keep-together" citation="§7.19.3" extURL="slice7.html#keep-together" compliance-level="2" comply="partial">
             <comment>works only in table rows</comment>
           </level-3>
-          <level-3 name="keep-with-next" compliance-level="1" comply="partial">
+          <level-3 name="keep-with-next" citation="§7.19.4" extURL="slice7.html#keep-with-next" compliance-level="1" comply="partial">
             <comment>works only in table rows</comment>
           </level-3>
-          <level-3 name="keep-with-previous" compliance-level="1" comply="partial">
+          <level-3 name="keep-with-previous" citation="§7.19.5" extURL="slice7.html#keep-with-previous" compliance-level="1" comply="partial">
             <comment>works only in table rows</comment>
           </level-3>
-          <level-3 name="orphans" compliance-level="1" comply="no"/>
-          <level-3 name="widows" compliance-level="1" comply="no"/>
-        </level-2>
-        <level-2 name="Layout-related Properties">
-          <level-3 name="clip" compliance-level="2" comply="no"/>
-          <level-3 name="overflow" compliance-level="1" comply="no"/>
-          <level-3 name="reference-orientation" compliance-level="2" comply="no"/>
-          <level-3 name="span" compliance-level="2" comply="yes"/>
+          <level-3 name="orphans" citation="§7.19.6" extURL="slice7.html#orphans" compliance-level="1" comply="no"/>
+          <level-3 name="widows" citation="§7.19.7" extURL="slice7.html#widows" compliance-level="1" comply="no"/>
+        </level-2>
+        <level-2 name="Layout-related Properties" citation="§7.20" extURL="slice7.html#section-N44408-Layout-related-Properties" ref-name="layout">
+          <level-3 name="clip" citation="§7.20.1" extURL="slice7.html#clip" compliance-level="2" comply="no"/>
+          <level-3 name="overflow" citation="§7.20.2" extURL="slice7.html#overflow" compliance-level="1" comply="no"/>
+          <level-3 name="reference-orientation" citation="§7.20.3" extURL="slice7.html#reference-orientation" compliance-level="2" comply="no">
+            <comment>Workaround for page-orientation (portrait vs. landscape) is to swap the page-width and page-height properties.</comment>
+            <comment>Workaround for block-container is to use SVG.</comment>
+          </level-3>
+          <level-3 name="span" citation="§7.20.4" extURL="slice7.html#span" compliance-level="2" comply="yes"/>
         </level-2>
-        <level-2 name="Leader and Rule Properties">
-          <level-3 name="leader-alignment" compliance-level="2" comply="yes">
+        <level-2 name="Leader and Rule Properties" citation="§7.21" extURL="slice7.html#section-N45132-Leader-and-Rule-Properties" ref-name="leader">
+          <level-3 name="leader-alignment" citation="§7.21.1" extURL="slice7.html#leader-alignment" compliance-level="2" comply="yes">
             <comment>not value &quot;page&quot;</comment>
           </level-3>
-          <level-3 name="leader-pattern" compliance-level="1" comply="yes">
+          <level-3 name="leader-pattern" citation="§7.21.2" extURL="slice7.html#leader-pattern" compliance-level="1" comply="yes">
             <comment>not value &quot;use-content&quot;</comment>
           </level-3>
-          <level-3 name="leader-pattern-width" compliance-level="2" comply="yes"/>
-          <level-3 name="leader-length" compliance-level="1" comply="yes">
+          <level-3 name="leader-pattern-width" citation="§7.21.3" extURL="slice7.html#leader-pattern-width" compliance-level="2" comply="yes"/>
+          <level-3 name="leader-length" citation="§7.21.4" extURL="slice7.html#leader-length" compliance-level="1" comply="yes">
             <comment>leader-length.minimum is not used at all</comment>
           </level-3>
-          <level-3 name="rule-style" compliance-level="1" comply="yes"/>
-          <level-3 name="rule-thickness" compliance-level="1" comply="yes"/>
-        </level-2>
-        <level-2 name="Properties for Dynamic Effects Formatting Objects">
-          <level-3 name="active-state" compliance-level="2" comply="no"/>
-          <level-3 name="auto-restore" compliance-level="2" comply="no"/>
-          <level-3 name="case-name" compliance-level="2" comply="no"/>
-          <level-3 name="case-title" compliance-level="2" comply="no"/>
-          <level-3 name="destination-placement-offset" compliance-level="2" comply="no"/>
-          <level-3 name="external-destination" compliance-level="2" comply="yes"/>
-          <level-3 name="indicate-destination" compliance-level="2" comply="no"/>
-          <level-3 name="internal-destination" compliance-level="2" comply="yes"/>
-          <level-3 name="show-destination" compliance-level="2" comply="no"/>
-          <level-3 name="starting-state" compliance-level="2" comply="no"/>
-          <level-3 name="target-presentation-context" compliance-level="2" comply="no"/>
-          <level-3 name="target-processing-context" compliance-level="2" comply="no"/>
-          <level-3 name="target-stylesheet" compliance-level="2" comply="no"/>
-        </level-2>
-        <level-2 name="Properties for Markers">
-          <level-3 name="marker-class-name" compliance-level="2" comply="no"/>
-          <level-3 name="retrieve-class-name" compliance-level="2" comply="no"/>
-          <level-3 name="retrieve-position" compliance-level="2" comply="no"/>
-          <level-3 name="retrieve-boundary" compliance-level="2" comply="no"/>
-        </level-2>
-        <level-2 name="Properties for Number to String Conversion">
-          <level-3 name="format" compliance-level="1" comply="no"/>
-          <level-3 name="grouping-separator" compliance-level="2" comply="no"/>
-          <level-3 name="grouping-size" compliance-level="2" comply="no"/>
-          <level-3 name="letter-value" compliance-level="1" comply="no"/>
-        </level-2>
-        <level-2 name="Pagination and Layout Properties">
-          <level-3 name="blank-or-not-blank" compliance-level="2" comply="yes"/>
-          <level-3 name="column-count" compliance-level="2" comply="yes"/>
-          <level-3 name="column-gap" compliance-level="2" comply="yes"/>
-          <level-3 name="extent" compliance-level="2" comply="yes"/>
-          <level-3 name="flow-name" compliance-level="1" comply="yes"/>
-          <level-3 name="force-page-count" compliance-level="2" comply="no"/>
-          <level-3 name="initial-page-number" compliance-level="1" comply="yes"/>
-          <level-3 name="master-name" compliance-level="1" comply="yes"/>
-          <level-3 name="master-reference" compliance-level="1" comply="yes"/>
-          <level-3 name="maximum-repeats" compliance-level="2" comply="yes"/>
-          <level-3 name="media-usage" compliance-level="2" comply="no"/>
-          <level-3 name="odd-or-even" compliance-level="2" comply="yes"/>
-          <level-3 name="page-height" compliance-level="1" comply="yes"/>
-          <level-3 name="page-position" compliance-level="2" comply="yes"/>
-          <level-3 name="page-width" compliance-level="1" comply="yes"/>
-          <level-3 name="precedence" compliance-level="2" comply="no"/>
-          <level-3 name="region-name" compliance-level="1" comply="yes"/>
-        </level-2>
-        <level-2 name="Table Properties">
-          <level-3 name="border-after-precedence" compliance-level="1" comply="no"/>
-          <level-3 name="border-before-precedence" compliance-level="1" comply="no"/>
-          <level-3 name="border-collapse" compliance-level="2" comply="no"/>
-          <level-3 name="border-end-precedence" compliance-level="1" comply="no"/>
-          <level-3 name="border-separation" compliance-level="2" comply="no"/>
-          <level-3 name="border-start-precedence" compliance-level="1" comply="no"/>
-          <level-3 name="caption-side" compliance-level="3" comply="no"/>
-          <level-3 name="column-number" compliance-level="1" comply="no"/>
-          <level-3 name="column-width" compliance-level="1" comply="yes"/>
-          <level-3 name="empty-cells" compliance-level="2" comply="no"/>
-          <level-3 name="ends-row" compliance-level="2" comply="no"/>
-          <level-3 name="number-columns-repeated" compliance-level="1" comply="no"/>
-          <level-3 name="number-columns-spanned" compliance-level="1" comply="yes"/>
-          <level-3 name="number-rows-spanned" compliance-level="1" comply="yes"/>
-          <level-3 name="starts-row" compliance-level="2" comply="no"/>
-          <level-3 name="table-layout" compliance-level="2" comply="no"/>
-          <level-3 name="table-omit-footer-at-break" compliance-level="2" comply="yes"/>
-          <level-3 name="table-omit-header-at-break" compliance-level="2" comply="yes"/>
-        </level-2>
-        <level-2 name="Writing-mode-related Properties">
-          <level-3 name="direction" compliance-level="1" comply="no"/>
-          <level-3 name="glyph-orientation-horizontal" compliance-level="2" comply="no"/>
-          <level-3 name="glyph-orientation-vertical" compliance-level="2" comply="no"/>
-          <level-3 name="text-altitude" compliance-level="2" comply="no"/>
-          <level-3 name="text-depth" compliance-level="2" comply="no"/>
-          <level-3 name="unicode-bidi" compliance-level="2" comply="no"/>
-          <level-3 name="writing-mode" compliance-level="1" comply="no"/>
-        </level-2>
-        <level-2 name="Miscellaneous Properties">
-          <level-3 name="content-type" compliance-level="2" comply="no"/>
-          <level-3 name="id" compliance-level="1" comply="yes"/>
-          <level-3 name="provisional-label-separation" compliance-level="1" comply="yes"/>
-          <level-3 name="provisional-distance-between-starts" compliance-level="1" comply="yes"/>
-          <level-3 name="ref-id" compliance-level="2" comply="yes"/>
-          <level-3 name="score-spaces" compliance-level="2" comply="no"/>
-          <level-3 name="src" compliance-level="1" comply="yes"/>
-          <level-3 name="visibility" compliance-level="2" comply="no"/>
-          <level-3 name="z-index" compliance-level="2" comply="no"/>
-        </level-2>
-        <level-2 name="Shorthand Properties">
-          <level-3 name="background" compliance-level="3" comply="no"/>
-          <level-3 name="background-position" compliance-level="3" comply="no"/>
-          <level-3 name="border" compliance-level="3" comply="no"/>
-          <level-3 name="border-bottom" compliance-level="3" comply="yes"/>
-          <level-3 name="border-color" compliance-level="3" comply="yes">
+          <level-3 name="rule-style" citation="§7.21.5" extURL="slice7.html#rule-style" compliance-level="1" comply="yes"/>
+          <level-3 name="rule-thickness" citation="§7.21.6" extURL="slice7.html#rule-thickness" compliance-level="1" comply="yes"/>
+        </level-2>
+        <level-2 name="Properties for Dynamic Effects Formatting Objects" citation="§7.22" extURL="slice7.html#section-N46115-Properties-for-Dynamic-Effects-Formatting-Objects" ref-name="dynamiceffects">
+          <level-3 name="active-state" citation="§7.22.1" extURL="slice7.html#active-state" compliance-level="2" comply="no"/>
+          <level-3 name="auto-restore" citation="§7.22.2" extURL="slice7.html#auto-restore" compliance-level="2" comply="no"/>
+          <level-3 name="case-name" citation="§7.22.3" extURL="slice7.html#case-name" compliance-level="2" comply="no"/>
+          <level-3 name="case-title" citation="§7.22.4" extURL="slice7.html#case-title" compliance-level="2" comply="no"/>
+          <level-3 name="destination-placement-offset" citation="§7.22.5" extURL="slice7.html#destination-placement-offset" compliance-level="2" comply="no"/>
+          <level-3 name="external-destination" citation="§7.22.6" extURL="slice7.html#external-destination" compliance-level="2" comply="yes"/>
+          <level-3 name="indicate-destination" citation="§7.22.7" extURL="slice7.html#indicate-destination" compliance-level="2" comply="no"/>
+          <level-3 name="internal-destination" citation="§7.22.8" extURL="slice7.html#internal-destination" compliance-level="2" comply="yes"/>
+          <level-3 name="show-destination" citation="§7.22.9" extURL="slice7.html#show-destination" compliance-level="2" comply="no"/>
+          <level-3 name="starting-state" citation="§7.22.10" extURL="slice7.html#starting-state" compliance-level="2" comply="no"/>
+          <level-3 name="switch-to" citation="§7.22.11" extURL="slice7.html#switch-to" compliance-level="2" comply="no"/>
+          <level-3 name="target-presentation-context" citation="§7.22.12" extURL="slice7.html#target-presentation-context" compliance-level="2" comply="no"/>
+          <level-3 name="target-processing-context" citation="§7.22.13" extURL="slice7.html#target-processing-context" compliance-level="2" comply="no"/>
+          <level-3 name="target-stylesheet" citation="§7.22.14" extURL="slice7.html#target-stylesheet" compliance-level="2" comply="no"/>
+        </level-2>
+        <level-2 name="Properties for Markers" citation="§7.23" extURL="slice7.html#section-N48193-Properties-for-Markers" ref-name="markers">
+          <level-3 name="marker-class-name" citation="§7.23.1" extURL="slice7.html#marker-class-name" compliance-level="2" comply="no"/>
+          <level-3 name="retrieve-class-name" citation="§7.23.2" extURL="slice7.html#retrieve-class-name" compliance-level="2" comply="no"/>
+          <level-3 name="retrieve-position" citation="§7.23.3" extURL="slice7.html#retrieve-position" compliance-level="2" comply="no"/>
+          <level-3 name="retrieve-boundary" citation="§7.23.4" extURL="slice7.html#retrieve-boundary" compliance-level="2" comply="no"/>
+        </level-2>
+        <level-2 name="Properties for Number to String Conversion" citation="§7.24" extURL="slice7.html#section-N48804-Properties-for-Number-to-String-Conversion" ref-name="numberstring">
+          <level-3 name="format" citation="§7.24.1" extURL="slice7.html#format" compliance-level="1" comply="no"/>
+          <level-3 name="grouping-separator" citation="§7.24.2" extURL="slice7.html#grouping-separator" compliance-level="2" comply="no"/>
+          <level-3 name="grouping-size" citation="§7.24.3" extURL="slice7.html#grouping-size" compliance-level="2" comply="no"/>
+          <level-3 name="letter-value" citation="§7.24.4" extURL="slice7.html#letter-value" compliance-level="1" comply="no"/>
+        </level-2>
+        <level-2 name="Pagination and Layout Properties" citation="§7.25" extURL="slice7.html#section-N49321-Pagination-and-Layout-Properties" ref-name="pagination">
+          <level-3 name="blank-or-not-blank" citation="§7.25.1" extURL="slice7.html#blank-or-not-blank" compliance-level="2" comply="yes"/>
+          <level-3 name="column-count" citation="§7.25.2" extURL="slice7.html#column-count" compliance-level="2" comply="yes"/>
+          <level-3 name="column-gap" citation="§7.25.3" extURL="slice7.html#column-gap" compliance-level="2" comply="yes"/>
+          <level-3 name="extent" citation="§7.25.4" extURL="slice7.html#extent" compliance-level="2" comply="yes"/>
+          <level-3 name="flow-name" citation="§7.25.5" extURL="slice7.html#flow-name" compliance-level="1" comply="yes"/>
+          <level-3 name="force-page-count" citation="§7.25.6" extURL="slice7.html#force-page-count" compliance-level="2" comply="no"/>
+          <level-3 name="initial-page-number" citation="§7.25.7" extURL="slice7.html#initial-page-number" compliance-level="1" comply="yes"/>
+          <level-3 name="master-name" citation="§7.25.8" extURL="slice7.html#master-name" compliance-level="1" comply="yes"/>
+          <level-3 name="master-reference" citation="§7.25.9" extURL="slice7.html#master-reference" compliance-level="1" comply="yes"/>
+          <level-3 name="maximum-repeats" citation="§7.25.10" extURL="slice7.html#maximum-repeats" compliance-level="2" comply="yes"/>
+          <level-3 name="media-usage" citation="§7.25.11" extURL="slice7.html#media-usage" compliance-level="2" comply="no"/>
+          <level-3 name="odd-or-even" citation="§7.25.12" extURL="slice7.html#odd-or-even" compliance-level="2" comply="yes"/>
+          <level-3 name="page-height" citation="§7.25.13" extURL="slice7.html#page-height" compliance-level="1" comply="yes"/>
+          <level-3 name="page-position" citation="§7.25.14" extURL="slice7.html#page-position" compliance-level="2" comply="partial">
+          	<comment>"last" isn't implemented!</comment>
+          </level-3>
+          <level-3 name="page-width" citation="§7.25.15" extURL="slice7.html#page-width" compliance-level="1" comply="yes"/>
+          <level-3 name="precedence" citation="§7.25.16" extURL="slice7.html#precedence" compliance-level="2" comply="no"/>
+          <level-3 name="region-name" citation="§7.25.17" extURL="slice7.html#region-name" compliance-level="1" comply="yes"/>
+        </level-2>
+        <level-2 name="Table Properties" citation="§7.26" extURL="slice7.html#section-N52000-Table-Properties" ref-name="table">
+          <level-3 name="border-after-precedence" citation="§7.26.1" extURL="slice7.html#border-after-precedence" compliance-level="1" comply="no"/>
+          <level-3 name="border-before-precedence" citation="§7.26.2" extURL="slice7.html#border-before-precedence" compliance-level="1" comply="no"/>
+          <level-3 name="border-collapse" citation="§7.26.3" extURL="slice7.html#border-collapse" compliance-level="2" comply="no"/>
+          <level-3 name="border-end-precedence" citation="§7.26.4" extURL="slice7.html#border-end-precedence" compliance-level="1" comply="no"/>
+          <level-3 name="border-separation" citation="§7.26.5" extURL="slice7.html#border-separation" compliance-level="2" comply="no"/>
+          <level-3 name="border-start-precedence" citation="§7.26.6" extURL="slice7.html#border-start-precedence" compliance-level="1" comply="no"/>
+          <level-3 name="caption-side" citation="§7.26.7" extURL="slice7.html#caption-side" compliance-level="3" comply="no"/>
+          <level-3 name="column-number" citation="§7.26.8" extURL="slice7.html#column-number" compliance-level="1" comply="no"/>
+          <level-3 name="column-width" citation="§7.26.9" extURL="slice7.html#column-width" compliance-level="1" comply="partial">
+          <comment>"percentage" not implemented. Workaround is to use the XSL-FO "proportional-column-width" function.</comment>
+          </level-3>
+          <level-3 name="empty-cells" citation="§7.26.10" extURL="slice7.html#empty-cells" compliance-level="2" comply="no"/>
+          <level-3 name="ends-row" citation="§7.26.11" extURL="slice7.html#ends-row" compliance-level="2" comply="no"/>
+          <level-3 name="number-columns-repeated" citation="§7.26.12" extURL="slice7.html#number-columns-repeated" compliance-level="1" comply="no"/>
+          <level-3 name="number-columns-spanned" citation="§7.26.13" extURL="slice7.html#number-columns-spanned" compliance-level="1" comply="yes"/>
+          <level-3 name="number-rows-spanned" citation="§7.26.14" extURL="slice7.html#number-rows-spanned" compliance-level="1" comply="yes"/>
+          <level-3 name="starts-row" citation="§7.26.15" extURL="slice7.html#starts-row" compliance-level="2" comply="no"/>
+          <level-3 name="table-layout" citation="§7.26.16" extURL="slice7.html#table-layout" compliance-level="2" comply="no"/>
+          <level-3 name="table-omit-footer-at-break" citation="§7.26.17" extURL="slice7.html#table-omit-footer-at-break" compliance-level="2" comply="yes"/>
+          <level-3 name="table-omit-header-at-break" citation="§7.26.18" extURL="slice7.html#table-omit-header-at-break" compliance-level="2" comply="yes"/>
+        </level-2>
+        <level-2 name="Writing-mode-related Properties" citation="§7.27" extURL="slice7.html#writing-mode-related" ref-name="writingmode">
+          <level-3 name="direction" citation="§7.27.1" extURL="slice7.html#direction" compliance-level="1" comply="no"/>
+          <level-3 name="glyph-orientation-horizontal" citation="§7.27.2" extURL="slice7.html#glyph-orientation-horizontal" compliance-level="2" comply="no"/>
+          <level-3 name="glyph-orientation-vertical" citation="§7.27.3" extURL="slice7.html#glyph-orientation-vertical" compliance-level="2" comply="no"/>
+          <level-3 name="text-altitude" citation="§7.27.4" extURL="slice7.html#text-altitude" compliance-level="2" comply="no"/>
+          <level-3 name="text-depth" citation="§7.27.5" extURL="slice7.html#text-depth" compliance-level="2" comply="no"/>
+          <level-3 name="unicode-bidi" citation="§7.27.6" extURL="slice7.html#unicode-bidi" compliance-level="2" comply="no"/>
+          <level-3 name="writing-mode" citation="§7.27.7" extURL="slice7.html#writing-mode" compliance-level="1" comply="no"/>
+        </level-2>
+        <level-2 name="Miscellaneous Properties" citation="§7.28" extURL="slice7.html#section-N56509-Miscellaneous-Properties" ref-name="misc">
+          <level-3 name="content-type" citation="§7.28.1" extURL="slice7.html#content-type" compliance-level="2" comply="no"/>
+          <level-3 name="id" citation="§7.28.2" extURL="slice7.html#id" compliance-level="1" comply="yes"/>
+          <level-3 name="provisional-label-separation" citation="§7.28.3" extURL="slice7.html#provisional-label-separation" compliance-level="1" comply="yes"/>
+          <level-3 name="provisional-distance-between-starts" citation="§7.28.4" extURL="slice7.html#provisional-distance-between-starts" compliance-level="1" comply="yes"/>
+          <level-3 name="ref-id" citation="§7.28.5" extURL="slice7.html#ref-id" compliance-level="2" comply="yes"/>
+          <level-3 name="score-spaces" citation="§7.28.6" extURL="slice7.html#score-spaces" compliance-level="2" comply="no"/>
+          <level-3 name="src" citation="§7.28.7" extURL="slice7.html#src" compliance-level="1" comply="yes"/>
+          <level-3 name="visibility" citation="§7.28.8" extURL="slice7.html#visibility" compliance-level="2" comply="no"/>
+          <level-3 name="z-index" citation="§7.28.9" extURL="slice7.html#z-index" compliance-level="2" comply="no"/>
+        </level-2>
+        <level-2 name="Shorthand Properties" citation="§7.29" extURL="slice7.html#section-N57854-Shorthand-Properties" ref-name="shorthand">
+          <level-3 name="background" citation="§7.29.1" extURL="slice7.html#background" compliance-level="3" comply="no"/>
+          <level-3 name="background-position" citation="§7.29.2" extURL="slice7.html#background-position" compliance-level="3" comply="no"/>
+          <level-3 name="border" citation="§7.29.3" extURL="slice7.html#border" compliance-level="3" comply="no"/>
+          <level-3 name="border-bottom" citation="§7.29.4" extURL="slice7.html#border-bottom" compliance-level="3" comply="yes"/>
+          <level-3 name="border-color" citation="§7.29.5" extURL="slice7.html#border-color" compliance-level="3" comply="yes">
             <comment>only one value allowed</comment>
           </level-3>
-          <level-3 name="border-left" compliance-level="3" comply="yes"/>
-          <level-3 name="border-right" compliance-level="3" comply="yes"/>
-          <level-3 name="border-style" compliance-level="3" comply="yes"/>
-          <level-3 name="border-spacing" compliance-level="3" comply="no"/>
-          <level-3 name="border-top" compliance-level="3" comply="yes"/>
-          <level-3 name="border-width" compliance-level="3" comply="yes"/>
-          <level-3 name="cue" compliance-level="3" comply="no"/>
-          <level-3 name="font" compliance-level="3" comply="no"/>
-          <level-3 name="margin" compliance-level="3" comply="partial">
+          <level-3 name="border-left" citation="§7.29.6" extURL="slice7.html#border-left" compliance-level="3" comply="yes"/>
+          <level-3 name="border-right" citation="§7.29.7" extURL="slice7.html#border-right" compliance-level="3" comply="yes"/>
+          <level-3 name="border-style" citation="§7.29.8" extURL="slice7.html#border-style" compliance-level="3" comply="yes">
+          	<comment>only "solid" works</comment>
+          </level-3>
+          <level-3 name="border-spacing" citation="§7.29.9" extURL="slice7.html#border-spacing" compliance-level="3" comply="no"/>
+          <level-3 name="border-top" citation="§7.29.10" extURL="slice7.html#border-top" compliance-level="3" comply="yes"/>
+          <level-3 name="border-width" citation="§7.29.11" extURL="slice7.html#border-width" compliance-level="3" comply="yes"/>
+          <level-3 name="cue" citation="§7.29.12" extURL="slice7.html#cue" compliance-level="3" comply="no"/>
+          <level-3 name="font" citation="§7.29.13" extURL="slice7.html#font" compliance-level="3" comply="no"/>
+          <level-3 name="margin" citation="§7.29.14" extURL="slice7.html#margin" compliance-level="3" comply="partial">
             <comment>only on pages and regions</comment>
           </level-3>
-          <level-3 name="padding" compliance-level="3" comply="partial">
+          <level-3 name="padding" citation="§7.29.15" extURL="slice7.html#padding" compliance-level="3" comply="partial">
             <comment>only one value allowed</comment>
             <comment>only implemented for blocks</comment>
             <comment>can't be used to make extra space (use indents + spaces instead)</comment>
             <comment>can be used to control how much the background-color extends beyond the content rectangle</comment>
           </level-3>
-          <level-3 name="page-break-after" compliance-level="3" comply="no"/>
-          <level-3 name="page-break-before" compliance-level="3" comply="no"/>
-          <level-3 name="page-break-inside" compliance-level="3" comply="no"/>
-          <level-3 name="pause" compliance-level="3" comply="no"/>
-          <level-3 name="position" compliance-level="3" comply="partial">
+          <level-3 name="page-break-after" citation="§7.29.16" extURL="slice7.html#page-break-after" compliance-level="3" comply="no"/>
+          <level-3 name="page-break-before" citation="§7.29.17" extURL="slice7.html#page-break-before" compliance-level="3" comply="no"/>
+          <level-3 name="page-break-inside" citation="§7.29.18" extURL="slice7.html#page-break-inside" compliance-level="3" comply="no"/>
+          <level-3 name="pause" citation="§7.29.19" extURL="slice7.html#pause" compliance-level="3" comply="no"/>
+          <level-3 name="position" citation="§7.29.20" extURL="slice7.html#position" compliance-level="3" comply="partial">
             <comment>&quot;inherit&quot; not handled</comment>
           </level-3>
-          <level-3 name="size" compliance-level="3" comply="no"/>
-          <level-3 name="vertical-align" compliance-level="3" comply="no"/>
-          <level-3 name="white-space" compliance-level="3" comply="no"/>
-          <level-3 name="xml:lang" compliance-level="3" comply="no"/>
+          <level-3 name="size" citation="§7.29.21" extURL="slice7.html#size" compliance-level="3" comply="no"/>
+          <level-3 name="vertical-align" citation="§7.29.22" extURL="slice7.html#vertical-align" compliance-level="3" comply="no"/>
+          <level-3 name="white-space" citation="§7.29.23" extURL="slice7.html#white-space" compliance-level="3" comply="no"/>
+          <level-3 name="xml:lang" citation="§7.29.24" extURL="slice7.html#xml:lang" compliance-level="3" comply="no"/>
         </level-2>
       </level-1>
     </standard>

src/documentation/content/xdocs/dev/api-doc.xml

@@ -15,7 +15,7 @@
         <li><link href="http://nagoya.apache.org/gump/javadoc/xml-fop-maintenance/build/javadocs/index.html">Javadocs for Maintenance Branch</link></li>
         <li><link href="http://nagoya.apache.org/gump/javadoc/xml-fop/build/javadocs/index.html">Javadocs for Trunk (Redesign)</link></li>
       </ul>
-      <note>If the links return an "Object not found!" message or otherwise do not work properly, it is probably because of a build error. Please raise a question on the <link href="../maillist.html#fop-user">fop-user mailing list</link> so that any problems can be fixed before the next build.</note>
+      <note>If the links return an "Object not found!" message or otherwise do not work properly, it is probably because of a build error. Please raise a question on the <link href="../resources.html#mailing-lists-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>

src/documentation/content/xdocs/dev/book.xml

@@ -34,5 +34,7 @@
       <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-item label="PDF" href="pdf.html"/>
+      <menu-item label="Postscript" href="ps.html"/>
     </menu>
 </book>

src/documentation/content/xdocs/dev/doc.xml

@@ -19,22 +19,6 @@ The major exception to this rule is the design doc, which currently exclusively
 Maintenance branch releases either copy the trunk content to the maintenance branch or use the trunk content directly for doc builds.</note>
       <p>Basic documents are stored in XML files, and use DTDs provided by Apache Forrest.</p>
     </section>
-    <section id="design">
-      <title>Design Principles</title>
-      <p>These principles are not written in stone, but reflect the current philosophy, and are documented here primarily to help achieve consistency. These principles should be changed if better or more practical ones are found, but they should probably be discussed and changed by common consent.</p>
-      <section id="where">
-        <title>Where</title>
-        <ul>
-          <li>To the extent possible, keep user content separate from developer content, primarily so the user doesn't have to filter out technical information.</li>
-          <li>To the extent possible, try to document a topic exactly once, in the place the user is most likely to look for it, then link to that from other locations as appropriate. This is somewhat contrary to the principle above, which should be applied as a higher priority.</li>
-        </ul>
-      </section>
-      <section id="design-when">
-        <title>When</title>
-        <p>The documentation and the product are in a constant state of change, and there is some difficulty in deciding what product state the website content should reflect. The current thinking is that the website should reflect the current state of the repository code branch from which releases are made. Features or other documentation that applies to unreleased code should be marked in such a way within the content that the user can determine whether and how it applies to the version they are using. For example, "Feature xyz is first available in Release n.nn.n".</p>
-        <p>Other approaches were considered, but all seemed to have significantly higher costs both to the users and the developers. From the user's standpoint, the choice is either that they potentially have to look multiple places to get the information they need (which was rejected), or they have to filter out an occasional feature that is in code available subsequent to their release (which was accepted).</p>
-      </section>
-    </section>
     <section id="web">
       <title>Website</title>
       <section id="web-background">

src/documentation/content/xdocs/dev/index.xml

@@ -64,7 +64,7 @@ internally will be kept.
       <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.
+Resources for these and other topics can be found on the <link href="../resources.html">FOP User Resources</link> page.
         </p>
         <ul>
           <li>
@@ -80,7 +80,7 @@ The <link href="http://xml.apache.org/mail/fop-dev/">Apache Mailing List archive
               </li>
             </ul>
           </li>
-          <li>Before posting questions to any list, see "<link href="../maillist.html#general">General Information</link>".</li>
+          <li>Before posting questions to any list, see "<link href="../resources.html#mailing-lists-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.

src/documentation/content/xdocs/dev/pdf.xml

@@ -0,0 +1,21 @@
+<?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>PDF (Developer Information)</title>
+  </header>
+  <body>
+    <section>
+      <title>Resources</title>
+      <ul>
+        <li><link href="http://partners.adobe.com/asn/developer/technotes/acrobatpdf.html">Acrobat/PDF Technical Notes</link></li>
+      </ul>
+    </section>
+  </body>
+</document>
+
+<!-- Last Line of $RCSfile$ -->

src/documentation/content/xdocs/dev/ps.xml

@@ -0,0 +1,21 @@
+<?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>Postscript (Developer Information)</title>
+  </header>
+  <body>
+    <section>
+      <title>Resources</title>
+      <ul>
+        <li><link href="http://partners.adobe.com/asn/developer/technotes/postscript.html">Postscript Technical Notes</link></li>
+      </ul>
+    </section>
+  </body>
+</document>
+
+<!-- Last Line of $RCSfile$ -->

src/documentation/content/xdocs/download.xml

@@ -3,33 +3,39 @@
     "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/schema/dtd/document-v11.dtd">
 
 <document>
-    <header>
-        <title>Download</title>
-    </header>
-
-    <body>
-<section>
-  <title>Downloading FOP</title>
-    <p>You can download the latest release version from the <link
-       href="http://xml.apache.org/dist/fop/">distribution directory</link>. </p>
-    <p>The file contains also the documentation (including some example fo files) and the source.  </p>
-    <p>If you want to work with the latest and nicest code, you can use the cvs version. See the section
-       on AnonCVS in the <link href="http://xml.apache.org/cvs.html">xml.apache.org documentation</link> for details.
-       Sometimes people have difficulties to access the cvs server; in this case you can download
-       a snapshot from the cvs files <link href="http://xml.apache.org/from-cvs/xml-fop/">here</link>.
-       In both cases you have to build FOP yourself - see <link href="compiling.html">Compiling Fop</link> for details.
-    </p>
-    <note>
-      Important: Currently, releases of FOP are coming out of the
-      "fop-0_20_2-maintain" branch. The "MAIN" branch is currently
-      under development. See <link href="http://xml.apache.org/fop/dev/index.html">Development Docs</link>
-      for more information.
-    </note>
-    <p>To run FOP from the command line, see <link href="running.html">Running FOP</link>.</p>
-    <p>If you are interested in embedding FOP in a Java application of your own, see
-       <link href="embedding.html">Embedding FOP</link>.
-    </p>
+  <header>
+    <title>FOP: Downloading A Distribution</title>
+  </header>
+  <body>
+  <section id="dist-type">
+    <title>Binary or Source?</title>
+    <p>Most FOP users will want to download the latest binary distribution, which is ready to run "out of the box."
+However, a source distribution will be preferable if you fall into one of the following categories:</p>
+    <ul>
+      <li>You wish to modify FOP.</li>
+      <li>You wish to use a version more recent than the latest release. For example, if you have read on the user mailing list that a bug has been fixed or a feature added that you are eager to try, you might download a source distribution from the CVS repository so that you don't have to wait for the next release.</li>
+      <li>You wish to build a local copy of the API documentation (javadocs).</li>
+    </ul>
+  </section>
+  <section id="binary">
+    <title>Binary Download</title>
+    <p>Binary distributions include "-bin" in their names, and can be downloaded from the <link href="http://xml.apache.org/dist/fop/">FOP Distribution</link> directory.
+</p>
+  </section>
+  <section id="source">
+    <title>Source Download</title>
+    <p>You must first determine which of the two main development branches you wish to download, "maintenance" or "redesign".
+See <link href="dev/index.html">Development Introduction</link> for more details on the choices, and for the CVS tags to use when downloading the "maintenance" branch.</p>
+    <p>There are three ways to obtain a source distribution. Please note that they are listed from least current to most current:</p>
+    <ul>
+      <li>Download a released version from the <link href="http://xml.apache.org/dist/fop/">FOP Distribution</link> directory. Source distributions include "-src" in their names. Please note that official releases currently are <em>only</em> made from the "maintenance" branch.</li>
+      <li>Download a CVS snapshot from the cvs files <link href="http://xml.apache.org/from-cvs/xml-fop/">here</link>. These snapshots are built approximately every six hours, and have the GMT of their creation time embedded in their names. Please note that CVS snapshots are made only for the "redesign" branch.</li>
+      <li>Download directly from the CVS repository.
+Anyone can do this using the <link href="http://xml.apache.org/cvs.html#AnonCVS">Anonymous CVS Server</link>. By default, the CVS code is up-to-the-minute, the same code that the developers are modifying. See the <link href="dev/tools.html#cvs">CVS section of Developer Tools</link> for more information on using CVS.</li>
+    </ul>
+    <p>With any source distribution, you will need to <link href="compiling.html">Build FOP</link> from the source files.</p>
 </section>
     </body>
 </document>
 
+<!-- Last Line of $RCSFile$ -->

src/documentation/content/xdocs/embedding.xml

@@ -7,15 +7,16 @@
 <document>
     <header>
         <title>Embedding FOP</title>
-        <subtitle>Notes about embedding FOP in your Java application</subtitle>
+        <subtitle>How to Embed FOP in a Java application</subtitle>
     </header>
 
     <body>
-<section>
-  <title>Embedding FOP</title>
-  <section>
+  <section id="overview">
     <title>Overview</title>
-  <p>Instantiate org.apache.fop.apps.Driver. Once this class is
+    <p>Review <link href="running.html">Running FOP</link> for important information that applies to embedded applications as well as command-line use, such as options and performance.
+    </p>
+  <p>To embed FOP in your application, instantiate org.apache.fop.apps.Driver.
+     Once this class is
      instantiated, methods are called to set the
      Renderer to use
      and the OutputStream to use to output the results of the
@@ -26,7 +27,7 @@
      enables runtime determination of Renderer and ElementMapping(s).
   </p>
   </section>
-  <section>
+  <section id="basics">
     <title>Basics</title>
   <p>The simplest way to use Driver is to instantiate it with the
      InputSource and OutputStream, then set the renderer desired and
@@ -36,9 +37,9 @@
   </p>
     <source><![CDATA[
    import org.apache.fop.apps.Driver;
-   
-   /*..*/ 
-    
+
+   /*..*/
+
    Driver driver = new Driver(new InputSource(args[0]),
                               new FileOutputStream(args[1]));
    driver.setRenderer(Driver.RENDER_PDF);
@@ -47,7 +48,6 @@
 In the example above, args[0] contains the path to an XSL-FO file, while 
 args[1] contains a path for the target PDF file.
   </p>
-
   <p>You also need to set up logging. Global logging for all FOP
     processes is managed by MessageHandler. Per-instance logging
     is handled by Driver. You want to set both using an implementation
@@ -149,30 +149,29 @@ issues should be fixed in the upcoming JDK 1.4</note>
   <p>If you want FOP to be totally silent you can also set an org.apache.avalon.framework.logger.NullLogger instance.</p>
   <p>If you want to use yet another logging facility you simply have to create a class that implements org.apache.avalon.framework.logging.Logger
   and set it on the Driver object. See the existing implementations in Avalon Framework for examples.</p>
-
   </section>
-  <section>
-    <title>Hints</title>
-    <section>
-     <title>XML/XSL/DOM Inputs</title>
-     <p>
-You may want to supply you input to FOP from different data sources.
-For example you may have a DOM and XSL stylesheet or you may want to
-set variables in the stylesheet. The page here:
-<fork href="http://xml.apache.org/xalan-j/usagepatterns.html">
-http://xml.apache.org/xalan-j/usagepatterns.html</fork> describes
-how you can do these things.
-     </p>
+    <section id="input">
+      <title>Input Sources</title>
+      <p>The input XSL-FO document is always handled internally as SAX (see the <link href="design/parsing.html">Parsing Design Document</link> for the rationale).
+However, the input itself can be provided in a variety of ways to FOP, which normalizes the input (if necessary) into SAX events:</p>
+      <ul>
+        <li><strong>SAX Events through SAX Handler</strong>: <code>FOTreeBuilder</code> is the SAX Handler which is obtained through <code>getContentHandler</code> on <code>Driver</code>.</li>
+        <li><strong>DOM (which is converted into SAX Events)</strong>: The conversion of a DOM tree is done via the <code>render(Document)</code> method on <code>Driver</code>.</li>
+        <li><strong>Data Source (which is parsed and converted into SAX Events)</strong>: The <code>Driver</code> can take an <code>InputSource</code> as input.
+This can use a <code>Stream</code>, <code>String</code> etc.</li>
+        <li><strong>XML+XSLT Transformation</strong> (which is transformed using an XSLT Processor and the result is fired as SAX Events: <code>XSLTInputHandler</code> is used as an <code>InputSource</code> in the render(<code>XMLReader</code>, <code>InputSource</code>) method on <code>Driver</code>.</li>
+      </ul>
+      <p>There are a variety of upstream data manipulations possible.
+For example, you may have a DOM and an XSL stylesheet; or you may want to
+set variables in the stylesheet.
+Interface documentation and some cookbook solutions to these situations are provided in <fork href="http://xml.apache.org/xalan-j/usagepatterns.html">Xalan Basic Usage Patterns</fork>.</p>
      <p>
-You can use the content handler from the driver to create a SAXResult.
-The transformer then can fire SAX events on the content handler which
-will in turn create the rendered output.
-     </p>
-     <p>
-Examples showing this can be found at the bott
+See the <link href="#examples">Examples</link> for some variations on input. 
      </p>
     </section>
-    <section>
+  <section id="hints">
+    <title>Hints</title>
+    <section id="object-reuse">
       <title>Object reuse</title>
      <p>
 If FOP is going to be used multiple times within your application
@@ -186,7 +185,7 @@ You will need to setup the driver again with a new OutputStream,
 IntputStream and renderer.
      </p>
     </section>
-    <section>
+    <section id="render-info">
       <title>Getting information on the rendering process</title>
       <p>
 To get the number of pages that were rendered by FOP you can call 
@@ -199,31 +198,149 @@ pages of each document.
       </p>
     </section>
   </section>
-  <section>
-    <title>Using FOP in a servlet</title>
-     <p>
-In the directory xml-fop/examples/servlet you can find a working example how
-to use FOP in a servlet. After building the servlet you can drop the fop.war 
-into the webapps directory of Tomcat, then go to a URL like this:
+  <section id="servlet">
+    <title>Using FOP in a Servlet</title>
+      <p>
+        Here is a minimal code snippet to demonstrate the basics:
+      </p>
+      <source>response.setContentType("application/pdf");
+Driver driver=new Driver( new InputSource("foo.fo"),
+                          response.getOutputStream());
+driver.setRenderer(Driver.RENDER_PDF);
+driver.run();</source>
+      <p>
+There are numerous problems with the code snippet above.
+Its purpose is only to demonstrate the basic concepts.
+See xml-fop/examples/servlet for a working example of FOP used in a servlet.
+After building the servlet, drop the fop.war into the webapps directory of Tomcat.
+Then access a URL as follows:
      </p>
      <p>http://localhost:8080/fop/fop?fo=/home/path/to/fofile.fo</p>
      <p>http://localhost:8080/fop/fop?xml=/home/path/to/xmlfile.xml&amp;xsl=/home/path/to/xslfile.xsl</p>
      <p>The source code for the servlet can be found under xml-fop/examples/servlet/src/FopServlet.java.</p>
-     <note>
-         Some browsers have problems handling the PDF result sent back to
-         the browser. IE is particularly bad and different versions behave
-         differently. Having a ".pdf" on the end of the URL may help.
-     </note>
+      <note>
+        Some versions of Internet Explorer will not automatically show the PDF.
+This is well-known to be a limitation of Internet Explorer, and is not a problem with the servlet.
+However, Internet Explorer can still be used to download the PDF so that it can be viewed later. Also, appending ".pdf" to the end of the URL may help.
+      </note>
   </section>
-</section>
-<section>
+  <section id="servlet-transform">
+    <title>Using FOP in a Servlet with an XSLT Transformation</title>
+    <p>
+      If both the source XML and XSL are read from files, use the TraxInputHandler:
+    </p>
+    <source>response.setContentType("application/pdf");
+XSLTInputHandler input
+  =new XSLTInputHandler(new File("foo.xml"), new File("foo.xsl"));
+Driver driver=new Driver();
+driver.setOutputStream(response.getOutputStream());
+driver.setRenderer(Driver.RENDER_PDF);
+driver.render(input.getParser(), input.getInputSource());</source>
+    <p>
+      This code snippet has the same problems as the one from the <link href="#servlet">section above</link>.
+    </p>
+    <p>
+      If your source XML is generated on the fly (for example from a database, a web service, or another servlet), create a transformer object explicitly, and use a SAX event stream to feed the transformation result into FOP:
+    </p>
+    <source>response.setContentType("application/pdf");
+Driver driver =new Driver();
+driver.setOutputStream(response.getOutputStream());
+driver.setRenderer(Driver.RENDER_PDF);
+Transformer transformer=TransformerFactory.newInstance()
+        .newTransformer(new StreamSource("foo.xsl"));
+transformer.transform(xmlsource, new SAXResult(driver.getContentHandler()));</source>
+    <p>
+      You don't have to call run() or render() on the driver object.
+    </p>
+    <p>
+      The <code>xmlsource</code> is a placeholder for your actual XML source.
+If you have to read the XML from a string, supply a <code>new StreamSource(new StringReader(xmlstring))</code>.
+Constructing and reparsing an XML string is generally less desirable than using a SAXSource if you generate your XML.
+You can alternatively supply a DOMSource as well.
+You may also use dynamically generated XSL if you like.
+    </p>
+    <p>
+      Because you have an explicit transformer object, you can also use it to explicitly set parameters for the transformation run.
+    </p>
+  </section>
+  <section id="config-external">
+    <title>Using a Configuration File</title>
+    <p>
+      To access an external configuration:
+    </p>
+    <source>org.apache.fop.apps.Options options = new Options(new File("userconfig.xml"));</source>
+    <p>
+      No further reference to the <code>options</code> variable is necessary.
+    </p>
+    <p>
+      See <link href="#multithreading">Multithreading FOP</link> for issues related to changing configuration in a multithreaded environment.
+    </p>
+  </section>
+  <section id="config-internal">
+    <title>Setting the Configuration Programmatically</title>
+    <p>
+      If you wish to set configuration options from within your embedded application, use the <code>Configuration.put</code> method. Here is an example that sets the "baseDir" configuration in a Unix environment:
+    </p>
+    <source>org.apache.fop.configuration.Configuration.put("baseDir","/my/base/dir");</source>
+    <p>
+      Here is another that sets baseDir in a Windows environment:
+    </p>
+    <source>org.apache.fop.configuration.Configuration.put("baseDir","C:\my\base\dir");</source>
+    <p>
+      See <link href="#multithreading">Multithreading FOP</link> for issues related to changing configuration in a multithreaded environment.
+    </p>
+  </section>
+  <section id="multithreading">
+    <title>Multithreading FOP</title>
+    <p>
+      FOP is not currently completely thread safe.
+Although the relevant methods of the Driver object are synchronized, FOP uses static
+variables for configuration data and loading images.
+Here are some tips to mitigate these problems:
+    </p>
+    <ul>
+      <li>To avoid having your threads blocked, create a Driver object for each thread.</li>
+      <li>If possible, do not change the configuration data while there is a Driver object rendering.
+Setup the configuration only once, preferably in the <code>init()</code> method of the servlet.
+      </li>
+      <li>If you must change the configuration data more often, or if you have multiple servlets within the same webapp using FOP, consider implementing a singleton class to encapsulate the configuration settings and to run FOP in synchronized methods.
+      </li>
+    </ul>
+  </section>
+  <section id="servlet-engine">
+    <title>Servlet Engines</title>
+    <p>
+      When using a servlet engine, there are potential CLASSPATH issues, and potential conflicts with existing XML/XSLT libraries.
+Servlet containers also often use their own classloaders for loading webapps, which can cause bugs and security problems.
+    </p>
+    <section id="tomcat">
+      <title>Tomcat</title>
+        <p>
+          Check Tomcat's documentation for detailed instructions about installing FOP and Cocoon.
+There are known bugs that must be addressed, particularly for Tomcat 4.0.3.
+        </p>
+    </section>
+    <section id="websphere">
+      <title>WebSphere 3.5</title>
+      <p>
+        Put a copy of a working parser in some directory where WebSphere can access it.
+For example, if /usr/webapps/yourapp/servlets is the CLASSPATH for your servlets, copy the Xerces jar into it (any other directory would also be fine).
+Do not add the jar to the servlet CLASSPATH, but add it to the CLASSPATH of the application server which contains your web application.
+In the WebSphere administration console, click on the "environment" button in the "general" tab.
+In the "variable name" box, enter "CLASSPATH".
+In the "value" box, enter the correct path to the parser jar file (/usr/webapps/yourapp/servlets/Xerces.jar in our example here).
+Press "OK", then apply the change and restart the application server.
+      </p>
+    </section>
+  </section>
+<section id="examples">
   <title>Examples</title>
   <p>
 The directory "xml-fop/examples/embedding" contains several working examples. 
 In contrast of the examples above the examples here primarily use JAXP for 
 XML access. This may be easier to understand for people familiar with JAXP.
   </p>
-  <section>
+  <section id="ExampleFO2PDF">
     <title>ExampleFO2PDF.java</title>
     <p>
 This example demonstrates the basic usage pattern to transform an XSL-FO
@@ -231,7 +348,7 @@ file to PDF using FOP.
     </p>
     <figure src="images/EmbeddingExampleFO2PDF.png" alt="Example XSL-FO to PDF"/>
   </section>
-  <section>
+  <section id="ExampleXML2FO">
     <title>ExampleXML2FO.java</title>
     <p>
 This example has nothing to do with FOP. It is there to show you how an XML 
@@ -241,7 +358,7 @@ classpath (ex. <fork href="http://xml.apache.org/xalan-j">Xalan</fork>).
     </p>
     <figure src="images/EmbeddingExampleXML2FO.png" alt="Example XML to XSL-FO"/>
   </section>
-  <section>
+  <section id="ExampleXML2PDF">
     <title>ExampleXML2PDF.java</title>
     <p>
 This example demonstrates how you can convert an arbitrary XML file to PDF 
@@ -259,7 +376,7 @@ strongly discourage you to do this if it isn't absolutely necessary. The
 performance is significantly higher with SAX.
     </p>
   </section>
-  <section>
+  <section id="ExampleObj2XML">
     <title>ExampleObj2XML.java</title>
     <p>
 This example is a preparatory example for the next one. It's an example that 
@@ -290,7 +407,7 @@ used. For more detailed information see other resources on JAXP (ex.
 <fork href="http://java.sun.com/xml/jaxp/dist/1.1/docs/tutorial/xslt/3_generate.html">An older JAXP tutorial</fork>).
     </p>
   </section>
-  <section>
+  <section id="ExampleObj2PDF">
     <title>ExampleObj2PDF.java</title>
     <p>
 The last example here combines the previous and the third to demonstrate 
@@ -301,7 +418,7 @@ using FOP as before.
     </p>
     <figure src="images/EmbeddingExampleObj2PDF.png" alt="Example Java object to PDF (via XML and XSL-FO)"/>
   </section>
-  <section>
+  <section id="example-notes">
     <title>Final notes</title>
     <p>
 These examples should give you an idea of what's possible. It should be easy 

src/documentation/content/xdocs/extensions.xml

@@ -4,29 +4,21 @@
 
 <document>
   <header>
-    <title>Extensions</title>
+    <title>Standard FOP Extensions</title>
   </header>
   <body>
-    <p>
-Sometimes it is desirable to have extensions to XSL-FO in order to support
-some feature of the output format which isn't covered by the XSL-FO
-specification.
-    </p>
-    <section>
-      <title>Default Extensions</title>
-      <p>
-These extension are available by default. They are automatically loaded
-and you only need to provide the correct namespace for your embedded
-XML markup.
-      </p>
-      <section>
+    <p>By "extension", we mean any data that can be placed in the input XML document that is not addressed by the XSL-FO standard.
+By having a mechanism for supporting extensions, FOP is able to add features that are not covered in the specification.</p>
+      <p>The extensions documented here are included with FOP, and are automatically available to you. If you wish to add an extension of your own to FOP, please see the <link href="dev/extensions.html">Developers' Extension Page</link>.</p>
+    <note>All extensions required the correct use of an appropriate namespace in your input document.</note>
+      <section id="svg">
         <title>SVG</title>
         <p>
-Please see the <link href="svg.html">SVG page</link> for more details.
+Please see the <link href="graphics.html#svg">SVG documentation</link> for more details.
         </p>
       </section>
-      <section>
-        <title>Bookmarks</title>
+      <section id="bookmarks">
+        <title>PDF Bookmarks</title>
         <p>
 To use this standard FOP extension, you need to add a namespace entry for
 http://xml.apache.org/fop/extensions on the root element.
@@ -53,39 +45,12 @@ property, but it isn't supported currently. See the pdfoutline.fo file in
 examples/fo/basic for a more complete example.
         </p>
       </section>
-      <section>
+      <section id="table-continue-label">
         <title>Continued-label (for table-header/-footer</title>
         <p>
 Please see examples/fo/basic/contlabel.fo
         </p>
       </section>
-    </section>
-    <section>
-      <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.
-          </li>
-          <li>
-Create a jar file with your classes, it must also include the following file
-"/META-INF/services/org.apache.fop.fo.ElementMapping". In this file you need
-to put the fully qualified classname of your element mappings class. This
-class must implement the "org.apache.fop.fo.ElementMapping" interface.
-          </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.
-          </li>
-          <li>
-Put your jar file in the classpath and then run fop over the XSL-FO file.
-          </li>
-        </ol>
-    </section>
   </body>
 </document>
 

src/documentation/content/xdocs/fo.xml

@@ -421,20 +421,6 @@ This document can be used either to validate against the FO standard, or against
 See the notes near the beginning of the document for instructions on how to use it.
           </p>
       </section>
-      <section id="landscape">
-        <title>Producing landscape pages</title>
-        <p>
-          Pages in landscape format can easily be produced by exchanging the page-height and page-width values of a simple-page-master element.
-        </p>
-        <source><![CDATA[<fo:layout-master-set>
-  <fo:simple-page-master master-name="A4-portrait" page-height="29.7cm" page-width="21cm" [..]>
-    <fo:region-body/>
-  </fo:simple-page-master>
-  <fo:simple-page-master master-name="A4-landscape" page-height="21cm" page-width="29.7cm" [..]>
-    <fo:region-body/>
-  </fo:simple-page-master>
-</fo:layout-master-set>]]></source>
-      </section>
     </section>
   </body>
 </document>

src/documentation/content/xdocs/fonts.xml

@@ -11,7 +11,16 @@
      </authors>
   </header>
 <body>
-  <section>
+  <section id="intro">
+    <title>Important</title>
+    <p>The information on this page applies primarily to the PDF renderer. The PostScript renderer
+    also supports custom fonts but doesn't support font embedding, yet. This page does 
+    <strong>not</strong> apply to the AWT, PCL, MIF and other renderers.</p>
+    <p>The AWT renderer relies upon AWT to provide the available fonts. And it's the printer 
+    driver of your operating system that decides if a font is embedded when using the AWT 
+    renderer.</p>
+  </section>
+  <section id="status">
     <title>Status</title>
     <p>FOP (building PDF files) normally supports only the base 14 font package defined in the Adobe PDF specification.
     That includes the following fonts: Helvetica, Times, Courier, Symbol and ZapfDingbats.
@@ -27,12 +36,12 @@
         The font is simply embedded into the PDF file, it is not converted.
     </note>
   </section>
-  <section>
-    <title>Adding additional Type 1 fonts</title>
+  <section id="type1">
+    <title>Adding Type 1 fonts</title>
     <p>As mentioned above you need an XML file containing font metrics to be able to use an additional font. FOP
     contains a tool that can generate such a font metrics file from a PFM file, which normally comes with the font file.
     </p>
-    <section>
+    <section id="type1-metrics">
       <title>Generating a font metrics file</title>
       <p> Run the class org.apache.fop.fonts.apps.PFMReader to generate the XML file.
       </p>
@@ -61,7 +70,7 @@ java -cp build/fop.jar:lib/avalon-framework.jar:lib/xml-apis.jar:
       appear to have no visible influence.
       </note>
     </section>
-    <section>
+    <section id="type1-register">
       <title>Register the fonts within FOP</title>
       <p>
         Edit conf/userconfig.xml and add entries for the font
@@ -92,13 +101,13 @@ java -cp build/fop.jar:lib/avalon-framework.jar:lib/xml-apis.jar:
       </note>
     </section>
   </section>
-  <section>
-    <title>Adding additional TrueType</title>
+  <section id="truetype">
+    <title>Adding TrueType Fonts</title>
         <p>Adding TrueType fonts is almost identical to the process of
         adding Type 1 fonts. The main difference is in the first
         step.</p>
 
-    <section>
+    <section id="truetype-metrics">
       <title>Generating a font metrics file</title>
             <p>As mentioned above you need an XML file containing font
             metrics to be able to use an additional font. FOP contains
@@ -113,10 +122,10 @@ java -cp build/fop.jar:lib/avalon-framework.jar:lib/xml-apis.jar:
 java -cp build\fop.jar;lib\avalon-framework.jar;lib\xml-apis.jar;
          lib\xercesImpl.jar;lib\xalan.jar
            org.apache.fop.fonts.apps.TTFReader
-             C:\myfonts\cmr10.ttf C:\myfonts\cmr10.ttf ttfcm.xml
+             C:\myfonts\cmr10.ttf ttfcm.xml
 </source>
     </section>
-    <section>
+    <section id="truetype-collections">
       <title>TrueType collections</title>
       <p>
       TrueType collections (.ttc files) contains more than one
@@ -141,7 +150,7 @@ java -cp build\fop.jar;lib\avalon-framework.jar;lib\xml-apis.jar;
 </source>
     </section>
 
-      <section>
+      <section id="truetype-register">
         <title>Register the fonts within FOP</title>
         <p>
           Similiar to Type 1 fonts.
@@ -153,16 +162,34 @@ java -cp build\fop.jar;lib\avalon-framework.jar;lib\xml-apis.jar;
       </section>
 
   </section>
-  <section>
+  <section id="embedding">
     <title>Embedding fonts</title>
     <p>
-      Font embedding is enabled in the userconfig.xml file and controlled over the embed-file attribute.
-      If you don't specify the embed-file attribute the fonts doesn't get embedded but only referenced.
+      Font embedding is enabled in the userconfig.xml file and controlled by the embed-file attribute.
+      If you don't specify the embed-file attribute the font will not be embedded, but will only be referenced.
+    </p>
+    <p>
+      When FOP embeds a font, it scrambles its fontname by inserting a prefix that ensures that the fontname will not match the fontname of an installed font.
+This is helpful with older versions of Acrobat Reader that preferred installed fonts over embedded fonts.
+    </p>
+    <p>
+      When embedding PostScript fonts, the entire font is always embedded.
+    </p>
+    <p>
+      When embedding TrueType fonts (ttf) or TrueType Collections (ttc), a new font, containing only the glyphs used, is created from the original font and embedded in the pdf.
+Currently, this embedded font contains only the minimum data needed to be embedded in a pdf document, and does not contain any codepage information.
+The PDF document contains indexes to the glyphs in the font instead of to encoded characters.
+While the document will be displayed correctly, the net effect of this is that searching, indexing, and cut-and-paste will not work properly.
+    </p>
+    <p>
+      One workaround for this behavior is to use the -ansi option when generating metrics with TTFReader.
+This will cause the whole font to be embedded in the pdf document.
+Characters will be WinAnsi encoded (as specified in the PDF spec), so you lose the ability to use characters from other character sets.
     </p>
-    <note>
-      Remember to start fop with -c conf/userconfig.xml on the command line.
-    </note>
   </section>
+  <note>
+    Be sure to start FOP with the option to find the config file ("-c conf/userconfig.xml" from the command line). Otherwise, it has no way of finding your custom font information.
+  </note>
 </body>
 </document>
 

src/documentation/content/xdocs/gethelp.xml

@@ -1,50 +1,83 @@
 <?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">
-
-
-<!-- How to get Help -->
 <document>
-    <header>
-        <title>How to Get Help</title>
-        <subtitle>Solving problems</subtitle>
-    </header>
-
-    <body>
-<section>
-  <title>How to get Help</title>
-  <ol>
-    <li>
-      Have a look at the documentation pages on this site. You can find information on how to run FOP,
-      how to embed it, how to add custom fonts etc.
-    </li>
-    <li>
-      Consult the <link href="faq.html">FAQ</link> to see if your question has already been answered before.
-    </li>
-    <li>
-      If you have a question concerning XSL:FO that is not related to FOP directly, please consult the various
-      resources on the net. See <link href="resources.html">Resources</link> for some interesting links.
-    </li>
-    <li>
-      Before you post your questions to one of the mailing lists, please search the mailing list archives, since it's
-      possible that your question has already been answered but it may not have found its way into the FAQ. You'll
-      find links to the mailing list archive in the <link href="resources.html">Resources</link>.
-    </li>
-    <li>
-      If you still can't solve your problem subscribe to FOP's user mailing list and post your question there. Please
-      don't forget to supply the version you're using, detailed error messages etc. This makes it easier to help you.
-      The instructions on how to subscribe can be found in the <link href="resources.html">Resources</link>
-    </li>
-    <li>
-You should probably read ESR's
-<link href="http://www.tuxedo.org/~esr/faqs/smart-questions.html">"How to Ask Questions the Smart Way"</link>
-    </li>
-  </ol>
-    <note>
-      Please don't use Bugzilla to post questions and please ask on the user mailing list first, if you think you've
-      found a bug.
-    </note>
-</section>
-    </body>
+  <header>
+    <title>Getting Help</title>
+    <subtitle>Checklist for Finding Appropriate Resources</subtitle>
+  </header>
+  <body>
+    <p>The FOP developer community is eager to help you maximize the usefulness of FOP.
+However, to make wise use of its limited resources, support must be primarily self-service.
+Go through the following checklist sequentially to determine what kind of help you need,
+and where to get it:</p>
+    <section id="underlying">
+      <title>Understand Underlying Technologies</title>
+      <p>If you have a questions about XML, XSLT, or XSL-FO that are not directly related to FOP, please consult resources that are appropriate for those questions.
+FOP is an implementation of these technologies, and when you use FOP, there is a presumption that you have a working understanding of them.
+We have included several useful links on our <link href="resources.html">Resources</link> page that may help you get started.
+        </p>
+    </section>
+    <section id="compliance">
+      <title>Review FOP's Standards Compliance</title>
+      <p>FOP is a work in progress, and does not yet fully comply with the W3C XSL-FO standard.
+The developers track which standard requirements have been implemented, and have documented these capabilities on the <link href="compliance.html">Compliance</link> page.
+If this document appears to be in error, continue down this checklist so that either the document or the software can be corrected.
+Otherwise, please do not submit mailing list questions or bug reports regarding features documented in the standard.
+Please especially do not submit questions asking when a particular feature will be implemented.
+There are too many unknowns to make even a reasonable estimate.
+The only sure way to get a feature implemented is to <link href="#how-to-help">pitch in and help</link>.</p>
+    </section>
+    <section id="doc">
+      <title>Read the Documentation</title>
+      <p>Review the documentation pages on this site.
+There is information about how to run FOP, how to embed it, how to add custom fonts etc.</p>
+    </section>
+    <section id="faq">
+      <title>Check the FAQs</title>
+      <p>Consult the <link href="faq.html">Frequently Asked Questions (FAQ)</link> to see if your question has already been answered.</p>
+    </section>
+    <section id="user-archive">
+      <title>Review FOP User Mailing List Archive</title>
+      <p>It is possible that your question has already been answered but has not yet found its way into the FAQ.
+Links to the FOP User mailing list archives are on the <link href="resources.html#mailing-lists-fop-user">Resources</link> page.
+        </p>
+    </section>
+    <section id="existing-issue">
+      <title>Look for an Existing Issue Report</title>
+      <p>See <link href="bugs.html#issues_existing">Reported Issues</link> for instructions on how to use the list of open issues. Review these open issues to see if any match your concerns.
+If so, please do not post a mailing list question or report another issue, as these will only slow the development team down.</p>
+    </section>
+    <section id="user-mailing-list">
+      <title>Submit Question to FOP User Mailing List</title>
+      <ul>
+        <li>Subscription information is on the <link href="resources.html#mailing-lists-fop-user">Resources</link> page.</li>
+        <li>Review <link href="resources.html#mailing-lists-general">General Mailing List Information</link> before submitting your question.</li>
+        <li>State the version of FOP you're using.</li>
+        <li>Include detailed error messages, if there are any.</li>
+        <li>Provide FO code instead of XSLT snippets or DocBook source. 
+See <link href="running.html#running_xalan">Running Xalan</link> for how to produce FO from your XML+XSLT.</li>
+        <li>Provide the shortest possible complete, <strong>self-contained</strong> FO code that demonstrates the problem.
+Include images only if they are an integral part of the question.
+Filter out any confidential material.</li>
+        <li>Include only those portions of stack traces that will be helpful in finding the problem.</li>
+        <li>Instead of attaching large PDF files or screen shots, include a small B&amp;W GIF, JPG or PNG of the area of interest.</li>
+      </ul>
+    </section>
+    <section id="enter-issue">
+      <title>Enter an Issue Report</title>
+      <p>If, and only if, you have followed all of the above steps, and believe that there is a bug or needed feature that you would like to report, please enter an issue in Bugzilla. Never use Bugzilla to post questions, only to enter issues that have already been asked on the user mailing list.</p>
+      <p>See <link href="bugs.html#issues_new">Reporting New Issues</link> for detailed instructions on how to enter an issue.
+      </p>
+    </section>
+    <section id="how-to-help">
+      <title>Find Out How <em>You</em> Can Help</title>
+    </section>
+    <p>As stated above, the FOP development team is a limited resource. Most make their livings doing things other than writing and supporting FOP. Perhaps you need a feature from the XSL-FO standard to be implemented right away, or a bug fixed, or a new output format, or .... If so, there are several ways that you can help:</p>
+    <ul>
+      <li>Become a <link href="dev/index.html">FOP developer</link>.</li>
+      <li>Fund a developer (or part of one). There is usually at least one FOP developer who would be glad to devote more time to FOP development if funding were in place.</li>
+      <li>Help out on the user mailing list. Users giving good answers to other users allows developers to focus more on development and less on support.</li>
+    </ul>
+  </body>
 </document>
-

src/documentation/content/xdocs/graphics.xml

@@ -20,7 +20,12 @@
         <tr>
           <td>BMP (Microsoft Windows Bitmap)</td>
           <td>bitmap</td>
-          <td><link href="#native">FOP native</link></td>
+          <td><link href="#jimi">JIMI</link> or <link href="#jai">JAI</link></td>
+        </tr>
+        <tr>
+          <td>CUR</td>
+          <td>unknown</td>
+          <td><link href="#jimi">JIMI</link></td>
         </tr>
         <tr>
           <td><link href="#eps">EPS</link> (Encapsulated PostScript)</td>
@@ -32,25 +37,75 @@
           <td>bitmap</td>
           <td><link href="#native">FOP native</link></td>
         </tr>
+        <tr>
+          <td>FPX</td>
+          <td>unknown</td>
+          <td><link href="#jai">JAI</link></td>
+        </tr>
+        <tr>
+          <td>ICO (Sun Icon)</td>
+          <td>bitmap</td>
+          <td><link href="#jimi">JIMI</link></td>
+        </tr>
         <tr>
           <td><link href="#jpeg">JPEG</link> (Joint Photographic Experts Group)</td>
           <td>bitmap</td>
           <td><link href="#native">FOP native</link></td>
         </tr>
+        <tr>
+          <td>PCX (PC Paintbrush)</td>
+          <td>bitmap</td>
+          <td><link href="#jimi">JIMI</link></td>
+        </tr>
+        <tr>
+          <td>PICT (Macintosh PICT)</td>
+          <td>metafile</td>
+          <td><link href="#jimi">JIMI</link></td>
+        </tr>
         <tr>
           <td>PNG (Portable Network Graphic)</td>
           <td>bitmap</td>
           <td><link href="#jimi">JIMI</link> or <link href="#jai">JAI</link></td>
         </tr>
+        <tr>
+          <td>PNM (Portable aNyMap Utilities, part of the Portable Bitmap Utilies, aka pbmplus. PNM is a superset encompassing PBM or Portable Bitmap, PGM or Portable Grayscale, and PPM or Portable Pixmap.)</td>
+          <td>bitmap</td>
+          <td><link href="#jai">JAI</link></td>
+        </tr>
+        <tr>
+          <td>PSD (Adobe Photoshop)</td>
+          <td>bitmap</td>
+          <td><link href="#jimi">JIMI</link></td>
+        </tr>
+        <tr>
+          <td>RAS (Sunraster)</td>
+          <td>bitmap</td>
+          <td><link href="#jimi">JIMI</link></td>
+        </tr>
         <tr>
           <td><link href="#svg">SVG</link> (Scalable Vector Graphics)</td>
           <td>vector (with embedded bitmaps)</td>
           <td><link href="#batik">Batik</link></td>
         </tr>
         <tr>
-          <td><link href="#tiff">TIFF</link> (Tag Image Format File)</td>
+          <td>TGA (Targa)</td>
+          <td>bitmap</td>
+          <td><link href="#jimi">JIMI</link></td>
+        </tr>
+        <tr>
+          <td>TIFF (Tag Image Format File)</td>
+          <td>bitmap</td>
+          <td><link href="#jimi">JIMI</link> or <link href="#jai">JAI</link></td>
+        </tr>
+        <tr>
+          <td>XBM (X BitMap)</td>
           <td>bitmap</td>
-          <td><link href="#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>
+          <td><link href="#jimi">JIMI</link></td>
+        </tr>
+        <tr>
+          <td>XPM (X PixMap)</td>
+          <td>bitmap</td>
+          <td><link href="#jimi">JIMI</link></td>
         </tr>
       </table>
     </section>
@@ -66,15 +121,14 @@
         <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.
+Then, copy the file "JimiProClasses.zip" from the archive to xml-fop/lib/jimi-1.0.jar. Please note that FOP binary distributions are compiled with JIMI support, so there is no need for you to build FOP to add the support. If jimi-1.0.jar is installed in the right place, it will automatically be used by FOP, otherwise it will not.
         </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.
+To use it, simply install <link href="http://java.sun.com/products/java-media/jai">JAI</link>.
 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>
@@ -222,10 +276,6 @@ into a raster graphic are not drawn properly in PDF. The image is opaque.
         </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>
@@ -237,20 +287,5 @@ into a raster graphic are not drawn properly in PDF. The image is opaque.
       <p>If you need a higher apparent output resolution for bitmapped images, first make sure that at least one dimension of the image is defined in your XSL-FO input. Apart from that, resolution problems are in the image file itself, and must be corrected there: use or create a higher-resolution image file.</p>
       <note>The explanation above describes only the basic default behavior. There are other attributes of the fo:external-graphic element that can affect the behavior described above.</note>
     </section>
-    <section id="caching">
-      <title>Image caching</title>
-      <p>
-        FOP caches images between runs. The URL is used as a key to identify images which means that when
-        a particular URL appears again, the image is taken from the cache. If you have a servlet that
-        generates a different image each time it is called with the same URL you need to use a constantly 
-        changing dummy parameter on the URL to avoid caching.
-      </p>
-      <p>
-        Currently, the images are not automatically released when an OutOfMemoryError is imminent. The
-        image cache can grow to a considerable size over time when a lot of different URLs are in use.
-        Starting with version 0.20.5 you can call <code>org.apache.fop.image.FopImageFactory.resetCache()</code>
-        to manually empty the cache. Image caching will be improved as part of our redesign effort.
-      </p>
-    </section>
   </body>
 </document>

src/documentation/content/xdocs/implemented.xml

@@ -1,256 +0,0 @@
-<?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>Implemented</title>
-</header>
-<body>
-<section>
-  <title>Features</title>
-  <section>
-    <title>What's Implemented?</title>
-      <p>The following formatting objects and properties of the XSL-FO 1.0
-         W3C Recommandation are implemented. Please have also a look at the
-         section on <jump href="limitations.html">limitations</jump>.
-      </p>
-  </section>
-  <section>
-    <title>1) Formatting Objects</title>
-    <p>This section follows the table "B Formatting Object Summary" in the xsl:fo specification. At the
-       end of each sub-section you find listed what is not implemented.</p>
-
-    <section>
-      <title>B.1 Declaration and Pagination and Layout Formatting Objects</title>
-      <ul>
-        <li>root</li>
-        <li>page-sequence</li>
-        <li>page-sequence-master</li>
-        <li>single-page-master-reference</li>
-        <li>repeatable-page-master-reference</li>
-        <li>repeatable-page-master-alternatives</li>
-        <li>conditional-page-master-reference</li>
-        <li>layout-master-set</li>
-        <li>simple-page-master</li>
-        <li>region-body</li>
-        <li>region-before</li>
-        <li>region-after</li>
-        <li>region-start</li>
-        <li>region-end</li>
-        <li>flow</li>
-        <li>static-content</li>
-      </ul>
-      <p>Not implemented: declarations, color-profile, title</p>
-    </section>
-
-    <section>
-      <title>B.2 Block Formatting Objects</title>
-      <ul>
-        <li>block</li>
-        <li>block-container (limited)</li>
-      </ul>
-    </section>
-
-    <section>
-      <title>B.3 Inline Formatting Objects</title>
-      <ul>
-        <li>character</li>
-        <li>external-graphic</li>
-        <li>inline</li>
-        <li>instream-foreign-object</li>
-        <li>leader</li>
-        <li>page-number </li>
-        <li>page-number-citation, see <jump href="limitations.html">limitations</jump></li>
-      </ul>
-      <p>Not implemented: bidi-override, initial-property-set, inline-container</p>
-    </section>
-
-    <section>
-      <title>B.4 Table Formatting Objects</title>
-      <ul>
-        <li>table</li>
-        <li>table-body</li>
-        <li>table-cell</li>
-        <li>table-column</li>
-        <li>table-footer</li>
-        <li>table-header</li>
-        <li>table-row</li>
-      </ul>
-      <p>Not implemented: table-and-caption, table-caption </p>
-    </section>
-
-    <section>
-      <title>B.5 List Formatting Objects</title>
-      <ul>
-        <li>list-block </li>
-        <li>list-item </li>
-        <li>list-item-body </li>
-        <li>list-item-label </li>
-      </ul>
-    </section>
-
-    <section>
-      <title>B.6 Link and Multi Formatting Objects</title>
-      <ul>
-        <li>basic-link (internal and external)</li>
-      </ul>
-      <p>Not implemented: multi-switch, multi-case, multi-toggle,
-         multi-properties, multi-property-set</p>
-    </section>
-
-    <section>
-      <title>B.7 Out-of-line Formatting Objects</title>
-      <ul>
-        <li>footnote</li>
-        <li>footnote-body</li>
-      </ul>
-      <p>Not implemented: float</p>
-    </section>
-
-    <section>
-      <title>B.8 Other Formatting Objects</title>
-      <ul>
-        <li>wrapper</li>
-        <li>marker, retrieve marker</li>
-      </ul>
-    </section>
-  </section>
-
-  <section>
-    <title>2) Properties</title>
-  <p>Property values can be computed. Compound properties are also understood by Fop.</p>
-    <ul>
-      <li>background-color </li>
-      <li>background-image </li>
-      <li>blank-or-not-blank</li>
-      <li>border-after-color</li>
-      <li>border-after-style</li>
-      <li>border-after-width</li>
-      <li>border-before-color</li>
-      <li>border-before-style</li>
-      <li>border-before-width</li>
-      <li>border-bottom</li>
-      <li>border-bottom-color</li>
-      <li>border-bottom-style</li>
-      <li>border-bottom-width</li>
-      <li>border-color (only one value allowed) </li>
-      <li>border-end-color</li>
-      <li>border-end-style</li>
-      <li>border-end-width</li>
-      <li>border-left</li>
-      <li>border-left-color</li>
-      <li>border-left-style</li>
-      <li>border-left-width</li>
-      <li>border-right</li>
-      <li>border-right-color</li>
-      <li>border-right-style</li>
-      <li>border-right-width</li>
-      <li>border-start-color</li>
-      <li>border-start-style</li>
-      <li>border-start-width</li>
-      <li>border-style</li>
-      <li>border-top</li>
-      <li>border-top-color</li>
-      <li>border-top-style</li>
-      <li>border-top-width</li>
-      <li>border-width</li>
-      <li>bottom</li>
-      <li>break-after </li>
-      <li>break-before </li>
-      <li>character</li>
-      <li>color </li>
-      <li>column-count</li>
-      <li>column-gap</li>
-      <li>column-width </li>
-      <li>country</li>
-      <li>end-indent </li>
-      <li>extent </li>
-      <li>external-destination</li>
-      <li>flow-name </li>
-      <li>font-family </li>
-      <li>font-size </li>
-      <li>font-style </li>
-      <li>font-weight </li>
-      <li>height</li>
-      <li>hyphenate</li>
-      <li>hyphenation-character</li>
-      <li>hyphenation-push-character-count</li>
-      <li>hyphenation-remain-character-count</li>
-      <li>id</li>
-      <li>initial-page-number</li>
-      <li>internal-destination</li>
-      <li>keep-with-next (broken)</li>
-      <li>language</li>
-      <li>leader-alignment (not value "page")</li>
-      <li>leader-length (see limitations)</li>
-      <li>leader-pattern (not value "use-content")</li>
-      <li>leader-pattern-width</li>
-      <li>left</li>
-      <li>letter-spacing</li>
-      <li>line-height </li>
-      <li>margin (only on pages and regions) </li>
-      <li>margin-bottom (only on pages and regions) </li>
-      <li>margin-left (only on pages and regions) </li>
-      <li>margin-right (only on pages and regions) </li>
-      <li>margin-top (only on pages and regions) </li>
-      <li>master-name </li>
-      <li>master-reference </li>
-      <li>maximum-repeats</li>
-      <li>number-columns-spanned</li>
-      <li>odd-or-even</li>
-      <li>padding (only one value allowed) </li>
-      <li>padding-after</li>
-      <li>padding-before</li>
-      <li>padding-bottom </li>
-      <li>padding-end</li>
-      <li>padding-left  </li>
-      <li>padding-right  </li>
-      <li>padding-start</li>
-      <li>padding-top  </li>
-      <li>page-height </li>
-      <li>page-position</li>
-      <li>page-width </li>
-      <li>position (allowed values: "static" (default),"relative", "absolute", fixed ) </li>
-      <li>provisional-distance-between-starts </li>
-      <li>provisional-label-separation </li>
-      <li>ref-id </li>
-      <li>region-name</li>
-      <li>right</li>
-      <li>rule-style</li>
-      <li>rule-thickness </li>
-      <li>space-after.optimum </li>
-      <li>space-before.optimum </li>
-      <li>span</li>
-      <li>src </li>
-      <li>start-indent </li>
-      <li>table-omit-footer-at-break</li>
-      <li>table-omit-header-at-break</li>
-      <li>text-align </li>
-      <li>text-align-last </li>
-      <li>text-decoration</li>
-      <li>text-indent </li>
-      <li>top</li>
-      <li>white-space-collapse</li>
-      <li>width</li>
-      <li>wrap-option</li>
-    </ul>
-    <p>All other properties are not implemented.</p>
-  </section>
-
-  <section>
-    <title>3)SVG Support</title>
-<p>
-FOP uses <jump href="http://xml.apache.org/batik/">Batik</jump> directly for its SVG support. Therefore FOP supports the same
-elements and properties as are supported by Batik. As FOP is designed for
-rendering to a static medium then only static SVG is rendered.
-</p>
-<p>
-Due to some limitations in PDF some SVG images, particularly ones with effects
-or transparency, may not come out correctly. The images should still be renderedcorrectly for the AWT and Print renderers.
-</p>
-  </section>
-</section>
-</body>
-</document>
-

src/documentation/content/xdocs/index.xml

@@ -7,67 +7,42 @@
     <title>FOP</title>
   </header>
   <body>
-    <section>
+    <section id="intro">
       <title>Introduction</title>
     <p>FOP (Formatting Objects Processor) is the world's first print formatter driven by XSL formatting
-       objects and the world's first output independent formatter. It is a
-       Java application that reads a formatting object tree and then
+       objects (XSL-FO) and the world's first output independent formatter. It is a
+       Java application that reads a formatting object (FO) tree and
        renders the resulting pages to a specified output. <link href="output.html">Output formats</link>
-       currently supported are PDF, PCL, PS, SVG, XML (area tree representation),
+       currently supported include PDF, PCL, PS, SVG, XML (area tree representation),
        Print, AWT, MIF and TXT.
        The primary output target is PDF.
     </p>
-    <note>
-      The PDF files on this site are created using current CVS.
-    </note>
         <figure width="480" height="260" src="images/document.jpg" alt="Render Diagram" />
-    <p>The latest version of FOP is 0.20.5 and it supports the
+    <p>The latest version of FOP (0.20.5) is a partial implementation of the
        <link href="http://www.w3.org/TR/2001/REC-xsl-20011015/">XSL-FO Version 1.0
        W3C Recommendation</link>.
-       You can <link href="download.html">download</link>
-       FOP including a precompiled version, the source code and many example files to
-       get you started. Pointers to introductions into xsl:fo can be found in the
-       <link href="resources.html">resources</link> section. Please be aware, that
-       FOP is at the moment not a full implementation of the basic conformance level
-       of the xsl:fo standard. You can find a list of supported flow objects and properties
-       in the section <link href="implemented.html">Features</link> and in section
-       <link href="limitations.html">Limitations</link> in what way this support is
-       limited.
+       Support for each of the standard's objects and properties is detailed in <link href="compliance.html">FOP Compliance</link>.
+       <link href="download.html">Download</link> options include a precompiled version, source code, and many example files to get you started. <link href="resources.html">Resources</link> include links to XSL-FO introductions and many other useful references. A checklist for <link href="gethelp.html">Getting Help</link> will guide you toward maximizing the usefulness of FOP.
     </p>
-    <p>FOP is part of Apache's XML project. The homepage of FOP is
-       <link href="http://xml.apache.org/fop">http://xml.apache.org/fop</link>.
-       Here you can find information about using and developing with FOP.
+    <p>FOP is proud to be part of <link href="http://xml.apache.org">Apache's XML project</link>.
     </p>
-    <p>Users can subscribe to fop-user@xml.apache.org by sending an email
-        to <link href="mailto:fop-user-subscribe@xml.apache.org">fop-user-subscribe@xml.apache.org</link>
-        this is where user specific topics are discussed.
-     </p>
     </section>
 
-  <section>
-    <title>Formatting</title>
+  <section id="demo">
+    <title>Demonstration</title>
         <figure width="480" height="260" src="images/layout.jpg" alt="Formatting Diagram" />
 <p>
-This image is a demonstration of a two page document. The xml data on the left
-is formatted into the two pages on the right. The document contains static areasthat appear on every page, an external graphic in this case an svg document.
-There is a footnote on the first page and a table that goes across both pages.
+This image is a demonstration of a real two page document. The xml data on the left
+is formatted into the two pages on the right. The document contains static areas that appear on every page, an external graphic, a footnote on the first page, and a table that goes across both pages.
 </p>
 <p>
-The advantage of XSL is the ability to take an XML document and to format
-the information into a page layout. The XML document can be generated
-in any way, the most common would be to use XSLT. FOP takes the XML
-and formats the data into pages. The pages are then rendered to the
-requested output.
-</p>
-<p>
-This is a real document. The image was created by rendering the document
-to the svg renderer then putting the rendered pages into an svg document
-along with the xml.
-</p>
+FOP uses the standard XSL-FO file format as input, lays the content out into pages, then renders it to the requested output.
+One great advantage to using XSL-FO as input is that XSL-FO is itself an XML file, which means that it can be conveniently created from a variety of sources.
+The most common method is to convert semantic XML to XSL-FO, using an XSLT transformation.</p>
   </section>
-  <section>
+  <section id="objectives">
     <title>FOP Objectives</title>
-    <p>The goals of the Apache XML FOP Project are to deliver an XSL FO->PDF formatter that is compliant to at least the Basic
+    <p>The goals of the Apache XML FOP Project are to deliver an XSL-FO to PDF formatter that is compliant to at least the Basic
        conformance level described in the W3C Recommendation from 15 October 2001, and that complies with the 11 March 1999 Portable Document
        Format Specification (Version 1.3) from Adobe Systems.
     </p>
@@ -77,10 +52,11 @@ along with the xml.
        Project will attempt to use the latest version of evolving specifications.
     </p>
 
-   <p>To reach this aim currently the layout system is being redesigned to
-better handle the formatting of all different types of formatting objects.
-   </p>
+   <p>The FOP layout system is currently being rewritten to better support the XSL-FO standard.</p>
   </section>
+  <note>
+    The PDF files on this site are created using the latest development version of FOP.
+  </note>
   </body>
 </document>
 

src/documentation/content/xdocs/involved.xml

@@ -1,90 +0,0 @@
-<?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>Getting Involved</title>
-        <subtitle>How to Get Involved in FOP</subtitle>
-    </header>
-
-    <body>
-<section>
-  <title>Getting involved</title>
-  <p>
-There are many different levels where people can get involved. The
-development of FOP and the related plans and tasks are discussed on
-the dev mailing list. Users can help or get issues resolved by
-contributing information and examples to the developers.
-</p>
-
-  <section>
-    <title>Get familiar with the 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 under
-<link href="resources.html">Resources</link>.
-</p>
-  </section>
-  <section>
-    <title>Fop's Design</title>
-    <p>
-The design for FOP is specified under the
-<link href="http://xml.apache.org/fop/design/index.html">Design</link> section.
-    </p>
-    <p>
-This is where the information on how FOP is developed and designed
-internally will be kept.
-    </p>
-  </section>
-
-  <section>
-    <title>Subscribe to the fop developers list</title>
-  <p>You can subscribe to fop-dev@xml.apache.org by sending an email
-        to <link href="mailto:fop-dev-subscribe@xml.apache.org">fop-dev-subscribe@xml.apache.org</link></p>
-  <p>Sending bug reports and feature requests to the list is a welcome and important contribution to
-     developing Fop.  </p>
-  <p>Read also the <link href="http://marc.theaimsgroup.com/?l=fop-dev&amp;r=1&amp;w=2">archive</link>
-     of the discussion list fop-dev to get an idea of the issues being discussed. </p>
-  </section>
-  <section>
-    <title>Look at the developer's 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>
-  <p>All changes to the code repository are sent to a special mailing list. After a cvs commit the diffs are automatically sent to this list. You can subscribe
-     to fop-cvs@xml.apache.org by sending an email to <link href="mailto:fop-cvs-subscribe@xml.apache.org">
-     fop-cvs-subscribe@xml.apache.org</link>. If you want to contribute to the development of Fop you should subscribe,
-     because it is important that you follow changes being made. </p>
-  </section>
-  <section>
-    <title>Contributing code, tests and documentation</title>
-  <p>If you want to contribute code (p.e. a bugfix), a test or documentation (p.e. an additional example), please do the following: </p>
-  <p>1) Make sure your code doesn't break the existing one and that Fop still compiles.</p>
-  <p>2) Create a file which shows the differences to the existing code.</p>
-  <p>3) Send this file as an <strong>Attachment</strong> to <link href="mailto:fop-dev@xml.apache.org">fop-dev@xml.apache.org.</link></p>
-  <p>One of the committers will test your code and commit it to the code repository.</p>
-  <p>If you have a test or useful bug test you should <link href="testing.html">read this page</link>.</p>
-  <p>BTW: The Apache project knows different roles for contributors, namely 'users', 'developers', 'committers' and the 'Project
-     Management Committee' (An explanation of these roles can be found <link href="http://xml.apache.org/roles.html">here</link>).</p>
-  </section>
-
-  <section>
-    <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>
-

src/documentation/content/xdocs/limitations.xml

@@ -1,79 +0,0 @@
-<?xml version="1.0"?>
-<!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>Limitations</title>
-    </header>
-
-    <body>
-<section>
-  <title>Limitations</title>
-  <p>FOP implements the fo objects and properties listed
-     in <jump href="implemented.html">features</jump>, sometimes it does so only in a limited way.
-  </p>
-
-  <section>
-    <title>fo:leader</title>
-    <p>leader-length.minimum is not used at all</p>
-  </section>
-
-  <section>
-    <title>page-number-citation</title>
-    <p>Only works for table of contents without any problems. The case where the page number doesn't
-    fit on a line isn't handled, and any text on the same line and after the page-number might not
-    appear exactly where you want it to.
-    </p>
-  </section>
-
-  <section>
-    <title>Padding</title>
-    <p>Padding works in conjunction with indents and spaces. It is only implemented
-       for blocks. At the moment padding can't be used to make extra space (indents+spaces
-       must be used), but only to control how much the background-color extends beyond
-       the content rectangle.
-    </p>
-  </section>
-  <section>
-    <title>Tables</title>
-    <p>There two limitations for tables: 1) FOP needs you to explicitly specify column widths
-       2) Cells have to contain block-level FOs. They can't contain straight character data.
-    </p>
-    <p>A working basic example of a table looks like this: </p>
-  <source><![CDATA[
-<fo:table>
- <fo:table-column column-width="150pt"/>
- <fo:table-column column-width="150pt"/>
- <fo:table-body font-size="10pt" font-family="sans-serif">
-  <fo:table-row>
-   <fo:table-cell>
-    <fo:block>text</fo:block>
-   </fo:table-cell>
-   <fo:table-cell>
-    <fo:block>text</fo:block>
-   </fo:table-cell>
-  </fo:table-row>
-  <fo:table-row>
-   <fo:table-cell>
-    <fo:block>text</fo:block>
-   </fo:table-cell>
-   <fo:table-cell>
-    <fo:block>text</fo:block>
-   </fo:table-cell>
-  </fo:table-row>
-  <fo:table-row>
-   <fo:table-cell>
-    <fo:block>text</fo:block>
-   </fo:table-cell>
-   <fo:table-cell>
-    <fo:block>text</fo:block>
-   </fo:table-cell>
-  </fo:table-row>
- </fo:table-body>
-</fo:table>]]></source>
-  </section>
-</section>
-</body>
-</document>
-

src/documentation/content/xdocs/news.xml

@@ -7,6 +7,19 @@
     <title>News</title>
   </header>
   <body>
+    <section>
+      <title>18 February 2003 - FOP 0.20.5 Release Candidate 2 available</title>
+      <p>
+      See the full text of the <link
+      href="http://archives.apache.org/eyebrowse/ReadMsg?listName=fop-dev@xml.apache.org&amp;msgNo=4509">announcement</link>.
+      </p>
+    </section>
+    <section>
+      <title>2 February 2003 - New XML PMC</title>
+      <p>
+      Jeremias Maerki and Peter B. West are now representing FOP on the XML PMC.
+      </p>
+    </section>
     <section>
 	    <title>28 January 2003 - FOP logo contest</title>
 		<p>We are looking for a new logo. FOP <link href="logocontest.html">logo
@@ -44,7 +57,7 @@
   <p>Welcome Oleg Tkachenko!</p>
  </section>
     <section>
-      <title>7 Jul 2002 FOP 0.20.4 released</title>
+      <title>7 July 2002 FOP 0.20.4 released</title>
       <p>
   Changes since 0.20.3 include:
       </p>
@@ -58,7 +71,7 @@
     The following JARs have been updated: Xerces to version
     2.0.1, Xalan to version 2.3.1 and Batik to version 1.5beta2.
   </li>
-  <li>Fop has been compiled with Jimi support</li>
+  <li>FOP has been compiled with Jimi support</li>
   <li>
     Logging has been changed from LogKit to Avalon's Logger
     Interface
@@ -82,7 +95,7 @@
       </p>
     </section>
     <section>
-      <title>13 Jun 2002 FOP 0.20.4 Release Candidate available</title>
+      <title>13 June 2002 FOP 0.20.4 Release Candidate available</title>
       <p>
   See the full text of the <link href=
   "http://marc.theaimsgroup.com/?l=fop-dev&amp;m=102398470424177&amp;w=4"
@@ -94,7 +107,7 @@
   <p>Welcome Jeremias Maerki, Joerg Pietschmann and Peter B. West!</p>
  </section>
 <section>
-  <title>11 March 2002 - Fop 0.20.3 released</title>
+  <title>11 March 2002 - FOP 0.20.3 released</title>
   <p>This is a maintenance release, the first version which supports the XSL-FO
    Recommendation syntax. See the
    <link href="http://marc.theaimsgroup.com/?l=xml-apache-announce&amp;m=101588818821794">

src/documentation/content/xdocs/output.xml

@@ -5,8 +5,7 @@
 <!-- Output Formats: Renderers -->
 <document>
     <header>
-        <title>Output</title>
-        <subtitle>Notes about Output Formats: Renderers</subtitle>
+        <title>FOP Output Options</title>
         <authors>
             <person name="Keiron Liddle" email="keiron@aftexsw.com"/>
             <person name="Art Welch" email=""/>
@@ -14,54 +13,34 @@
     </header>
 
     <body>
-<section>
-  <title>Output Formats</title>
     <p>
-FOP supports a number of different output formats. This is achieved by
-using different renderers that create the output.
+FOP supports multiple output formats by using a different renderer for each format.
+The renderers do not all have the same set of capabilities, sometimes because of the output format itself, sometimes because some renderers get more development attention than others.
     </p>
+<section id="general">
+  <title>General Information</title>
+  <section id="general-fonts">
+    <title>Fonts</title>
     <p>
-Here we will explain some information for uses to be able to understand
-what the renderers are doing and what difference there may be between
-different renderers.
+Most FOP renderers use a FOP-specific system for font registration.
+However, the AWT and print renderers use the java awt package, which gets its font information from the operating system registration.
+This can result in several differences, including actually using different fonts, and having different font metrics for the same font.
+The net effect is that the layout of a given FO document can be quite different between renderers that do not use the same font information.
     </p>
-<section>
-  <title>Common Information</title>
-    <p>
-Each renderer is given an area tree to render to its output format.
-The area tree is simply a representation of the pages and the placement
-of text and graphical objects on those pages.
-    </p>
-    <p>
-The renderer will be given each page as it is ready and an output stream
-to write the data out. The renderer is responsible for managing the
-output format and associated data and flow.
-    </p>
-    <p>
-Fonts and Layout - some formats (eg. PDF and AWT) rely on different
-font information. The fonts for these outputs have different sizes
-for the same point size. This means that the layout can be quite
-different for the same FO document.
-    </p>
-    <p>
-DPI - This is an important issue when creating output for printing.
-The dpi is used to convert measurements into points. For example 1in
-= 2.54cm = 72 points. It is also used when determining the size of
-images and the rendering of certain graphics in the output. Currently
-FOP uses a value of 72dpi.
+  </section>
+  <section id="general-direct-output">
+    <title>Output to a Printer or Other Device</title>
+        <p>
+The most obvious way to print your document is to use the FOP <link href="#print">print renderer</link>, which uses the Java API (AWT).
+However, you can also send output from the Postscript renderer directly to a Postscript device, or output from the PCL renderer directly to a PCL device.
     </p>
     <p>
-You may want to send your output directly to a printer. The print
-renderer can use the Java API to print the document. You might also be
-able to send the output stream directly to a printer. If your printer
-supports postscript you could send the postscript to the printer. If
-you have a printer that supports PCL you could stream the PCL document
-to your printer.
-On Windows, you can use:
+Here are Windows command-line examples for Postscript and PCL:
     </p>
-<source><![CDATA[fop ... -ps \\computername\printer or fop ... -pcl \\computername\printer]]></source>
+    <source><![CDATA[fop ... -ps \\computername\printer]]></source>
+    <source><![CDATA[fop ... -pcl \\computername\printer]]></source>
     <p>
-On UNIX:
+Here is some Java code to accomplish the task in UNIX:
     </p>
 <source><![CDATA[proc = Runtime.getRuntime().exec("lp -d" + print_queue + " -o -dp -");
 out = proc.getOutputStream();]]></source>
@@ -69,10 +48,11 @@ out = proc.getOutputStream();]]></source>
 Set the OutputStream (out) to the PCLRenderer and it happily sends the
 PCL to the UNIX printer queue.
     </p>
+  </section>
 </section>
-<section>
+<section id="pdf">
   <title>PDF</title>
-    <p>
+  <p>
 PDF is the best supported output format. It is also the most accurate
 with text and layout. This creates a PDF document that is streamed out
 as each page is rendered. This means that the internal page index
@@ -80,8 +60,10 @@ information is stored near the end of the document.
 The PDF version supported is 1.3 which is currently the most popular
 version for Acrobat Reader (4.0), PDF versions are forwards/backwards
 compatible.
-    </p>
-    <anchor id="pdf-fonts"/>
+  </p>
+  <p>Note that FOP does not currently support "tagged pdf".</p>
+  <section id="pdf-fonts">
+    <title>Fonts</title>
     <p>
       PDF has a set of fonts that are always available to all PDF viewers,
       to quote from the PDF Specification:
@@ -93,8 +75,81 @@ Helvetica, and Times), as well as two symbolic fonts (Symbol and ITC Zapf
 Dingbats). These fonts, or suitable substitute fonts with the same metrics, are
 guaranteed to be available in all PDF viewer applications."</em>
     </p>
+  </section>
+  <section id="pdf-postprocess">
+    <title>Post-processing</title>
+    <p>FOP does not currently support several desirable PDF features: document properties (title, author, etc.), and watermarks. One workaround is to use Adobe Acrobat (the full version, not the Reader) to process the file manually or with scripting that it supports.</p>
+    <p>Another popular post-processing tool is <link href="http://www.lowagie.com/iText">iText</link>, which has tools for adding security features, document properties, watermarks, and many other features to PDF files.
+    </p>
+    <warning>Caveat: iText swallows PDF bookmarks.</warning>
+    <p>Here is some sample code that uses iText to encrypt a FOP-generated PDF. (Note that FOP now supports <link href="pdfencryption.html">PDF encryption</link>. However the principles for using iText for other PDF features are similar.)</p>
+    <source><![CDATA[public static void main(String args[]) {
+  try {
+    ByteArrayOutputStream fopout=new ByteArrayOutputStream();
+    FileOutputStream outfile=new FileOutputStream(args[2]);
+    Driver driver =new Driver();
+    driver.setOutputStream(fopout);
+    driver.setRenderer(Driver.RENDER_PDF);
+    Transformer transformer=TransformerFactory
+      .newInstance().newTransformer(new StreamSource(new File(args[1])));
+    transformer.transform(new StreamSource(new File(args[0])),
+       new SAXResult(driver.getContentHandler()));
+    PdfReader reader = new PdfReader(fopout.toByteArray());
+    int n = reader.getNumberOfPages();
+    Document document = new Document(reader.getPageSizeWithRotation(1));
+    PdfWriter writer = PdfWriter.getInstance(document, outfile);
+    writer.setEncryption(PdfWriter.STRENGTH40BITS, "pdf", null,
+      PdfWriter.AllowCopy);
+    document.open();
+    PdfContentByte cb = writer.getDirectContent();
+    PdfImportedPage page;
+    int rotation;
+    int i = 0;
+    while (i < n) {
+      i++;
+      document.setPageSize(reader.getPageSizeWithRotation(i));
+      document.newPage();
+      page = writer.getImportedPage(reader, i);
+      rotation = reader.getPageRotation(i);
+      if (rotation == 90 || rotation == 270) {
+        cb.addTemplate(page, 0, -1f, 1f, 0, 0,
+         reader.getPageSizeWithRotation(i).height());  }
+      else {
+        cb.addTemplate(page, 1f, 0, 0, 1f, 0, 0);
+      }
+      System.out.println("Processed page " + i);
+    }
+    document.close();
+  }
+  catch( Exception e) {
+    e.printStackTrace();
+  }
+}]]></source>
+    <p>Check the iText tutorial and documentation for setting access flags, password, encryption strength and other parameters.
+    </p>
+  </section>
+  <section id="pdf-watermark">
+    <title>Watermarks</title>
+    <p>
+      In addition to the <link href="#pdf-postprocess">PDF Post-processing</link> options, consider the following workarounds:
+    </p>
+    <ul>
+      <li>
+        Use a background image for the body region.
+      </li>
+      <li>
+        (submitted by Trevor_Campbell@kaz.com.au) Place an image in a
+        region that overlaps the flowing text. For example, make
+        region-before large enough to contain your image. Then include a
+        block (if necessary, use an absolutely positioned block-container)
+        containing the watermark image in the static-content for the
+        region-before. Note that the image will be drawn on top of the
+        normal content.
+      </li>
+    </ul>
+  </section>
 </section>
-<section>
+<section id="pcl">
   <title>PCL</title>
     <p>
 This format is for the Hewlett-Packard PCL printers.
@@ -108,7 +163,7 @@ in the "HP PCL 5 Printer Language Technical Reference Manual" (copyright 1990).
 This should allow any device fully supporting PCL 5 to be able to
 print the output generated by the PCLRenderer.
     </p>
-    <section>
+    <section id="pcl-limitations">
       <title>Limitations</title>
       <ul>
         <li>Text or graphics outside the left or top of the printable area are not rendered properly. In general things that should print to the left of the printable area are shifted to the right so that they start at the left edge of the printable area and an error message is generated.</li>
@@ -124,7 +179,7 @@ print the output generated by the PCLRenderer.
       </ul>
     </section>
 
-    <section>
+    <section id="pcl-additional">
       <title>Additional Features</title>
       <p>There are some special features that are controlled by some public variables on the PCLRenderer class.</p>
 
@@ -145,7 +200,7 @@ print the output generated by the PCLRenderer.
       </dl>
     </section>
 </section>
-<section>
+<section id="ps">
   <title>PostScript</title>
     <p>
 The PostScript renderer is still in its early stages and therefore still
@@ -154,7 +209,7 @@ Images and SVG are not fully supported, yet. Currently, the PostScript
 renderer generates PostScript Level 3 with most DSC comments. Actually,
 the only Level 3 feature used is FlateDecode, everthing else is Level 2.
     </p>
-    <section>
+    <section id="ps-limitations">
       <title>Limitations</title>
       <ul>
         <li>Images and SVG may not be display correctly. SVG support is far from being complete. No image transparency is available.</li>
@@ -166,7 +221,7 @@ the only Level 3 feature used is FlateDecode, everthing else is Level 2.
       </ul>
     </section>
 </section>
-<section>
+<section id="rtf">
   <title>RTF</title>
     <p>
 This is currently not integrated with FOP but it will soon.
@@ -175,7 +230,7 @@ attempt to contain as much information from the fo document as
 possible.
     </p>
 </section>
-<section>
+<section id="svg">
   <title>SVG</title>
     <p>
 This format creates an SVG document that has links between the pages.
@@ -188,7 +243,7 @@ same way as the AWT viewer, if the svg is view where the fonts are
 different, such as another platform, then the page will appear wrong.
     </p>
 </section>
-<section>
+<section id="xml">
   <title>XML</title>
     <p>
 This is for testing and verification. The XML created is simply
@@ -196,14 +251,14 @@ a representation of the internal area tree put into XML. It does
 not perform any other purpose.
     </p>
 </section>
-<section>
+<section id="print">
   <title>Print</title>
     <p>
 It is possible to directly print the document from the command line.
 This is done with the same code that renders to the AWT renderer.
     </p>
 </section>
-<section>
+<section id="awt">
   <title>AWT</title>
     <p>
 The AWT viewer shows a window with the pages displayed inside a
@@ -212,14 +267,14 @@ The fonts used for the formatting and viewing depend on the fonts
 available to your JRE.
     </p>
 </section>
-<section>
+<section id="mif">
   <title>MIF</title>
     <p>
 This format is the Maker Interchange Format which is used by
 Adobe Framemaker. This is currently not fully implemented.
     </p>
 </section>
-<section>
+<section id="txt">
   <title>TXT</title>
     <p>
 Text as you could imagine does not work very well. It is an output format
@@ -245,7 +300,6 @@ than text, so text will overwrite any graphic element representations.
     </p>
 </section>
 
-</section>
     </body>
 </document>
 

src/documentation/content/xdocs/pdfencryption.xml

@@ -12,7 +12,6 @@
   <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

src/documentation/content/xdocs/relnotes.xml

@@ -14,11 +14,11 @@
   <p>Important changes since the last release (0.20.4):</p>
   <ul>
     <li>Some hyphenation patterns (cs, da, de, de_DR, el, en, en_US, fr, nl,
-        no, pt, ru, sk, tr) have been removed due to licensing reasons. 
-        We hope to resolve this issue until the final release.
+        no, pt, ru, sk, tr) have been removed due to licensing reasons.
+        We hope to resolve this issue before the final release.
         (English hyphenation is still available as en_GB)
     </li>
-    <li>Documentation is done with <link href="http://xml.apache.org/forrest/">
+    <li>Documentation is now built with <link href="http://xml.apache.org/forrest/">
         Forrest</link> (version 0.3). You need to install Forrest if you want build the docs
         yourself. (See
         <link href="http://xml.apache.org/forrest/your-project.html">Using Forrest</link>)
@@ -26,19 +26,21 @@
     <li>The following JARs have been updated:
         Xerces to version 2.2.1, Xalan to version 2.4.1 and Batik to version 1.5beta4.
     </li>
-    <li>Fop has been compiled with Jimi support this time but you still have to download
-        <link href="http://java.sun.com/products/jimi/">Jimi</link>, extract the archive,
+    <li>FOP has been compiled with Jimi support, but Jimi is not included in the
+        FOP distribution. To use it, first download
+        <link href="http://java.sun.com/products/jimi/">Jimi</link>, then extract
+        the archive, then
         copy JimiProClasses.zip to FOP's lib dir and rename it to jimi-1.0.jar.
     </li>
-    <li>Fop has been compiled with
-        <link href="http://java.sun.com/products/java-media/jai">JAI</link>
-        support. For using JAI you just need to install it.
+    <li>FOP has been compiled with JAI support, but JAI is not included in the
+        FOP distribution. To use it, simply install
+        <link href="http://java.sun.com/products/java-media/jai">JAI</link>.
     </li>
     <li>Links in PDF won't generate multiple link rectangles anymore. If this causes
         a problem you can set the system property "links.merge" to "no".
     </li>
   </ul>
-  
+
 </section>
 <section>
   <title>FOP 0.20.4</title>
@@ -51,7 +53,7 @@
        <li>The following JARs have been updated:
          Xerces to version 2.0.1, Xalan to version 2.3.1 and Batik to version 1.5beta2.
       </li>
-      <li>Fop has been compiled with Jimi support this time
+      <li>FOP has been compiled with Jimi support this time
         but you still have to download
         <link href="http://java.sun.com/products/jimi/">Jimi</link>
         and copy it to lib/ to get PNG support (no need to build FOP yourself though).

src/documentation/content/xdocs/resources.xml

@@ -1,7 +1,6 @@
 <?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">
-
 <!-- FOP Relevant Specifications and links -->
 <document>
   <header>
@@ -9,171 +8,158 @@
     <subtitle>Resources useful for developing and using FOP</subtitle>
   </header>
   <body>
-<section>
-  <title>FOP Relevant Specifications and Links</title>
-  <section>
-    <title>Mailing Lists (and archives)</title>
-        <p>
-For the Apache mailing lists, see
-<link href="http://xml.apache.org/mail.html">Apache XML Mailing Lists</link>
-for detailed subscription information.
-        </p>
-    <section>
-      <title>FOP User Mailing List</title>
-        <p>
-Use this forum to discuss topics of interest to FOP users.
-After reviewing the FOP documentation and searching the
-archives (see below), use this forum to ask questions about
-how to download, install, configure, and use FOP. Please do
-<em>not </em>use this forum for general XSL-FO, XSLT, or PDF questions.
-        </p>
-      <ul>
-            <li>
-To review the archives, you have several options:
-              <ul>
-                <li>
-The <link href="http://marc.theaimsgroup.com/?l=fop-user&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-user@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-user">Apache Mailing List archive</link> (gzip files).
-                </li>
-              </ul>
-            </li>
-            <li>
-To subscribe (digest only): Send email to <link href="mailto:fop-user-digest-subscribe@xml.apache.org">fop-user-digest-subscribe@xml.apache.org</link>.
-            </li>
-            <li>
-To subscribe fully: Send email to <link href="mailto:fop-user-subscribe@xml.apache.org">fop-user-subscribe@xml.apache.org</link>.
-            </li>
-            <li>
-For standard help: Send email to <link href="mailto:fop-user-help@xml.apache.org">fop-user-help@xml.apache.org</link>.
-            </li>
-            <li>
-To unsubscribe: Send email to <link href="mailto:fop-user-unsubscribe@xml.apache.org">fop-user-unsubscribe@xml.apache.org</link>.
-            </li>
-      </ul>
+    <section id="mailing-lists">
+      <title>Mailing Lists and Archives</title>
+      <section id="mailing-lists-general">
+        <title>General Information</title>
+        <p>Before posting questions to any list, review "<jump href="http://www.catb.org/~esr/faqs/smart-questions.html">How To Ask Questions The Smart Way</jump>".</p>
+        <p>Be sure to set your email client to send plain text email messages to any mailing lists.
+Please do <em>not</em> send html or rtf email, as they do not work well with the archive engines.
+If you are using Microsoft Outlook, this setting can be found at the "Mail Format" tab of the Tools/Options menu.</p>
+        <p>For help in understanding email acronyms, see the <jump href="http://www.lingo2word.com/lists/acronym_listA.html">Lingo2Word Acronym List</jump>, or the <jump href="http://www.keno.org/web_design/acronyms.htm">Keno Internet Services Internet Glossary</jump>.</p>
+      </section>
+      <section id="mailing-lists-fop-user">
+        <title>FOP User Mailing List</title>
+        <p>Use this forum to discuss topics of interest to FOP users.
+After reviewing the FOP documentation and searching the archives (see below), use this forum to ask questions about how to download, install, configure, and use FOP.
+Please do <em>not</em> use this forum for general XSL-FO, XSLT, or PDF questions.</p>
+        <ul>
+          <li>To review the archives, you have several options:
+            <ul>
+              <li>The <jump href="http://marc.theaimsgroup.com/?l=fop-user&amp;r=1&amp;w=2">Mailing list ARChives </jump> (MARC) at the AIMS group (search).</li>
+              <li>The <jump href="http://nagoya.apache.org/eyebrowse/SummarizeList?listName=fop-user@xml.apache.org">Apache Eyebrowse</jump> archive (search, list by date, author, subject, or thread).</li>
+              <li>The <link href="http://xml.apache.org/mail/fop-user">Apache Mailing List archive</link> (gzip files).</li>
+            </ul>
+          </li>
+          <li>Before posting questions to any list, see "<link href="#mailing-lists-general">General Information</link>".</li>
+          <li>See <link href="http://xml.apache.org/mail.html#fop-user">Apache XML Mailing Lists</link> for detailed subscription information.</li>
+          <li>To subscribe (digest only): Send email to <link href="mailto:fop-user-digest-subscribe@xml.apache.org">fop-user-digest-subscribe@xml.apache.org</link>.</li>
+          <li>To subscribe fully: Send email to <link href="mailto:fop-user-subscribe@xml.apache.org">fop-user-subscribe@xml.apache.org</link>.</li>
+          <li>For standard help: Send email to <link href="mailto:fop-user-help@xml.apache.org">fop-user-help@xml.apache.org</link>.</li>
+          <li>To unsubscribe: Send email to <link href="mailto:fop-user-unsubscribe@xml.apache.org">fop-user-unsubscribe@xml.apache.org</link>.</li>
+        </ul>
+      </section>
+      <section id="mailing-lists-w3c-xslfo">
+        <title>XSL-FO Mailing List (at W3C)</title>
+        <p>Use this forum to ask general XSL-FO questions.</p>
+        <ul>
+          <li>To review the archive: <jump href="http://lists.w3.org/Archives/Public/www-xsl-fo/">W3C XSL-FO Archives</jump>.</li>
+          <li>Before posting questions to any list, see "<link href="#mailing-lists-general">General Information</link>".</li>
+          <li>Subscription administration information can be found at <jump href="http://www.w3.org/Mail/Request">W3C Mailing List Administrativia</jump>.
+After reviewing the instructions there, send your subscribe or unsubscribe request to <link href="mailto:www-xsl-fo-request@w3.org">www-xsl-fo-request@w3.org</link>.</li>
+        </ul>
+      </section>
+      <section id="mailing-lists-yahoogroups-xslfo">
+        <title>XSL-FO Mailing List (at YahooGroups)</title>
+        <p>Use this forum to ask general XSL-FO questions.</p>
+        <ul>
+          <li>Before posting questions to any list, see "<link href="#mailing-lists-general">General Information</link>".</li>
+          <li>The home page for this groups is <jump href="http://groups.yahoo.com/group/XSL-FO">XSL-FO - discussion of XSL Formatting Objects</jump>.</li>
+        </ul>
+      </section>
+      <section id="mailing-lists-xslt-mulberry">
+        <title>XSLT List (Mulberry Tech)</title>
+        <ul>
+          <li>Before posting questions to any list, see "<link href="#mailing-lists-general">General Information</link>".</li>
+          <li>Information for using and subscribing can be found at <jump href="http://www.mulberrytech.com/xsl/xsl-list">XSL-List -- Open Forum on XSL</jump>.</li>
+        </ul>
+      </section>
     </section>
-    <section>
-      <title>FOP Developer Mailing List</title>
-          <p>
-Use this forum to discuss topics related to FOP development,
-including patch submissions, bug reports, and design issues.
-          </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>
-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 id="specs">
+      <title>Specifications</title>
+      <section id="specs-xslfo">
+        <title>XSL-FO</title>
+        <ul>
+          <li><jump href="http://www.w3.org/TR/2001/REC-xsl-20011015/">XSL-FO Recommendation (15 October 2001)</jump></li>
+          <li><jump href="http://www.renderx.com/Tests/validator/fo.dtd.html">Unofficial DTD for the XSL-FO Recommendation</jump> provided by N. Grigoriev from RenderX.</li>
+        </ul>
+      </section>
+      <section id="specs-xslt">
+        <title>XSLT</title>
+        <ul>
+          <li><jump href="http://www.w3.org/TR/xslt">XSLT Recommendation</jump></li>
+        </ul>
+      </section>
+      <section id="specs-xml">
+        <title>XML</title>
+        <ul>
+          <li><jump href="http://www.w3.org/TR/REC-xml">XML Recommendation</jump></li>
+          <li><jump href="http://sax.sourceforge.net/">Simple API for XML (SAX)</jump></li>
+          <li><jump href="http://www.w3.org/TR/REC-DOM-Level-1">Document Object Model (DOM)</jump></li>
+          <li><jump href="http://www.w3.org/TR/REC-xml-names/">Namespaces in XML Recommendation</jump></li>
+        </ul>
+      </section>
+      <section id="specs-java">
+        <title>Java</title>
+        <ul>
+          <li><jump href="http://java.sun.com/j2se/1.3/docs/api/index.html">Java JDK 1.3 Documentation</jump></li>
+        </ul>
+      </section>
+      <section id="specs-other">
+        <title>Other</title>
+        <ul>
+          <li><jump href="http://www.w3.org/TR/SVG/">Supported SVG Recommendation (04 September 2001)</jump></li>
+          <li><jump href="http://partners.adobe.com/asn/developer/acrosdk/docs/filefmtspecs/PDFReference.pdf">Portable Document Format (PDF) 1.4 Reference Manual</jump></li>
+        </ul>
+      </section>
+    </section>
+    <section id="documents">
+      <title>Books, Tutorials, Articles</title>
+      <section id="documents-xslfo">
+        <title>XSL-FO</title>
+        <ul>
+          <li>[online book] <jump href="http://www.ibiblio.org/xml/books/bible2/chapters/ch18.html">The XML Bible</jump>, by Elliotte Rusty Harold. Chapter 18 of XSL Formatting Objects</li>
+          <li>[online article] <jump href="http://www.sun.com/software/xml/developers/slides-dtd/">Using Formatting Objects with the Slides DTD</jump>, by Paul Sandoz.</li>
+          <li>[online article] <jump href="http://www.xml.com/pub/a/2001/01/17/xsl-fo/index.html">Using XSL Formatting Objects</jump>, by J. David Eisenberg.</li>
+          <li>[online reference] <jump href="http://zvon.org/xxl/xslfoReference/Output/index.html">XSL FO reference</jump>, by Miloslav Nic.</li>
+          <li>[online book] <jump href="http://www.dpawson.co.uk/xsl/sect3/bk/index.html">An introduction to XSL Formatting Objects</jump>, by Dave Pawson. See hardcopy version below.</li>
+          <li>[book] <jump href="http://www.oreilly.com/catalog/xslfo">XSL-FO</jump>, by Dave Pawson, O'Reilly &amp; Associates, 2002, ISBN 0-596-00355-2. See online version above.</li>
+          <li>[book] <jump href="http://www.phptr.com/browse/product.asp?product_id={CEA527AF-412D-49DA-8C1F-46E0A519B8D8}">Definitive XSL-FO</jump>, by G. Ken Holman, Prentice Hall PTR, 2003, ISBN 0-131-40374-5.</li>
+          <li>[book] <jump href="http://www.sams.com/catalog/product.asp?product_id={F7ADFA46-6AF1-497C-9163-0D6337F727B3}">XSL Formatting Objects Developer's Handbook</jump>, by Doug Lovell, Sams, 2002, ISBN 0-672-32281-1.</li>
+          <li>[book] <jump href="http://www.cranesoftwrights.com/training/index.htm#pfux">Practical Formatting Using XSLFO</jump>, Crane Softwrights Ltd., 2003, ISBN 1-894049-11-X.</li>
+        </ul>
+      </section>
+      <section id="documents-xslt">
+        <title>XSLT</title>
+        <ul>
+          <li>[book] <jump href="http://wrox.com/books/1861005067.htm">XSLT Programmer's Reference</jump>, by Michael H. Kay, Wrox Press, ISBN 1-861-00506-7.</li>
+          <li>[book] <jump href="http://www.oreilly.com/catalog/xslt">XSLT</jump>, by Doug Tidwell, O'Reilly &amp; Associates, 2001, ISBN 0-596-00053-7.</li>
+          <li>[book] <jump href="http://www.oreilly.com/catalog/xsltckbk">XSLT Cookbook</jump>, by Sal Mangano, O'Reilly &amp; Associates, 2002, ISBN 0-596-00372-2.</li>
+          <li>[article] <jump href="http://www.dpawson.co.uk/xsl/xslfaq.html">Dave Pawson's XSLT FAQ</jump>.</li>
+         <li>[book] <jump href="http://www.oreilly.com/catalog/xpathpointer">XPath and XPointer: Locating Content in XML Documents</jump>, by John E. Simpson, O'Reilly &amp; Associates, 2002, ISBN 0-596-00291-2.</li>
+          <li>[book] <jump href="http://www.wiley.com/cda/product/0,,0471416207,00.html">XSL Essentials</jump>, by Michael Fitzgerald, John Wiley &amp; Sons, 2001, ISBN 0-471-41620-7.</li>
+          <li>[book] <jump href="http://www.oreilly.com/catalog/javaxslt">Java and XSLT</jump>, by Eric M. Burke, O'Reilly &amp; Associates, 2001, ISBN 0-596-00143-6.</li>
+        </ul>
+      </section>
+      <section id="documents-xml">
+        <title>XML</title>
+        <ul>
+          <li>[online book] <jump href="http://www.ibiblio.org/xml/books/bible2">The XML Bible</jump>, by Elliotte Rusty Harold. See hardcopy version below.</li>
+          <li>[book] <jump href="http://www.wiley.com/cda/product/0,,0764547607,00.html">The XML Bible</jump>, by Elliotte Rusty Harold, John Wiley &amp; Sons, ISBN 0-764-54760-7. See online version above.</li>
+          <li>[online resource] A great number of additional XML-related books and articles can be found at the <jump href="http://xml.oreilly.com">O'Reilly XML Site</jump>.</li>
+        </ul>
+      </section>
+      <section id="documents-java">
+        <title>Java</title>
+        <ul>
+          <li>[online resource] A great number of Java-related books and articles can be found at the <jump href="http://java.oreilly.com">O'Reilly Java Site</jump>.</li>
+        </ul>
+      </section>
     </section>
-    <section>
-      <title>XSL:FO Mailing List (at W3C)</title>
-          <p>
-Use this forum to ask general XSL-FO questions.
-          </p>
+    <section id="products">
+      <title>Related/Useful Products</title>
       <ul>
-            <li>
-To review the archive: <link href="http://lists.w3.org/Archives/Public/www-xsl-fo/">W3C XSL-FO Archives</link>.
-            </li>
-            <li>
-Subscription administration information can be found at <link href="http://www.w3.org/Mail/Request">W3C Mailing List Administrativia</link>. After reviewing the instructions there, send your subscribe or unsubscribe request to <link href="mailto:www-xsl-fo-request@w3.org">www-xsl-fo-request@w3.org</link>.
-            </li>
+        <li>PJ is an open source product that can be used to modify PDF documents:
+<jump href="http://www.etymon.com/pj/index.html">http://www.etymon.com/pj/index.html</jump></li>
+        <li>iText is a library that can edit PDF files, it is possible to do
+post processing of the generated PDF files: <jump href="http://www.lowagie.com/iText/">http://www.lowagie.com/iText/</jump>.</li>
+        <li>html2fo is a converter from html to xsl:fo: <jump href="http://html2fo.sourceforge.net/">http://html2fo.sourceforge.net/</jump>.</li>
+        <li>FOA is a XSL-FO Authoring tool: <jump href="http://foa.sourceforge.net/">http://foa.sourceforge.net/</jump>.</li>
+        <li>TIFFRenderer is a renderer for outputting multi-page TIFF: <jump href="http://www.tkachenko.com/fop/tiffrenderer.html">http://www.tkachenko.com/fop/tiffrenderer.html</jump>.</li>
+        <li>AFP Renderer / Batch Assembler for FOP: <jump href="http://mypage.bluewin.ch/huanderegg/">http://mypage.bluewin.ch/huanderegg/</jump>.</li>
+        <li>The <jump href="http://mogwai.sourceforge.net">Mogwai Project</jump> includes a renderer for FOP that generates output for Okidata dot matrix printers.</li>
+        <li> [software] <jump href="http://www.vbxml.com/xpathvisualizer">The XPath Visualizer</jump>. Web site says: "This is a full blown Visual XPath Interpreter for the evaluation of any XPath expression and visual presentation of the resulting nodeset or scalar value."</li>
       </ul>
     </section>
-  </section>
-  <section>
-    <title>Specifications</title>
-  <ul>
-          <li>
-            <link href="http://www.w3.org/TR/2001/REC-xsl-20011015/">XSL-FO Recommendation (15 October 2001)</link>
-          </li>
-          <li>
-            <link href="http://www.renderx.com/Tests/validator/fo.dtd.html">A dtd for the XSL-FO Recommendation provided by N. Grigoriev from RenderX</link>
-          </li>
-          <li>
-            <link href="http://www.w3.org/TR/SVG/">Supported SVG Recommendation (04 September 2001)</link>
-          </li>
-          <li>
-            <link href="http://www.w3.org/TR/REC-xml">XML Recommendation</link>
-          </li>
-          <li>
-            <link href="http://www.w3.org/TR/xslt">XSLT Recommendation</link>
-          </li>
-          <li>
-            <link href="http://partners.adobe.com/asn/developer/acrosdk/docs/filefmtspecs/PDFReference.pdf">Portable Document Format (PDF) 1.4 Reference Manual </link>
-          </li>
-          <li>
-            <link href="http://sax.sourceforge.net/">Simple API for XML (SAX)</link>
-          </li>
-          <li>
-            <link href="http://www.w3.org/TR/REC-DOM-Level-1">Document Object Model (DOM)</link>
-          </li>
-          <li>
-            <link href="http://www.w3.org/TR/REC-xml-names/">Namespaces in XML Recommendation</link>
-          </li>
-          <li>
-            <link href="http://java.sun.com/j2se/1.3/docs/api/index.html">Java JDK 1.3 Documentation</link>
-          </li>
-  </ul>
-  </section>
-  <section>
-    <title>Tutorials/Articles</title>
-    <ul>
-          <li>
-            <link href="http://www.ibiblio.org/xml/books/bible2/chapters/ch18.html">Elliotte Rusty Harold: Chapter 18 on xsl:fo from his excellent book XML Bible, Second Edition</link>
-          </li>
-          <li>
-            <link href="http://www.sun.com/software/xml/developers/slides-dtd/">Paul Sandoz: Using formatting objects with the slides dtd</link>
-          </li>
-          <li>
-            <link href="http://www.xml.com/pub/a/2001/01/17/xsl-fo/index.html">J. David Eisenberg: Using XSL Formatting Objects</link>
-          </li>
-          <li>
-            <link href="http://zvon.org/xxl/xslfoReference/Output/index.html">Miloslav Nic: XSL FO reference</link>
-          </li>
-          <li>
-            <link href="http://www.dpawson.co.uk/xsl/sect3/bk/index.html">Dave Pawson: An introduction to XSL Formatting Objects</link>
-          </li>
-    </ul>
-  </section>
-  <section>
-    <title>Related/Useful Products</title>
-    <ul>
-      <li>
-PJ is an open source product that can be used to modify PDF documents:
-<link href="http://www.etymon.com/pj/index.html">http://www.etymon.com/pj/index.html</link>
-      </li>
-      <li>
-iText is a library that can edit PDF files, it is possible to do
-post processing of the generated PDF files: <link href="http://www.lowagie.com/iText/">http://www.lowagie.com/iText/</link>.
-      </li>
-    </ul>
-  </section>
-</section>
   </body>
 </document>
-

src/documentation/content/xdocs/running.xml

@@ -3,83 +3,174 @@
     "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/schema/dtd/document-v11.dtd">
 
 <document>
-<header>
-  <title>Running FOP</title>
-</header>
+  <header>
+    <title>Running FOP</title>
+  </header>
 
-<body>
-  <section>
-    <title>Installation</title>
-    <section>
-      <title>Overview</title>
+  <body>
+    <section id="require">
+      <title>System Requirements</title>
       <p>The following software must be installed:</p>
       <ul>
-        <li>Java 1.2.x or later.</li>
-        <li>FOP. The <jump href="http://xml.apache.org/fop/download.html">FOP distribution</jump> includes all libraries that you will need to run a basic FOP installation. These can be found in the xml-fop/lib directory. These libraries include the following:</li>
-        <ul>
-          <li>Apache <jump href="http://xml.apache.org/xerces-j/index.html">Xerces-J</jump> for XML parsing. You can use other XML parsers which support SAX and DOM.</li>
-          <li>Apache Xalan, an XSLT processor.</li>
-          <li>Apache <jump href="http://xml.apache.org/batik/">Batik</jump>, an SVG library.</li>
-        </ul>
-        <li>Optional Libraries</li>
+        <li>Java 1.2.x or later Runtime Environment.</li>
+        <li>FOP. The <link href="download.html">FOP distribution</link> includes all libraries that you will need to run a basic FOP installation. These can be found in the xml-fop/lib directory. These libraries include the following:
+          <ul>
+            <li><jump href="http://xml.apache.org/xerces-j/index.html">Apache Xerces-J</jump> for XML parsing. You can use other XML parsers which support SAX and DOM.</li>
+            <li><jump href="http://xml.apache.org/xalan-j/index.html">Apache Xalan-J</jump>, an XSLT processor.</li>
+            <li><jump href="http://xml.apache.org/batik/">Apache Batik</jump>, an SVG library.</li>
+          </ul>
+        </li>
+      </ul>
+      <p>The following sofware is optional, depending on your needs:</p>
+      <ul>
+        <li>Graphics libraries. Support for some graphics formats requires additional packages. See <link href="graphics.html">FOP: Graphics Formats</link> for details.</li>
+        <li>PDF encryption. See <link href="pdfencryption.html">FOP: PDF Encryption</link> for details.</li>
+      </ul>
+      <p>In addition, the following system requirements apply:</p>
+      <ul>
+        <li>If you will be using FOP to process SVG, you must do so in a graphical environment. See <link href="graphics.html#batik">FOP: Graphics (Batik)</link> for details.</li>
       </ul>
     </section>
-    <section>
-      <title>Instructions</title>
-      <p>Basic FOP installation consists of first unzipping the <code>.gz</code> file that is the distribution medium, then unarchiving the resulting <code>.tar</code> file in a directory/folder that is convenient on your system. Please consult your operating system documentation or Zip application software documentation for instructions specific to your site.</p>
+    <section id="install">
+      <title>Installation</title>
+      <section id="install-instruct">
+        <title>Instructions</title>
+        <p>Basic FOP installation consists of first unzipping the <code>.gz</code> file that is the distribution medium, then unarchiving the resulting <code>.tar</code> file in a directory/folder that is convenient on your system. Please consult your operating system documentation or Zip application software documentation for instructions specific to your site.</p>
+      </section>
+      <section id="install-problems">
+        <title>Problems</title>
+        <p>Some Mac OSX users have experienced filename truncation problems using Stuffit to unzip and unarchive their distribution media. This is a legacy of older Mac operating systems, which had a 31-character pathname limit. Several Mac OSX users have recommended that Mac OSX users use the shell command <code>tar -xzf</code> instead.</p>
+      </section>
     </section>
-    <section>
-      <title>Problems</title>
-      <p>Some Mac OSX users have experienced filename truncation problems using Stuffit to unzip and unarchive their distribution media. This is a legacy of older Mac operating systems, which had a 31-character pathname limit. Several Mac OSX users have recommended that Mac OSX users use the shell command <code>tar -xzf</code> instead.</p>
-    </section>
-  </section>
-
-  <section>
-    <title>Starting FOP as a standalone application</title>
-    <p>Review the batch file fop.bat or the shell script fop.sh to see how FOP is invoked.</p>
-    <p>The standard scripts for starting FOP require that the environment variable JAVA_HOME be set to a path pointing to the appropriate Java installation on your system. Macintosh OSX includes a Java environment as part of its distribution. We are told by Mac OSX users that the path to use in this case is <code>/Library/Java/Home</code>. <strong>Caveat: </strong>We suspect that, as Apple releases new Java environments and as FOP upgrades the minimum Java requirements, the two will inevitably not match on some systems. Please see <jump href="http://developer.apple.com/java/faq">Java on Mac OSX FAQ</jump> for information as it becomes available.</p>
-    <p><code>fop [options] [-fo|-xml] infile [-xsl file] [-awt|-pdf|-mif|-pcl|-ps|-txt|-svg|-at|-print] &lt;outfile></code></p>
-     <p>[OPTIONS]</p>
-     <source>
-      -d          debug mode<br/>
-      -x          dump configuration settings<br/>
-      -q          quiet mode<br/>
-      -c cfg.xml  use additional configuration file cfg.xml<br/>
-      -l lang     the language to use for user information<br/></source>
-    <p>[INPUT]</p>
-    <source>
-      infile            xsl:fo input file (the same as the next)<br/>
-      -fo  infile       xsl:fo input file<br/>
-      -xml infile       xml input file, must be used together with -xsl<br/>
-      -xsl stylesheet   xslt stylesheet<br/></source>
+    <section id="standalone-start">
+      <title>Starting FOP as a Standalone Application</title>
+      <p>The usual and recommended practice for starting FOP from the command line is to run the batch file fop.bat (Windows) or the shell script fop.sh (Unix/Linux).
+If you write your own scripts, be sure to review these standard scripts to make sure that you get your environment properly configured.</p>
+      <p>The standard scripts for starting FOP require that the environment variable JAVA_HOME be set to a path pointing to the appropriate Java installation on your system. Macintosh OSX includes a Java environment as part of its distribution. We are told by Mac OSX users that the path to use in this case is <code>/Library/Java/Home</code>. <strong>Caveat: </strong>We suspect that, as Apple releases new Java environments and as FOP upgrades the minimum Java requirements, the two will inevitably not match on some systems. Please see <jump href="http://developer.apple.com/java/faq">Java on Mac OSX FAQ</jump> for information as it becomes available.</p>
+      <p><code>fop [options] [-fo|-xml] infile [-xsl file] [-awt|-pdf|-mif|-pcl|-ps|-txt|-svg|-at|-print] &lt;outfile></code></p>
+      <p>[OPTIONS]</p>
+      <source>
+      -d             debug mode
+      -x             dump configuration settings
+      -q             quiet mode
+      -c cfg.xml     use additional configuration file cfg.xml
+      -l lang        the language to use for user information
+      -s             (-at output) omit tree below block areas
+      -txt.encoding  (-txt output encoding use the encoding for the output file.
+                     The encoding must be a valid java encoding.
+      -o [password]  pdf file will be encrypted with option owner password
+      -u [password]  pdf file will be encrypted with option user password
+      -noprint       pdf file will be encrypted without printing permission
+      -nocopy        pdf file will be encrypted without copy content permission
+      -noedit        pdf file will be encrypted without edit content permission
+      -noannotations pdf file will be encrypted without edit annotation permission</source>
+      <p>[INPUT]</p>
+      <source>      infile            XSLFO input file (the same as the next)
+      -fo  infile       xsl:fo input file
+      -xml infile       xml input file, must be used together with -xsl
+      -xsl stylesheet   xslt stylesheet</source>
 
-    <p>[OUTPUT]</p>
-    <source>
-      outfile           input will be rendered as pdf file into outfile<br/>
-      -pdf outfile      input will be rendered as pdf file (outfile req'd)<br/>
-      -awt              input will be displayed on screen<br/>
-      -mif outfile      input will be rendered as mif file (outfile req'd)<br/>
-      -pcl outfile      input will be rendered as pcl file (outfile req'd)<br/>
-      -ps outfile       input will be rendered as PostScript file (outfile req'd)<br/>
-      -txt outfile      input will be rendered as text file (outfile req'd)<br/>
+      <p>[OUTPUT]</p>
+      <source>      outfile           input will be rendered as pdf file into outfile
+      -pdf outfile      input will be rendered as pdf file (outfile req'd)
+      -awt              input will be displayed on screen
+      -mif outfile      input will be rendered as mif file (outfile req'd)
+      -pcl outfile      input will be rendered as pcl file (outfile req'd)
+      -ps outfile       input will be rendered as PostScript file (outfile req'd)
+      -txt outfile      input will be rendered as text file (outfile req'd)
       -svg outfile      input will be rendered as an svg slides file (outfile req'd)
       -at outfile       representation of area tree as XML (outfile req'd)
-      -print            input file will be rendered and sent to the printer<br/>                        see options with "-print help"<br/></source>
-
-    <p>[Examples]</p>
-    <source>
-      fop foo.fo foo.pdf<br/>
-      fop -fo foo.fo -pdf foo.pdf (does the same as the previous line)<br/>
-      fop -xsl foo.xsl -xml foo.xml -pdf foo.pdf<br/>
-      fop foo.fo -mif foo.mif<br/>
-      fop foo.fo -print or Fop -print foo.fo<br/>
-      fop foo.fo -awt<br/></source>
-  </section>
-
-  <section>
-    <title>Problems</title>
-    <p>If you have problems running FOP, please have a look at the <jump href="gethelp.html">"How to get Help" page</jump>.</p>
-  </section>
-
-</body>
+      -print            input file will be rendered and sent to the printer
+                        see print specific options with "-print help"</source>
+      <p>[Examples]</p>
+      <source>      fop foo.fo foo.pdf
+      fop -fo foo.fo -pdf foo.pdf (does the same as the previous line)
+      fop -xsl foo.xsl -xml foo.xml -pdf foo.pdf
+      fop foo.fo -mif foo.mif
+      fop foo.fo -print or fop -print foo.fo
+      fop foo.fo -awt</source>
+      <p>PDF encryption is only available if FOP was compiled with encryption support <strong>and</strong> if compatible encryption support is availabe at run time. Currently, only the JCE is supported. Check the <link href="pdfencryption.html">Details</link>.</p>
+    </section>
+    <section id="check-input">
+      <title>Using Xalan to Check XSL-FO Input</title>
+      <p>FOP sessions that use -xml and -xsl input instead of -fo input are actually controlling two distinct conversions: Tranforming XML to XSL-FO, then formatting the XSL-FO to PDF (or another FOP output format).
+Although FOP controls both of these processes, the first is included merely as a convenience and for performance reasons.
+Only the second is part of FOP's core processing.
+If a user has a problem running FOP, it is important to determine which of these two processes is causing the problem.
+If the problem is in the first process, the user's stylesheet is likely the cause.
+The FOP development team does not have resources to help with stylesheet issues, although we have included links to some useful <link href="resources.html#specs">Specifications</link> and <link href="resources.html#articles">Books/Articles</link>.
+If the problem is in the second process, FOP may have a bug or an unimplemented feature that does require attention from the FOP development team.</p>
+      <note>The user is always responsible to provide correct XSL-FO code to FOP.</note>
+      <p>In the case of using -xml and -xsl input, although the user is responsible for the XSL-FO code that is FOP's input, it is not visible to the user. To make the intermediate FO file visible, the FOP distribution includes xalan.bat (Windows batch file) and xalan.sh (Unix/Linux script), which run only the first (transformation) step, and write the results to a file.</p>
+      <note>When asking for help on the FOP mailing lists, <em>never</em> attach XML and XSL to illustrate the issue. Always run the xalan script and send the resulting XSL-FO file instead. Of course, be sure that the XSL-FO file is correct before sending it.</note>
+      <p>
+        The scripts are invoked the same way that <link href="http://xml.apache.org/xalan-j/commandline.html">Xalan</link> is:
+      </p>
+      <p>
+        <code>xalan -in xmlfile -xsl file -out outfile</code>
+      </p>
+      <p>
+        Note that there are some subtle differences between the "fop" and "xalan" command lines.
+      </p>
+    </section>
+    <section id="memory">
+      <title>Memory Usage</title>
+      <p>
+FOP can consume quite a bit of memory, even though this has been continually improved.
+This is partly inherent to the formatting process and partly caused by implementation choices.
+All FO processors currently on the market have memory problems with certain layouts.
+      </p>
+      <p>
+If you are running out of memory when using FOP, here are some ideas that may help:
+      </p>
+      <ul>
+        <li>
+Increase memory available to the JVM. See <link href="http://java.sun.com/j2se/1.3/docs/tooldocs/solaris/java.html">the -Xmx option</link> for more information.
+          <!--<warning>-->
+(Warning: It is usually unwise to increase the memory allocated to the JVM beyond the amount of physical RAM, as this will generally cause significantly slower performance.)
+          <!--</warning>-->
+        </li>
+        <li>
+Avoid forward references.
+Forward references are references to some later part of a document.
+Examples include page number citations which refer to pages which follow the citation, tables of contents at the beginning of a document, and page numbering schemes that include the total number of pages in the document (<link href="faq.html#pagenum">"page N of TOTAL"</link>).
+Forward references cause all subsequent pages to be held in memory until the reference can be resolved, i.e. until the page with the referenced element is encountered.
+Forward references may be required by the task, but if you are getting a memory overflow, at least consider the possibility of eliminating them.
+A table of contents might be eliminated, relying on PDF bookmarks instead.
+Or it might be moved to the end of the document without dimishing its value very much.
+Or, in some circumstances, the paper could even be reshuffled after printing.
+        </li>
+        <li>
+Avoid large images, especially if they are scaled down.
+If they need to be scaled, scale them in another application upstream from FOP.
+For many image formats, memory consumption is driven mainly by the size of the image file itself, not its dimensions (width*height), so increasing the compression rate may help.
+        </li>
+        <li>
+Use multiple page sequences.
+FOP starts rendering after the end of a page sequence is encountered.
+While the actual rendering is done page-by-page, some additional memory allocated for other purposes could be freed after the page sequence has been rendered.
+        </li>
+        <li>
+Break down large tables.
+If you don't use table headers and footers, just start a new table every N rows.
+With headers and footers, consider integrating them as normal table rows, or, if they are used at page breaks, try to put the information into static content.
+You can then use markers to change them.
+        </li>
+      </ul>
+      <p>
+There are currently some bugs which cause FOP to go into a nonterminating loop, which will also often result in a memory overflow.
+A characteristic symptom is continuous <link href="faq.html#boxoverflow">box overflows</link> in the log.
+Most of these loops are triggered by elements that do not fit in the available space, such as big images or an improperly specified width in nested block elements.
+The only workaround is to locate such problems and correct them.
+      </p>
+      <p>
+One of FOP's stated design goals is to be able to process input of arbitrary size.
+Addressing this goal is one of the prime motivations behind the <link href="dev/index.html">FOP Redesign</link>.
+      </p>
+    </section>
+    <section id="problems">
+      <title>Problems</title>
+      <p>If you have problems running FOP, please see the <jump href="gethelp.html">"How to get Help" page</jump>.</p>
+    </section>
+  </body>
 </document>

src/documentation/content/xdocs/svg.xml

@@ -1,136 +0,0 @@
-<?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">
-
-<!-- SVG in FOP -->
-
-<document>
-    <header>
-        <title>SVG</title>
-        <subtitle>Embedding SVG in FOP</subtitle>
-    </header>
-
-    <body>
-
-<section>
-  <title>SVG in FOP</title>
-  <section>
-    <title>Introduction</title>
-    <p>
-FOP uses the SVG library from <link href="http://xml.apache.org/batik/">Batik</link> to handle SVG.
-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>. Either way the SVG document will be
-read in and converted into a DOM in Batik. This DOM will then be used by the renderer to
-create the graphical image.
-    </p>
-    <p>
-The AWT and Print renderers simply use batik to draw the SVG into a graphic.
-    </p>
-    <p>
-In the case of the PDF renderer there is a PDFGraphics2D class that Batik uses
-to render the image into. This class converts the drawing instructions into
-PDF markup which is placed into the current PDF document.
-    </p>
-  </section>
-
-  <section>
-    <title>Converting SVG to a PDF Document</title>
-    <p>
-It is possible to convert a standalone SVG document directly into a simple page PDF document.
-This is possible through the use of Batik's transcoder mechanism.<br/>
-<code>java org.apache.batik.apps.rasterizer.Main -m application/pdf document.svg</code>
-<br/>
-This will output the svg document as "document.pdf" containing a PDF rendering of
-the SVG file.
-    </p>
-    <p>
-It is also possible to specify the width and/or height of the PDF document on the command line with -w and -h or if you are using the transcoder api you can use the transcoding hints.
-    </p>
-    <p>
-Currently the SVG image is drawn at the SVG document size and simply scaled in PDF to the new size. So the result may not be the best possible. For example if you have any images or effects it will draw them at the original resolution of the svg document. When this is viewed in the pdf it will have an incorrect resolution for the size of the pdf.
-</p>
-    <p>
-The size of the pdf file will also remain the same regardless of what size the page is.
-    </p>
-    <p>
-For more information see <link href="http://xml.apache.org/batik/">Batik</link> for
-how transcoders work.
-    </p>
-  </section>
-
-  <section>
-    <title>Important Notes</title>
-    <p>
-The svg is inserted 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.
-This needs to be improved.
-    </p>
-    <p>
-Another important note is that text is converted and drawn as a
-set of shapes by batik. 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 by adding the following to the user config:
-    </p>
-<source><![CDATA[<entry>
-  <key>strokeSVGText</key>
-  <value>false</value>
-</entry>]]></source>
-    <p>
-The drawback from this is that all text 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>
-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>
-    <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>
-    </body>
-</document>
-

src/documentation/content/xdocs/tabs.xml

@@ -2,11 +2,14 @@
       <!DOCTYPE tabs PUBLIC "-//APACHE//DTD Cocoon Documentation Tab V1.0//EN"
     "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/schema/dtd/tab-cocoon-v10.dtd">
 
-      <tabs software="MyProj"
-        title="MyProj"
-        copyright="Foo"
-        xmlns:xlink="http://www.w3.org/1999/xlink">
-
-        <tab label="Home" dir=""/>
-
-    </tabs>
+<tabs software="FOP"
+      title="FOP"
+      copyright="@year@ The Apache Software Foundation"
+      xmlns:xlink="http://www.w3.org/1999/xlink">
+  
+  <tab label="Home" dir=""/>
+  <tab label="Development" dir="dev/"/>
+  <tab label="Design" dir="design/"/>
+  <tab label="Alt Design" dir="design/alt.design/"/>
+  
+</tabs>

src/documentation/content/xdocs/testing.xml

@@ -1,108 +0,0 @@
-<?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>
-    <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>
-</body>
-</document>
-

src/documentation/resources/schema/dtd/compliance-v10.dtd

@@ -1,8 +1,9 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!-- $Id$ -->
 <!ELEMENT compliance (head, body)>
-<!ELEMENT head (title)>
+<!ELEMENT head (title, subtitle?)>
 <!ELEMENT title (#PCDATA)>
+<!ELEMENT subtitle (#PCDATA)>
 <!ELEMENT body (standard)>
 <!ELEMENT standard (explanatory?, level-1+)>
 <!ATTLIST standard
@@ -12,6 +13,7 @@
   compliance-level-1-desc CDATA #REQUIRED
   compliance-level-2-desc CDATA #REQUIRED
   compliance-level-3-desc CDATA #REQUIRED
+  ref-name CDATA #IMPLIED
 >
 <!ELEMENT level-1 (explanatory?, level-2+)>
 <!ATTLIST level-1
@@ -19,6 +21,7 @@
   extURL CDATA #IMPLIED
   citation CDATA #IMPLIED
   compliance-item-desc CDATA #REQUIRED
+  ref-name CDATA #IMPLIED
 >
 <!ELEMENT explanatory (p*)>
 <!ELEMENT level-2 (level-3+)>
@@ -26,6 +29,7 @@
   name CDATA #REQUIRED
   extURL CDATA #IMPLIED
   citation CDATA #IMPLIED
+  ref-name CDATA #IMPLIED
 >
 <!ELEMENT level-3 (comment*)>
 <!ATTLIST level-3
@@ -34,6 +38,7 @@
   citation CDATA #IMPLIED
   compliance-level (1 | 2 | 3) #REQUIRED
   comply (yes | no | na | partial) #REQUIRED
+  ref-name CDATA #IMPLIED
 >
 <!ELEMENT comment (#PCDATA)>
 <!ELEMENT p (#PCDATA)>

src/documentation/skinconf.xml

@@ -11,9 +11,14 @@ jefft@apache.org
 
   <!ENTITY % links.att 'name CDATA #REQUIRED'>
   <!ENTITY % link.att 'name CDATA #REQUIRED href CDATA #REQUIRED'>
-  <!ELEMENT skinconfig (disable-search?, searchsite-domain?, searchsite-name?, project-name, project-url, project-logo, group-name?, group-url?, group-logo?, host-logo?, year?, vendor?, trail?, credits?)*>
+  <!ELEMENT skinconfig (disable-search?, searchsite-domain?, searchsite-name?,
+  project-name, project-url, project-logo, group-name?, group-url?, group-logo?,
+  host-url?, host-logo?, year?, vendor?, trail?, credits?)*>
   <!ELEMENT credits (credit*)>
-  <!ELEMENT credit (name, url, image, width?, height?)>
+  <!ELEMENT credit (name, url, image?, width?, height?)>
+  <!-- id uniquely identifies the tool, and role indicates its function -->
+  <!ATTLIST credit id   CDATA #IMPLIED
+                   role CDATA #IMPLIED>
   <!ELEMENT disable-search (#PCDATA)>
   <!ELEMENT searchsite-domain (#PCDATA)>
   <!ELEMENT searchsite-name (#PCDATA)>
@@ -23,6 +28,7 @@ jefft@apache.org
   <!ELEMENT group-name (#PCDATA)>
   <!ELEMENT group-url (#PCDATA)>
   <!ELEMENT group-logo (#PCDATA)>
+  <!ELEMENT host-url (#PCDATA)>
   <!ELEMENT host-logo (#PCDATA)>
   <!ELEMENT year (#PCDATA)>
   <!ELEMENT vendor (#PCDATA)>
@@ -60,7 +66,7 @@ jefft@apache.org
   <host-logo></host-logo>
 
   <!-- The following used to construct a copyright statement -->
-  <year>1999-2002</year>
+  <year>1999-2003</year>
   <vendor>The Apache Software Foundation.</vendor>
 
   <!-- Some skins use this to form a 'breadcrumb trail' of links. If you don't
@@ -75,7 +81,7 @@ jefft@apache.org
   <!-- Credits are typically rendered as a set of small clickable images in the
   page footer -->
   <credits>
-    <credit>
+    <!--<credit>
       <name>Built with Cocoon</name>
       <url>http://xml.apache.org/cocoon/</url>
       <image>skin/images/built-with-cocoon.gif</image>
@@ -88,6 +94,13 @@ jefft@apache.org
       <image>skin/images/centipede-logo-small.gif</image>
       <width>138</width>
       <height>31</height>
+    </credit>-->
+    <credit role="pdf">
+      <name>Created by: FOP 1.0dev</name>
+      <url>http://xml.apache.org/fop/dev</url>
+      <image>images/logo.jpg</image>
+      <width>138</width>
+      <height>31</height>
     </credit>
   </credits>
 </skinconfig>