Submitted by: Jeremias M�rki

Reviewed by:  Karen Lease
- Added a page "How to get Help".
- Added documentation for Michael's logging changes.
- Corrected some minor typos.
- Restructured the Resources page a bit.
- Added some more information on the PostScript Renderer.
- Added a comment on the FormattingResults class in "Embedding".
- Added a comment on CVS branches.
- A few other little additions.


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

9 files changed, 140 insertions, 81 deletions

diff --git a/docs/xml-docs/fop.xml b/docs/xml-docs/fop.xml
index ac3c17d11..eec25e93c 100644
--- a/docs/xml-docs/fop.xml
+++ b/docs/xml-docs/fop.xml
@@ -1,32 +1,32 @@
 <?xml version="1.0"?>
-
-<book title="FOP XSL-FO documentation" copyright="1999-2001 The Apache Software Foundation">
-  <external href="http://xml.apache.org/"  label="Home"/>
-  <separator/>
-  <page id="index"          label="About FOP"      source="fop/readme.xml"/>
-  <page id="download"       label="Download"    source="fop/download.xml"    />
-  <page id="running"        label="Running FOP"     source="fop/running.xml"    />
-  <page id="embedding"      label="Embedding" source="fop/embedding.xml"    />
-  <page id="output"      label="Ouput Formats" source="fop/output.xml"    />
-  <page id="implemented"    label="Features" source="fop/implemented.xml"    />
-  <page id="todo"           label="TODO"    source="fop/todo.xml"    />
-  <page id="limitations"    label="Limitations" source="fop/limitations.xml"    />
-  <page id="examples"       label="Examples" source="fop/examples.xml"    />
-  <separator/>
-  <page id="svg"            label="SVG" source="fop/svg.xml"    />
-  <page id="extensions"     label="Extensions" source="fop/extensions.xml"    />  <page id="fonts"          label="Fonts" source="fop/fonts.xml"    />
-  <page id="config"         label="Configuration" source="fop/configuration.xml"    />
-  <separator/>
-  <external href="design/index.html"      label="NEW DESIGN" />
-  <page id="involved"       label="Getting involved" source="fop/involved.xml"    />
-  <page id="compiling"      label="Compiling" source="fop/compiling.xml"    />
-  <page id="testing"        label="Testing" source="fop/testing.xml"    />
-  <separator/>
-  <page id="relnotes"       label="Release Notes" source="fop/relnotes.xml"    />
-  <separator/>
-  <faqs id="faq"            label="FAQ" source="fop/faq.xml"/>
-  <page id="bugs"           label="Bugs" source="fop/bugs.xml"    />
-  <page id="resources"      label="Resources" source="fop/resources.xml"    />
-  <page id="license"        label="License"     source="fop/license.xml"   />
-
+<book title="FOP XSL-FO documentation" copyright="1999-2002 The Apache Software Foundation">
+	<external href="http://xml.apache.org/" label="Home"/>
+	<separator/>
+	<page id="index" label="About FOP" source="fop/readme.xml"/>
+	<page id="download" label="Download" source="fop/download.xml"/>
+	<page id="relnotes" label="Release Notes" source="fop/relnotes.xml"/>
+	<page id="gethelp" label="How to get Help" source="fop/gethelp.xml"/>
+	<separator/>
+	<page id="running" label="Running FOP" source="fop/running.xml"/>
+	<page id="embedding" label="Embedding" source="fop/embedding.xml"/>
+	<page id="output" label="Ouput Formats" source="fop/output.xml"/>
+	<page id="implemented" label="Features" source="fop/implemented.xml"/>
+	<page id="todo" label="TODO" source="fop/todo.xml"/>
+	<page id="limitations" label="Limitations" source="fop/limitations.xml"/>
+	<page id="examples" label="Examples" source="fop/examples.xml"/>
+	<separator/>
+	<page id="svg" label="SVG" source="fop/svg.xml"/>
+	<page id="extensions" label="Extensions" source="fop/extensions.xml"/>
+	<page id="fonts" label="Fonts" source="fop/fonts.xml"/>
+	<page id="config" label="Configuration" source="fop/configuration.xml"/>
+	<separator/>
+	<external href="design/index.html" label="NEW DESIGN"/>
+	<page id="involved" label="Getting involved" source="fop/involved.xml"/>
+	<page id="compiling" label="Compiling" source="fop/compiling.xml"/>
+	<page id="testing" label="Testing" source="fop/testing.xml"/>
+	<separator/>
+	<faqs id="faq" label="FAQ" source="fop/faq.xml"/>
+	<page id="bugs" label="Bugs" source="fop/bugs.xml"/>
+	<page id="resources" label="Resources" source="fop/resources.xml"/>
+	<page id="license" label="License" source="fop/license.xml"/>
 </book>
