updating docs for 0.17 release

git-svn-id: https://svn.apache.org/repos/asf/xmlgraphics/fop/trunk@194024 13f79535-47bb-0310-9956-ffa450edef68

12 files changed, 117 insertions, 111 deletions

diff --git a/docs/xml-docs/fop/architecture.xml b/docs/xml-docs/fop/architecture.xml
index 0ac6ada55..5d385281b 100644
--- a/docs/xml-docs/fop/architecture.xml
+++ b/docs/xml-docs/fop/architecture.xml
@@ -16,7 +16,7 @@ this class, a typical sequence is:</p>
 <p><code>driver.addElementMapping("org.apache.fop.svg.SVGElementMapping");</code></p>
 <p><code>driver.addPropertyList("org.apache.fop.fo.StandardPropertyListMapping");</code></p>
 <p><code>driver.addPropertyList("org.apache.fop.svg.SVGPropertyListMapping");</code></p>
-<p><code>driver.setWriter(new PrintWriter(new FileWriter(args[1])));</code></p>
+  <p><code>driver.setOutputStream(new FileOutputStream(args[1]));</code></p>
 <p></p>
 <p><code>driver.buildFOTree(parser, fileInputSource(args[0]));</code></p>
 <p></p>
@@ -262,6 +262,11 @@ Rendering will not be discussed further in this document, as most of our
 current effort must concentrate on layout. Section 4.12 in the XSL WD
 discusses some issues applicable to rendering.
 </p>
+
+<p>
+You can find UML diagramms for all Fop packages (latest release version) 
+<jump href="http://xml.apache.org/dist/fop-uml.zip">here</jump>.</p>
+
 </s2>
 
 <s2 title="SVG">
diff --git a/docs/xml-docs/fop/bugs.xml b/docs/xml-docs/fop/bugs.xml
index 01de7ffa4..1e8e69336 100644
--- a/docs/xml-docs/fop/bugs.xml
+++ b/docs/xml-docs/fop/bugs.xml
@@ -1,23 +1,18 @@
 <?xml version="1.0" standalone="no"?>
 
-
-
 <!-- Bugs -->
 
 <s1 title="Bugs">
   <s2 title="How to report bugs">
-    <p>Please report bugs to the discussion list fop-dev@xml.apache.org and put 
-       the word [BUG] in the subject line. </p>
+    <p>Please report bugs to <jump href="http://nagoya.apache.org/bugzilla/">bugzilla</jump>, the Apache bug
+       database. A copy of your bug report is sent automatically to the discussion list fop-dev@xml.apache.org. </p>
     <p>Please make sure, before you report a bug, that it is not mentioned in the FAQ or 
-       in the list of open bugs in the file STATUS in the start directory of the Fop
-       distribution. </p>
-    <p>Please make your description as concise as possible and send an example fo 
+       in the list of open bugs at bugzilla.</p>
+    <p>Please make your description as concise as possible and add an example fo 
        file with your report, which just demonstrates the problem. Thanks for your help!</p>
   </s2>
   <s2 title="Known bugs">
-    <p>A list of known bugs can be found at the end of the file 
-       <jump href="http://xml.apache.org/websrc/cvsweb.cgi/xml-fop/">Status</jump> in the root 
-       of the Fop distribution.</p>
+    <p>A list of known bugs can be found at <jump href="http://nagoya.apache.org/bugzilla/">bugzilla</jump>.</p>
   </s2>
 </s1>
 
