some small improvements to website docs

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

7 files changed, 95 insertions, 63 deletions

diff --git a/docs/xml-docs/fop/embedding.xml b/docs/xml-docs/fop/embedding.xml
index 6a7884b70..d7f5aa58b 100644
--- a/docs/xml-docs/fop/embedding.xml
+++ b/docs/xml-docs/fop/embedding.xml
@@ -15,6 +15,8 @@
      instantiate the class itself. The advantage of the latter is it
      enables runtime determination of Renderer and ElementMapping(s).
   </p>
+  </s2>
+  <s2 title="Examples">
   <p>The simplest way to use Driver is to instantiate it with the 
      InputSource and OutputStream, then set the renderer desired and 
      call the run method.
@@ -25,15 +27,30 @@
    Driver driver = new Driver(new InputSource (args[0]), 
                               new FileOutputStream(args[1]));
    driver.setRenderer(RENDER_PDF);
-   driver.run();
-]]></source>
+   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[
    userConfigFile = new File(userConfig);
-   options = new Options(userConfigFile);
-]]></source>
+   options = new Options(userConfigFile);]]></source>
 
   <p>Once the Driver is set up, the render method
      is called. Depending on whether DOM or SAX is being used, the
@@ -52,8 +69,7 @@
   driver.setRenderer(Driver.RENDER_PDF);
   driver.setInputSource(new FileInputSource(args[0]));
   driver.setOutputStream(new FileOutputStream(args[1]));
-  driver.run();
-]]></source>
+  driver.run();]]></source>
   <p>You can also specify an xml and xsl file for the input.
   </p>
   <p>Here is an example use of Driver with the XSLTInputHandler:</p>
@@ -63,10 +79,22 @@
   InputHandler inputHandler = new XSLTInputHandler(xmlFile, xslFile);
   XMLReader parser = inputHandler.getParser();
   driver.setOutputStream(new FileOutputStream(outFile));
-  driver.render(parser, inputHandler.getInputSource());
-]]></source>
+  driver.render(parser, inputHandler.getInputSource());]]></source>
   <p>Have a look at the classes CommandLineStarter or FopServlet for complete examples.</p>
   </s2>
+  <s2 title="Hints">
+     <p>
+If FOP is going to be used multiple times within your application
+it may be useful to reuse certain objects to save time.
+     </p>
+     <p>
+The renderers and the driver can both be reused. A renderer is reusable
+once the previous render has been completed. The driver is reuseable
+after the rendering is complete and the reset method is called.
+You will need to setup the driver again with a new OutputStream,
+IntputStream and renderer.
+     </p>
+  </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 
diff --git a/docs/xml-docs/fop/extensions.xml b/docs/xml-docs/fop/extensions.xml
index f77f75f87..90b6d5e8f 100644
--- a/docs/xml-docs/fop/extensions.xml
+++ b/docs/xml-docs/fop/extensions.xml
@@ -33,8 +33,7 @@ Please see the <jump href="svg.html">SVG page</jump> for more details.
       <fox:label>Prerequisites</fox:label>
     </fox:outline>
   <fox:outline>
-</fo:root>
-]]></source>
+</fo:root>]]></source>
     <p>It works similarly to a basic-link. There is also an external-destination 
        property, but it isn't supported currently. See the pdfoutline.fo file in 
       docs/examples/fo for a more complete example.</p>
diff --git a/docs/xml-docs/fop/license.xml b/docs/xml-docs/fop/license.xml
index 2bb39174f..7d184fdef 100644
--- a/docs/xml-docs/fop/license.xml
+++ b/docs/xml-docs/fop/license.xml
@@ -5,7 +5,7 @@
 
 <s1 title="License">
   <s2 title="The Apache Software License, Version 1.1">
-    <p> Copyright (C) 1999 The Apache Software Foundation. All rights reserved.</p>
+    <p> Copyright (C) 1999-2001 The Apache Software Foundation. All rights reserved.</p>
     <p> Redistribution and use in source and binary forms, with or without modification, 
         are permitted provided that the following conditions are met:</p>
     <p>1. Redistributions of  source code must  retain the above copyright  notice,
diff --git a/docs/xml-docs/fop/limitations.xml b/docs/xml-docs/fop/limitations.xml
index fd3b1288f..c2220c3be 100644
--- a/docs/xml-docs/fop/limitations.xml
+++ b/docs/xml-docs/fop/limitations.xml
@@ -32,36 +32,39 @@
        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>  