diff --git a/docs/xml-docs/fop/download.xml b/docs/xml-docs/fop/download.xml
index 454c58532..8ef87431a 100644
--- a/docs/xml-docs/fop/download.xml
+++ b/docs/xml-docs/fop/download.xml
@@ -21,8 +21,12 @@
        a snapshot from the cvs files <jump href="http://xml.apache.org/from-cvs/xml-fop/">here</jump>. 
        In both cases you have to build Fop yourself - see <jump href="compiling.html">Compiling Fop</jump> for details. 
     </p>
-    <p>To run FOP from the command line, see <jump href="running.html">Running FOP</jump>. If you are 
-       interested in embedding FOP in a Java application of your own, see 
+    <note>
+      <p>Important: Currently, releases of FOP are coming out of the "fop-0_20_2-maintain" branch. The "MAIN" branch is
+      used for the redesign. See <jump href="design/index.html">NEW DESIGN</jump> for more information.</p>
+    </note>
+    <p>To run FOP from the command line, see <jump href="running.html">Running FOP</jump>.</p>
+    <p>If you are interested in embedding FOP in a Java application of your own, see
        <jump href="embedding.html">Embedding FOP</jump>.
     </p>
 </s1>
diff --git a/docs/xml-docs/fop/embedding.xml b/docs/xml-docs/fop/embedding.xml
index 5e3a41a78..919fa98e8 100644
--- a/docs/xml-docs/fop/embedding.xml
+++ b/docs/xml-docs/fop/embedding.xml
@@ -37,23 +37,6 @@
    driver.setRenderer(RENDER_PDF);
    driver.run();]]></source>
 