diff --git a/docs/xml-docs/fop/compiling.xml b/docs/xml-docs/fop/compiling.xml
index 0c7209f86..f0d0339fb 100644
--- a/docs/xml-docs/fop/compiling.xml
+++ b/docs/xml-docs/fop/compiling.xml
@@ -16,8 +16,8 @@
    <s2 title="Setting up your classpath">
      <p>The build process relies on finding following libraries in your classpath (the version numbers indicate that building with them has been successfully tested, other, later versions may work too:</p>
      <ul>
-        <li><jump href="http://xml.apache.org/xerces-j/index.html">Xerces-J</jump> version 1.2.1 (xml parser)</li>
-        <li><jump href="http://xml.apache.org/xalan/index.html">Xalan</jump> version 1.2 (xslt processor)</li>
+        <li><jump href="http://xml.apache.org/xerces-j/index.html">Xerces-J</jump> version 1.2.1 (xml parser). Xerces-J version 1.3.0 does not work, because of a bug in Xerces!</li>
+        <li><jump href="http://xml.apache.org/xalan/index.html">Xalan</jump> version 1.2 (xslt processor). Xalan 2.0 is also supported.</li>
         <li>bsf.jar (comes with Xalan)</li>
         <li>jimi.jar (image processing library) this file is optional </li>
      </ul>
diff --git a/docs/xml-docs/fop/embedding.xml b/docs/xml-docs/fop/embedding.xml
index 90c319f49..ee70f75c7 100644
--- a/docs/xml-docs/fop/embedding.xml
+++ b/docs/xml-docs/fop/embedding.xml
@@ -5,11 +5,11 @@
 <!-- Embedding FOP -->
 
 <s1 title="Embedding FOP ">
-  <s2 title="">
+  <s2 title="Overview">
   <p>Instantiate org.apache.fop.apps.Driver. Once this class is 
      instantiated, methods are called to set the
      Renderer to use, the (possibly multiple) ElementMapping(s) to
-     use and the PrintWriter to use to output the results of the
+     use and the OutputStream to use to output the results of the
      rendering (where applicable). In the case of the Renderer and
      ElementMapping(s), the Driver may be supplied either with the
      object itself, or the name of the class, in which case Driver will
@@ -27,17 +27,26 @@
   <p>Once the FO Tree is built, the format() and render() methods may be
      called in that order.
   </p>
-  <p>Here is an example use of Driver from CommandLine.java:</p>
+  <p>Here is an example use of Driver:</p>
   <p><code>Driver driver = new Driver();</code></p>
   <p><code>driver.setRenderer("org.apache.fop.render.pdf.PDFRenderer", version);</code></p>
   <p><code>driver.addElementMapping("org.apache.fop.fo.StandardElementMapping");</code></p>
   <p><code>driver.addElementMapping("org.apache.fop.svg.SVGElementMapping");</code></p>
   <p><code>driver.addPropertyList("org.apache.fop.fo.StandardPropertyListMapping");</code></p>
   <p><code>driver.addPropertyList("org.apache.fop.svg.SVGPropertyListMapping");</code></p>
-  <p><code>driver.setWriter(new PrintWriter(new FileWriter(args[1])));</code></p>
+  <p><code>driver.setOutputStream(new FileOutputStream(args[1]));</code></p>
   <p><code>driver.buildFOTree(parser, fileInputSource(args[0]));</code></p>
   <p><code>driver.format();</code></p>
   <p><code>driver.render();</code></p>
+  <p>Have a look at the classes CommandLine or XalanCommandLine for complete examples.</p>
+  </s2>
+  <s2 title="Using Fop in a servlet">  
+     <p>In the directory xml-fop/docs/examples/embedding you can find a working example how to use
+        Fop in a servlet. You can drop the fop.war into the webapps directory of Tomcat, then 
+        go to a URL like this:
+     </p>
+     <p>http://localhost:8080/fop/fop?fo=/home/path/to/fofile.fo</p>
+     <p>You can also find the source code there in the file FopServlet.java</p>
   </s2>
 </s1>
 
diff --git a/docs/xml-docs/fop/faq.xml b/docs/xml-docs/fop/faq.xml
index 5449035a4..f0dfba96e 100644
--- a/docs/xml-docs/fop/faq.xml
+++ b/docs/xml-docs/fop/faq.xml
@@ -1,77 +1,9 @@
 <?xml version="1.0"?>
 
 
-<faqs title="FAQ Running FOP">
-
-  <faq title="Source files for the formatting properties are missing">
-    <q>Q: I can't find the source files for the formatting properties. The directories 
-       where they should be are empty. Where can I find them?</q>
-    <a><p>A: They are generated during the build process. So you should use the build script coming 
-          with Fop at least once to generate these files.
-       </p>
-    </a>
-  </faq>
-
-
-  <faq title="Formatting object xxx doesn't work as expected">
-    <q>Q: Feature xxx of the XSL Working Draft 27 March 2000 does not work as it should. Why?</q>
-    <a><p>A: First: Only a small subset of formatting objects and properties is 
-          implemented at the moment. Please have a look at the section "Features", 
-          which lists the supported fo and properties. Second: At the moment only 
-          Working Draft 21 Apr 1999 is supported. 
-       </p>
-    </a>
-  </faq>
-
-  <faq title="Supporting the latest XSL working draft">
-    <q>Q: When will the latest version of the XSL working draft be supported?</q>
-    <a><p>Basic conformance to the latest XSL working draft is scheduled for fall 2000. 
-       </p>
-    </a>
-  </faq>
-
-  <faq title="Fatal error: Root element must be root">
-     <q>Q: Running FOP I get the following messages or something similar: 
-        "WARNING: Unknown formatting object http://www.w3.org/XSL/Format/1.0^root"
-        and then a FATAL Error "Root element must be root, not default FO".</q>
-     <a>
-        <p>A: Make sure that you have specified as the namespace for fo the
-           following string: "http://www.w3.org/1999/XSL/Format". It is analogous 
-           to the xslt namespace "http://www.w3.org/1999/XSL/Transform"
-        </p>
-     </a>
-  </faq>
-
-  <faq title="Char '>' inserted into page number">
-     <q>Q: The char ">" is inserted into the page number display like this 
-        "formatting FOs into areas [1] [2] [3>>>>]". Is this a bug?</q>
-     <a><p>A: No, a feature. It simply means that on that page an area 
-           overflowed (ie there was not enough room to fit the text in).</p></a>
-  </faq>
-
-  <faq title="Are font properties allowed here">
-     <q>Q: It looks like FOP must be honoring font properties when it shouldn't be? 
-        Example: According to the dtd coming with the xsl-fo spec inline-sequence 
-        shouldn't have any attributes, but FOP doesn't reject them.
-     </q>
-     <a>
-      <p>A: Font properties are inherited down to individual characters. You can
-         specify font properties on any formatting object you like and any textual content
-         will inherit those properties (unless overriden by a closer ancestor).
+<s1 title="Frequently Asked Questions">
+      <p>The Fop faq has an own site. Please look here: 
+         <jump href="http://www.owal.co.uk:8090/asf/servlet/asf/screen/DisplayTopics/action/SetAll/project_id/18/faq_id/276">http://www.OWAL.co.uk:8090/</jump>
       </p>
-      <p>The dtd coming with the xsl-fo spec isn't correct in this respect.
-      </p>
-     </a>
-  </faq>
-
-  <faq title="Supported fonts">
-     <q>Q: I need some additional fonts in FOP. How I can set embedding fonts?
-     </q>
-     <a>
-      <p>A: At present, FOP does not support any fonts other than the built-in fonts
-        Times, Helvetica, Courier, Symbol and ZapfDingbats. 
-       </p>
-     </a>
-  </faq>
+</s1>
 
-</faqs>
diff --git a/docs/xml-docs/fop/fonts.xml b/docs/xml-docs/fop/fonts.xml
index 81a94aec5..01869e8e1 100644
--- a/docs/xml-docs/fop/fonts.xml
+++ b/docs/xml-docs/fop/fonts.xml
@@ -1,19 +1,19 @@
 <?xml version="1.0" standalone="no"?>
 <!-- Font Support -->
-<!-- Author: jeremias.maerki@outline.ch -->
+<!-- Authors: Jeremias Maerki, Tore Engvig-->
 <s1 title="Font Support ">
 	<s2 title="Status">
 		<p>FOP (building PDF files) normally supports only the base 14 font package defined in the Adobe PDF specification.
 		That includes the following fonts: Helvetica, Times, Courier, Symbol and ZapfDingbats.
 		</p>
 		<p>Font support in FOP can be extended by the addition of font metric files (written in XML) created from Adobe
-		Type 1 fonts. No other font types (TrueType, Type 0, Type 3, etc.) are supported at this time. The current method
-		of adding fonts to FOP requires the package to be recompiled.
+		Type 1 fonts and Truetype fonts. No other font types (Type 0, Type 3, etc.) are supported at this time. The current method
+		of adding fonts to FOP requires the package to be recompiled. You can also embed fonts into pdf files; see below.
 		</p>
 	</s2>
 	<s2 title="Adding additional Type 1 fonts">
 		<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.
+		contains a tool that can generate such a font metrics file from a PFM file, which normally comes with the font file. 
 		</p>
 		<s3 title="Generating a font metrics file">
 			<p>	Run the class org.apache.fop.fonts.apps.PFMReader to generate the XML file. Important: The tool does two
@@ -91,4 +91,59 @@
 			</p>
 		</s3>
 	</s2>
+	<s2 title="Adding additional TrueType">
+        <p>Adding Truetype fonts is almost identical to the process of adding type 1 fonts. The main difference is in the first step.</p>
+		<s3 title="Generating a font metrics file">
+            <p>As mentioned above you need an XML file containing font metrics to be able to use an additional font. FOP
+               contains a tool that can generate such a font metrics file from your truetype font file
+            </p>
+            <p>Create metrics for the fontfile (we assume the file has the name cmr10.ttf und to be in c:\myfonts\):            </p>
+            <p><code>java org.apache.fop.fonts.apps.TTFReader -fn TCM -cn TCM -ef C:\myfonts\cmr10.ttf C:\myfonts\cmr10.ttf ttfcm.xml</code></p>
+            <p>the -fn option sets the font name (in the example to TCM )</p>
+            <p>the -cn option set the classname (in the example to CM)</p>
+            <p>the -ef option will try to embed to font at the given path when fop is running (you can 
+               change that in the generated xml file). </p>
+		</s3>
+		<s3 title="Register the fonts within FOP">
+			<p>Open the class org.apache.fop.render.pdf.FontSetup and add entries to the ones present according to
+			the following example:
+			</p>
+			<p>
+				<code>fontInfo.addMetrics("F14", new ZapfDingbats());</code>
+			</p>
+			<p>
+				<code>fontInfo.addMetrics("F19", new TCM()); //This is the new entry.</code>
+			</p>
+			<p>
+				<code>...</code>
+			</p>
+			<p>
+				<code>fontInfo.addFontProperties("F14", "ZapfDingbats", "normal", "normal");</code>
+			</p>
+			<p>
+				<code>fontInfo.addFontProperties("F19", "TCM", "normal", "normal"); //This is the new entry.</code>
+			</p>
+			<p>Note: The class name to use is visible in the &lt;class-name&gt; element of the font metrics file.
+			</p>
+		</s3>
+		<s3 title="Adjusting build.xml">
+			<p>In the src/codegen directory you find the font metrics files for the base 14 fonts. The are being transformed
+			during build into Java classes and then compiled. The newly generated font metrics file must be included in this 
+			process. To do that open build.xml and add entries according to the following example:
+			</p>
+			<p>Look for the section "Initialization target" and add the following line at the end of it</p>
+    		<p><code>&lt;property name="tcm.xml" value="${build.codegen}/tcm.xml"&gt;</code></p>
+            <p>then search for the section "Generate the source code". At the end of this section you can find 
+               templates for type 1 and truetype fonts. use them with your font name:</p>
+    		<p><code>&lt;xslt infile="${tcm.xml}" xsltfile="${ttffontfile.xsl}" 
+                    outfile="${build.src}/${replacestring}/render/pdf/fonts/TCM.java" smart="yes"/&gt;</code></p>
+        </s3>
+        <s3 title="embedding fonts">
+            <p>edit conf\userconfig.xml and add TCM to the list of embedded fonts</p>
+            <p>Don't forget: If you have embedded fonts, you must run Fop with the flag -cuserconfig.xml,  
+               otherwise the settings in userconfig.xml will not be read.</p>
+        </s3>
+        <p>Rebuild FOP!</p>
+
+	</s2>
 </s1>
diff --git a/docs/xml-docs/fop/implemented.xml b/docs/xml-docs/fop/implemented.xml
index 86b0dd8aa..c4393d155 100644
--- a/docs/xml-docs/fop/implemented.xml
+++ b/docs/xml-docs/fop/implemented.xml
@@ -85,11 +85,18 @@
     </s3>
 
     <s3 title="B.7 Out-of-line Formatting Objects">
-      <p>Not implemented: float, footnote, footnote-body</p>
+      <ul>
+        <li>footnote</li>
+        <li>footnote-body</li>
+      </ul>
+      <p>Not implemented: float</p>
     </s3>
 
     <s3 title="B.8 Other Formatting Objects">
-      <p>Not implemented: wrapper, marker, retrieve-marker</p>
+      <ul>
+        <li>wrapper</li>
+      </ul>
+      <p>Not implemented: marker, retrieve-marker</p>
     </s3>
   </s2>
 
@@ -200,7 +207,7 @@
       <li>table-omit-header-at-break</li> 
       <li>text-align </li>
       <li>text-align-last </li>
-      <li>textdecoration (only value "underline")</li>
+      <li>text-decoration</li>
       <li>text-indent </li>
       <li>top</li>
       <li>white-space-collapse</li>
diff --git a/docs/xml-docs/fop/involved.xml b/docs/xml-docs/fop/involved.xml
index 68742cce9..8ce3d70c9 100644
--- a/docs/xml-docs/fop/involved.xml
+++ b/docs/xml-docs/fop/involved.xml
@@ -41,7 +41,7 @@
      Management Committee' (An explanation of these roles can be found <jump href="http://xml.apache.org/roles.html">here</jump>).</p>
   </s2>
   <s2 title="Get familiar with the Fop related standards">
-  <p>At the moment Fop is mainly a tools to render XSL:FO files to pdf. Therefore if you want to contribute to Fop you should become
+  <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 their internet addresses on our <jump href="specs.html">website</jump>.</p>
   </s2>
   <s2 title="Fop's architecture">
diff --git a/docs/xml-docs/fop/limitations.xml b/docs/xml-docs/fop/limitations.xml
index e56c1a5e4..33fcbc4cc 100644
--- a/docs/xml-docs/fop/limitations.xml
+++ b/docs/xml-docs/fop/limitations.xml
@@ -10,10 +10,7 @@
   </p>
 
   <s2 title="fo:leader">
-    <p>Only the property leader-length.optimum is used, so for all purposes you can use 
-       "leader-length" instead. leader-length.minimum/maximum should be honored 
-       for line-justification, but this does not happen.
-    </p>
+    <p>leader-length.minimum is not used at all</p>
   </s2>
 
   <s2 title="page-number-citation">
@@ -79,9 +76,5 @@
     <p><code>&lt;/fo:table></code></p>
   </s2>
 
-  
-  <!--<s2 title="display-graphic">
-    <p>Which formats are supported? Compression etc. </p>  
-  </s2>-->
 
 </s1>
diff --git a/docs/xml-docs/fop/readme.xml b/docs/xml-docs/fop/readme.xml
index c95748d0b..91cec49ea 100644
--- a/docs/xml-docs/fop/readme.xml
+++ b/docs/xml-docs/fop/readme.xml
@@ -20,7 +20,7 @@
        like XT or Xalan) or can be passed in memory as a DOM Document or (in
        the case of XT) SAX events.
     </p>