-    <p><code>&lt;fo:table></code></p>
-    <p><code>&#160;&lt;fo:table-column column-width="150pt"/></code></p>
-    <p><code>&#160;&lt;fo:table-column column-width="150pt"/></code></p>
-    <p><code>&#160;&lt;fo:table-body font-size="10pt" font-family="sans-serif"></code></p>
-    <p><code>&#160;&#160;&lt;fo:table-row></code></p>
-    <p><code>&#160;&#160;&#160;&lt;fo:table-cell></code></p>
-    <p><code>&#160;&#160;&#160;&#160;&lt;fo:block>text&lt;/fo:block></code></p>
-    <p><code>&#160;&#160;&#160;&lt;/fo:table-cell></code></p>
-    <p><code>&#160;&#160;&#160;&lt;fo:table-cell></code></p>
-    <p><code>&#160;&#160;&#160;&#160;&lt;fo:block>text&lt;/fo:block></code></p>
-    <p><code>&#160;&#160;&#160;&lt;/fo:table-cell></code></p>
-    <p><code>&#160;&#160;&lt;/fo:table-row></code></p>
-    <p><code>&#160;&#160;&lt;fo:table-row></code></p>
-    <p><code>&#160;&#160;&#160;&lt;fo:table-cell></code></p>
-    <p><code>&#160;&#160;&#160;&#160;&lt;fo:block>text&lt;/fo:block></code></p>
-    <p><code>&#160;&#160;&#160;&lt;/fo:table-cell></code></p>
-    <p><code>&#160;&#160;&#160;&lt;fo:table-cell></code></p>
-    <p><code>&#160;&#160;&#160;&#160;&lt;fo:block>text&lt;/fo:block></code></p>
-    <p><code>&#160;&#160;&#160;&lt;/fo:table-cell></code></p>
-    <p><code>&#160;&#160;&lt;/fo:table-row></code></p>
-    <p><code>&#160;&#160;&lt;fo:table-row></code></p>
-    <p><code>&#160;&#160;&#160;&lt;fo:table-cell></code></p>
-    <p><code>&#160;&#160;&#160;&#160;&lt;fo:block>text&lt;/fo:block></code></p>
-    <p><code>&#160;&#160;&#160;&lt;/fo:table-cell></code></p>
-    <p><code>&#160;&#160;&#160;&lt;fo:table-cell></code></p>
-    <p><code>&#160;&#160;&#160;&#160;&lt;fo:block>text&lt;/fo:block></code></p>
-    <p><code>&#160;&#160;&#160;&lt;/fo:table-cell></code></p>
-    <p><code>&#160;&#160;&lt;/fo:table-row></code></p>
-    <p><code>&#160;&lt;/fo:table-body></code></p>
-    <p><code>&lt;/fo:table></code></p>
+<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>
+</p>
   </s2>
 
 
diff --git a/docs/xml-docs/fop/readme.xml b/docs/xml-docs/fop/readme.xml
index 69e7db6a3..d9a15dddf 100644
--- a/docs/xml-docs/fop/readme.xml
+++ b/docs/xml-docs/fop/readme.xml
@@ -2,7 +2,7 @@
 
 <!-- Overview -->
 
-<s1 title="Fop">
+<s1 title="FOP">
   <s2 title="What is FOP?">
     <p>FOP is the world's first print formatter driven by XSL formatting
        objects. It is a Java application that reads a formatting object
@@ -15,7 +15,7 @@
        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
-       section <jump href="specs.html">specifications</jump>. Please be aware, that 
+       <jump href="resources.html">resources</jump> 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 <jump href="implemented.html">Features</jump> and in section 
diff --git a/docs/xml-docs/fop/running.xml b/docs/xml-docs/fop/running.xml
index 3c2a7ed44..8ee55f348 100644
--- a/docs/xml-docs/fop/running.xml
+++ b/docs/xml-docs/fop/running.xml
@@ -33,16 +33,14 @@
       -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>
+      -l lang     the language to use for user information<br/></source>
     </p>
     <p>[INPUT]<br/>
     <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>
+      -xsl stylesheet   xslt stylesheet<br/></source>
     </p>
 
     <p>[OUTPUT]<br/>
@@ -54,8 +52,7 @@
       -pcl outfile      input will be rendered as pcl file (outfile req'd)<br/>
       -txt outfile      input will be rendered as text file (outfile req'd)<br/>
       -print            input file will be rendered and sent to the printer<br/>
-                        see options with "-print help"<br/>
-    </source>
+                        see options with "-print help"<br/></source>
     </p>
 
     <p>[Examples]<br/>
@@ -65,8 +62,7 @@
       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>
+      Fop foo.fo -awt<br/></source>
     </p>
   </s2>
 
diff --git a/docs/xml-docs/fop/todo.xml b/docs/xml-docs/fop/todo.xml
index aa1effcbf..b2e12c8af 100644
--- a/docs/xml-docs/fop/todo.xml
+++ b/docs/xml-docs/fop/todo.xml
@@ -64,15 +64,10 @@ there are no invalid children. Should help process the layout better.
 </s3>
 </s2>
   <s2 title="Processing Improvements">
-<s3 title="Logging">
-    <p>
-Support for proper logging with logKit.
-    </p>
-</s3>
 <s3 title="Image Handling">
     <p>
-Needs to be a bit more solid and allow for direct insertion of images
-(jpeg) into the pdf.
+Needs to be a bit more solid.
+Allow for direct insertion of jpeg images in svg into the pdf.
     </p>
 </s3>
 <s3 title="Configuration">
@@ -99,9 +94,15 @@ no dependancies on any specific renderers.
 </s3>
 </s2>
   <s2 title="Enhancements">
-<s3 title="linking support in svg">
+<s3 title="font handling">
+    <p>
+Need better handling of font names, since a font can have several names.
+    </p>
+</s3>
+<s3 title="user agent">
     <p>
-support the a link rendering for the svg output.
+A user agent (or some similar thing) is needed to handle adjustable
+values, such as setting dpi resolution.
     </p>
 </s3>
 <s3 title="input from url">
@@ -126,15 +127,20 @@ suggested by Vincent Hardy.
     <p>
 Support for different encoding on different types of streams
 in pdf document.
-For example images.
+For example images and text.
+    </p>
+</s3>
+<s3 title="PDF Graphic State">
+    <p>
+Add support for the pdf graphic state for use with transparency
+in pdf 1.4.
     </p>
 </s3>
 <s3 title="svg features">
     <p>
-currently patterns and gradients are not generated properly
+Currently patterns and gradients are not generated properly
     </p>
 </s3>
-
   </s2>