-  <p>You also need to set the Logger for logging messages, see
-     <jump href="http://jakarta.apache.org/avalon/logkit/index.html">Jakarta Logkit</jump>
-     for more information.
-  </p>
-    <source><![CDATA[
-    Hierarchy hierarchy = Hierarchy.getDefaultHierarchy();
-    PatternFormatter formatter = new PatternFormatter(
-       "[%{priority}]: %{message}\n%{throwable}" );
-
-    LogTarget target = null;
-    target = new StreamTarget(System.out, formatter);
-
-    hierarchy.setDefaultLogTarget(target);
-    log = hierarchy.getLoggerFor("fop");
-    log.setPriority(Priority.INFO);
-    driver.setLogger(log);]]></source>
-
   <p>To setup the user config file you can do the following
   </p>
     <source><![CDATA[
@@ -105,7 +88,37 @@ when finished, you will need to call <code>System.exit</code>. These
 issues should be fixed in the upcoming JDK1.4</note>
 </p>
   </s2>
+  <s2 title="Controlling logging">
+  	<p>FOP uses Jakarta Avalon's 
+  		<jump href="http://jakarta.apache.org/avalon/api/org/apache/avalon/framework/logger/Logger.html">Logger</jump>
+  		 interface to do logging. See the <jump href="http://jakarta.apache.org/avalon/">Jakarta Avalon project</jump> for more information.</p>
+  	<p>Per default FOP uses the ConsoleLogger which logs to System.out. If you want to do logging using a 
+  	logging framework (such as LogKit, Log4J or JDK 1.4 Logging) you can set a
+  	different Logger implementation on the Driver object. Here's an example how you would use LogKit:</p>
+    <source><![CDATA[
+    Hierarchy hierarchy = Hierarchy.getDefaultHierarchy();
+    PatternFormatter formatter = new PatternFormatter(
+       "[%{priority}]: %{message}\n%{throwable}" );
+
+    LogTarget target = null;
+    target = new StreamTarget(System.out, formatter);
+
+    hierarchy.setDefaultLogTarget(target);
+    log = hierarchy.getLoggerFor("fop");
+    log.setPriority(Priority.INFO);
+    
+    driver.setLogger(new org.apache.avalon.framework.logger.LogKitLogger(log));]]></source>
+  <p>The LogKitLogger class implements the Logger interface so all logging calls are being redirected to LogKit. 
+  More information on Jakarta LogKit can be found <jump href="http://jakarta.apache.org/avalon/logkit/index.html">here</jump>.</p>
+  <p>Similar implementations exist for Log4J (org.apache.avalon.framework.logger.Log4JLogger) and 
+  JDK 1.4 logging (org.apache.avalon.framework.logger.Jdk14Logger).</p>
+  <p>If you want FOP to be totally silent you can also set an org.apache.avalon.framework.logger.NullLogger instance.</p>
+  <p>If you want to use yet another logging facility you simply have to create a class that implements org.apache.avalon.framework.logging.Logger 
+  and set it on the Driver object. See the existing implementations in Avalon Framework for examples.</p>
+
+  </s2>
   <s2 title="Hints">
+  	<s3 title="Object reuse">
      <p>
 If FOP is going to be used multiple times within your application
 it may be useful to reuse certain objects to save time.
@@ -117,6 +130,14 @@ after the rendering is complete and the reset method is called.
 You will need to setup the driver again with a new OutputStream,
 IntputStream and renderer.
      </p>
+  	</s3>
+  	<s3 title="Getting information on the rendering process">
+  		To get the number of pages that were rendered by FOP you can call Driver.getResults(). This returns a 
+  		FormattingResults object where you can lookup the number of pages produced. It also gives you the
+  		page-sequences that were produced along with their id attribute and their number of pages. This is particularly useful if you
+  		render multiple documents (each enclosed by a page-sequence) and have to know the number of pages
+  		of each document.
+  	</s3>
   </s2>
   <s2 title="Using Fop in a servlet">  
      <p>
diff --git a/docs/xml-docs/fop/implemented.xml b/docs/xml-docs/fop/implemented.xml
index 65d2e616c..c5985fc1b 100644
--- a/docs/xml-docs/fop/implemented.xml
+++ b/docs/xml-docs/fop/implemented.xml
@@ -6,8 +6,8 @@
 <s1 title="Features">
   <s2 title="What's Implemented?">
       <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>
+         W3C Recommandation are implemented. Please have also a look at the 
+         section on <jump href="limitations.html">limitations</jump>.
       </p>
   </s2>
   <s2 title="1) Formatting Objects">
@@ -17,28 +17,28 @@
     <s3 title="B.1 Declaration and Pagination and Layout Formatting Objects">
       <ul>
         <li>root</li>
-        <li>page-sequence </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>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>
+        <li>static-content</li>
       </ul>
       <p>Not implemented: declarations, color-profile, title</p>
     </s3>
 
     <s3 title="B.2 Block Formatting Objects">
       <ul>
-        <li>block </li>
+        <li>block</li>
         <li>block-container (limited)</li>
       </ul>
     </s3>
@@ -58,7 +58,7 @@
 
     <s3 title="B.4 Table Formatting Objects">
       <ul>
-        <li>table </li>
+        <li>table</li>
         <li>table-body</li>
         <li>table-cell</li>
         <li>table-column</li>
diff --git a/docs/xml-docs/fop/output.xml b/docs/xml-docs/fop/output.xml
index 49aaa32f9..3b7a4c45c 100644
--- a/docs/xml-docs/fop/output.xml
+++ b/docs/xml-docs/fop/output.xml
@@ -115,13 +115,24 @@ print the output generated by the PCLRenderer.
       </dl>
     </s3>
 </s2>
-<s2 title="PS">
+<s2 title="PostScript">
     <p>
-The postscript format can be used to send to a printer or any other
-purpose you may have. It has good support for most text and
-layout. images and SVG are not fully supported due to some ps
-issues.
+The PostScript renderer is still in its early stages and therefore still
+missing some features. It provides good support for most text and layout. 
+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>
+    <s3 title="Limitations">
+      <ul>
+        <li>Images and SVG may not be display correctly. SVG support is far from being complete. No image transparency is available.</li>
+        <li>Character spacing may be wrong.</li>
+        <li>No font embedding is supported.</li>
+        <li>Multibyte characters are not supported.</li>
+        <li>PPD support is still missing.</li>
+        <li>The renderer is not yet configurable.</li>
+      </ul>
+    </s3>
 </s2>
 <s2 title="RTF">
     <p>
diff --git a/docs/xml-docs/fop/readme.xml b/docs/xml-docs/fop/readme.xml
index 2547f5bc6..2b44465e4 100644
--- a/docs/xml-docs/fop/readme.xml
+++ b/docs/xml-docs/fop/readme.xml
@@ -15,7 +15,7 @@
 <p>
         <figure width="300" height="100" src="title.jpg" alt="FOP Title" />
 </p>
-    <p>FOP is the world's first print formatter driven by XSL formatting
+    <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
        renders the resulting pages to a specified output. <jump href="output.html">Output formats</jump>
diff --git a/docs/xml-docs/fop/relnotes.xml b/docs/xml-docs/fop/relnotes.xml
index 589701226..6daf30b54 100644
--- a/docs/xml-docs/fop/relnotes.xml
+++ b/docs/xml-docs/fop/relnotes.xml
@@ -22,7 +22,7 @@
          on <code>fo:page-sequence</code>, <code>fo:single-page-master-reference</code>,
          <code>fo:repeatable-page-master-reference</code> and
          <code>fo:conditional-page-master-reference</code>.</p></li>
-       <li>JDK 1.2 (or better) is required</li>
+       <li>JDK 1.2 (or later) is required</li>
        <li>Jimi has been removed for licensing reasons
          <p>If you need PNG support you have to download 
            <jump href="http://java.sun.com/products/jimi/">Jimi</jump>,
@@ -33,6 +33,9 @@
          (search for jdk1.4 and remove the comments)
         </p> 
        </li>
+       <li>
+       	<p>For a more detailed list of changes, see the CHANGES file in the root of the FOP distribution.</p>
+       </li>
       </ul>
     </p>
  </s1>
diff --git a/docs/xml-docs/fop/resources.xml b/docs/xml-docs/fop/resources.xml
index a05f1f22a..2d3b93e21 100644
--- a/docs/xml-docs/fop/resources.xml
+++ b/docs/xml-docs/fop/resources.xml
@@ -13,6 +13,38 @@
     <body>
 
 <s1 title="FOP Relevant Specifications and Links">
+  <s2 title="Mailing Lists (and archives)">
+  	<s3 title="FOP User Mailing List">
+  		<ul>
+  			<li>Send a mail to <jump href="mailto:fop-user-subscribe@xml.apache.org">fop-user-subscribe@xml.apache.org</jump>
+  			 to subscribe. This is where user specific topics are discussed. For detailed instructions on the subscription, see 
+  			 <jump href="http://xml.apache.org/mail.html">Apache XML Mailing Lists</jump>.</li>
+  			 <li>The Mailing list ARChives (MARC) at the AIMS group: 
+		      		<jump href="http://marc.theaimsgroup.com/?l=fop-user&amp;r=1&amp;w=2">fop-user</jump>
+		      	</li>(searchable)
+		      	<li><jump href="http://xml.apache.org/mail/fop-user/">Apache archive of fop-user@apache.org</jump></li>
+  		</ul>
+  	</s3>
+  	<s3 title="FOP Developer Mailing List">
+  		<ul>
+  			<li>Send a mail to <jump href="mailto:fop-dev-subscribe@xml.apache.org">fop-dev-subscribe@xml.apache.org</jump>
+  			 to subscribe. For detailed instructions on the subscription, see 
+  			 <jump href="http://xml.apache.org/mail.html">Apache XML Mailing Lists</jump>.</li>
+  			 <li>The Mailing list ARChives (MARC) at the AIMS group: 
+		      		<jump href="http://marc.theaimsgroup.com/?l=fop-dev&amp;r=1&amp;w=2">fop-dev</jump>
+		      	</li>(searchable)
+		      	<li><jump href="http://xml.apache.org/mail/fop-dev/">Apache archive of fop-dev@apache.org</jump></li>
+  		</ul>
+  	</s3>
+  	<s3 title="XSL:FO Mailing List (at W3C)">
+  		<ul>
+		      <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>.</li>
+		          <li>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>
+  	</s3>
+  </s2>
   <s2 title="Specifications">
   <ul>
     <li><jump href="http://www.w3.org/TR/2001/REC-xsl-20011015/">XSL-FO Recommendation (15 October 2001)</jump></li>
@@ -36,14 +68,8 @@
       <li><jump href="http://www.dpawson.co.uk/xsl/sect3/bk/index.html">Dave Pawson: An introduction to XSL Formatting Objects</jump></li>
     </ul>
   </s2>
-  <s2 title="Other resources">
+  <s2 title="Related/Useful Products">
     <ul>
-      <li><jump href="http://xml.apache.org/mail/fop-dev/">Apache archive of fop-dev@apache.org</jump></li>
-      <li>The Mailing list ARChives (MARC) at the AIMS group: <jump href="http://marc.theaimsgroup.com/?l=fop-dev&amp;r=1&amp;w=2">fop-dev</jump>,
-      <jump href="http://marc.theaimsgroup.com/?l=fop-user&amp;r=1&amp;w=2">fop-user</jump></li>(searchable)
-      <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>
       <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>
diff --git a/docs/xml-docs/fop/running.xml b/docs/xml-docs/fop/running.xml
index 56bb026b1..7931377d4 100644
--- a/docs/xml-docs/fop/running.xml
+++ b/docs/xml-docs/fop/running.xml
@@ -67,13 +67,7 @@
   </s2>
 
   <s2 title="Problems">
-    <p>If you have problems running FOP, please have a look at the 
-       <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 
-       <jump href="http://marc.theaimsgroup.com/?l=fop-user&amp;r=1&amp;w=2">fop-user@xml.apache.org</jump>
-      (see  <jump href="http://xml.apache.org/mail.html">here</jump> for
-       howto subscribe). Maybe it is a bug and maybe somebody is already working on it. 
-    </p>
+    <p>If you have problems running FOP, please have a look at the <jump href="gethelp.html">"How to get Help" page</jump>.</p>
   </s2>
 </s1>