-    <p>The latest version of Fop is 0.16 and it supports the xsl:fo candidate release.
+    <p>The latest version of Fop is 0.17 and it supports the xsl:fo candidate release.
        You can <jump href="download.html">download</jump> 
        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
diff --git a/docs/xml-docs/fop/specs.xml b/docs/xml-docs/fop/resources.xml
index 708e6935b..3906739ac 100644
--- a/docs/xml-docs/fop/specs.xml
+++ b/docs/xml-docs/fop/resources.xml
@@ -8,8 +8,7 @@
   <ul>
     <li><jump href="http://www.w3.org/TR/2000/CR-xsl-20001121/">XSL-FO Candidate Recommendation (21 November 2000)</jump></li>
     <li><jump href="http://www.renderx.com/Tests/validator/fo2000.dtd.html">A dtd for the XSL-FO WD from October provided by N. Grigoriev from RenderX</jump></li>
-    <li><jump href="http://www.w3.org/TR/SVG">Latest SVG Working draft</jump></li>
-    <li><jump href="http://www.w3.org/TR/2000/CR-SVG-20000802/index.html">Supported SVG Candidate Recommendation</jump></li>
+    <li><jump href="http://www.w3.org/TR/2000/CR-SVG-20001102/">Supported SVG Candidate Recommendation (02 November 2000)</jump></li>
     <li><jump href="http://www.w3.org/TR/REC-xml">XML Recommendation</jump></li>
     <li><jump href="http://www.w3.org/TR/xslt">XSLT Recommendation</jump></li>
     <li><jump href="http://partners.adobe.com/asn/developer/acrosdk/DOCS/pdfspec.pdf">Portable Document Format (PDF) 1.3 Reference Manual </jump></li>
@@ -23,6 +22,16 @@
     <ul>
       <li><jump href="http://www.ibiblio.org/xml/books/bible/updates/15.html">Elliotte Rusty Harold: Chapter 15 on xsl:fo from his excellent xml book</jump></li>
       <li><jump href="http://www.sun.com/software/xml/developers/slides-dtd/">Paul Sandoz: Using formatting objects with the slides dtd</jump></li>
+      <li><jump href="http://www.xml.com/pub/a/2001/01/17/xsl-fo/index.html">J. David Eisenberg: Using XSL Formatting Objects</jump></li>
+    </ul>
+  </s2>
+  <s2 title="Other resources">
+    <ul>
+      <li><jump href="http://xml.apache.org/mail/fop-dev/">Apache archive of fop-dev@apache.org</jump></li>
+      <li><jump href="http://marc.theaimsgroup.com/">External, but easier to browse archive fop-dev@apache.org</jump></li>
+      <li>There is an xsl:fo mailing list: www-xsl-fo@w3.org. Subscription info can be found here: <jump href="http://www.w3.org/Mail/Request">
+          http://www.w3.org/Mail/Request</jump>. And the archive can be found here: 
+          <jump href="http://lists.w3.org/Archives/Public/www-xsl-fo/">http://lists.w3.org/Archives/Public/www-xsl-fo/</jump></li>
     </ul>
   </s2>
 </s1>
diff --git a/docs/xml-docs/fop/running.xml b/docs/xml-docs/fop/running.xml
index b78212e6d..d796fc6e7 100644
--- a/docs/xml-docs/fop/running.xml
+++ b/docs/xml-docs/fop/running.xml
@@ -16,11 +16,12 @@
           be included in your classpath. The jar file w3c.jar contains the compiled classes for the
           java svg bindings with some other DOM classes that are used by the SVG DOM bindings.
           The source for the svg java binding classes can be found at - <jump href="http://www.w3.org/TR/2000/CR-SVG-20000802/java.html">
-          SVG Java bindings</jump>, currently they correspond to the CR-SVG-20000802 specification document.
+          SVG Java bindings</jump>, currently they correspond to the SVG Candidate Recommendation (02 November 2000).
           The other required files can be found at <jump href="http://www.w3.org/TR/2000/CR-DOM-Level-2-20000510/java-binding.html">W3C DOM Java binding</jump>.
     </p>
     <p>d) Optional: Fop supports the jimi library for image processing, if it is in your classpath
-          when you build Fop. You can find it at <jump href="http://java.sun.com/products/jimi/">java.sun.com</jump>
+          when you build Fop (the precompiled version supports jimi). You can find it at 
+          <jump href="http://java.sun.com/products/jimi/">java.sun.com</jump>
     </p>
   </s2>
   <s2 title="Starting FOP as an standalone application">
@@ -108,7 +109,7 @@
   </s2>
   <s2 title="Problems">
     <p>If you have problems running FOP, please have a look at the 
-       <jump href="faq-running.html">FOP FAQ</jump>. If you don't find a solution there,
+       <jump href="http://www.owal.co.uk:8090/asf/servlet/asf/screen/DisplayTopics/action/SetAll/project_id/18/faq_id/276">FOP FAQ</jump>. If you don't find a solution there,
        you can ask for help on the list fop-dev@xml.apache.org. Maybe it is a bug and 
        maybe somebody is already working on it. 
     </p>