Split Embedding page to Embedding and Servlets.

Added some more content gathered from fop-user.
Replaced InputHandler usage with JAXP patterns.


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

1 files changed, 240 insertions, 227 deletions

diff --git a/src/documentation/content/xdocs/embedding.xml b/src/documentation/content/xdocs/embedding.xml
index a71431e0c..035b37d70 100644
--- a/src/documentation/content/xdocs/embedding.xml
+++ b/src/documentation/content/xdocs/embedding.xml
@@ -36,231 +36,178 @@
   <p>Here is an example use of Driver which outputs PDF:
   </p>
     <source><![CDATA[
-   import org.apache.fop.apps.Driver;
+import org.apache.fop.apps.Driver;
 
-   /*..*/
+/*..*/
 
-   Driver driver = new Driver(new InputSource(args[0]),
-                              new FileOutputStream(args[1]));
-   driver.setRenderer(Driver.RENDER_PDF);
-   driver.run();]]></source>
+Driver driver = new Driver(new InputSource(args[0]),
+                           new FileOutputStream(args[1]));
+driver.setRenderer(Driver.RENDER_PDF);
+driver.run();]]></source>
   <p>
 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
-    of org.apache.avalon.framework.logger.Logger. See 
-    <jump href="#logging">below</jump> for more information.
-  </p>
+  <section id="basic-logging">
+    <title>Logging</title>
+    <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
+      of org.apache.avalon.framework.logger.Logger. See 
+      <jump href="#logging">below</jump> for more information.
+    </p>
+    <p>
+      Call <code>setLogger(Logger)</code> always immediately after 
+      instantiating the Driver object. See here:
+    </p>
     <source><![CDATA[
-   import org.apache.avalon.framework.logger.Logger; 
-   import org.apache.avalon.framework.logger.ConsoleLogger; 
-   
-   /*..*/
-    
-   Logger logger = new ConsoleLogger(ConsoleLogger.LEVEL_INFO);
-   MessageHandler.setScreenLogger(logger);
-   driver.setLogger(logger);]]></source>
+import org.apache.avalon.framework.logger.Logger; 
+import org.apache.avalon.framework.logger.ConsoleLogger; 
 
-  <p>To setup the user config file you can do the following
-  </p>
+/*..*/
+
+Driver driver = new Driver();
+Logger logger = new ConsoleLogger(ConsoleLogger.LEVEL_INFO);
+MessageHandler.setScreenLogger(logger);
+driver.setLogger(logger);]]></source>
+  </section>
+
+  <section id="render">
+    <title>Processing XSL-FO</title>
+    <p>
+      Once the Driver is set up, one of the <code>render()</code> methods
+      is called. Depending on whether DOM or an InputSource is being used, the
+      invocation of the method is either <code>render(Document)</code> or
+      <code>render(Parser, InputSource)</code> respectively.
+    </p>
+    <p>
+      <strong>Another possibility may be used to build the FO Tree: You can
+      call <code>getContentHandler()</code> and fire the SAX events yourself.
+      </strong>
+      You don't have to call <code>run()</code> or <code>render()</code> on the 
+      Driver object if you use <code>getContentHandler()</code>.
+    </p>
+    <p>Here is an example use of Driver:</p>
     <source><![CDATA[
-   import org.apache.fop.apps.Options;
-   
-   /*..*/ 
-    
-   userConfigFile = new File(userConfig);
-   options = new Options(userConfigFile);]]></source>
-    <note>
-        This is all you need to do, it sets up a static configuration class.
-    </note>
+Driver driver = new Driver();
+//Setup logging here: driver.setLogger(...
+driver.setRenderer(Driver.RENDER_PDF);
+driver.setInputSource(new FileInputSource(args[0]));
+driver.setOutputStream(new FileOutputStream(args[1]));
+driver.run();]]></source>
+  </section>
 
-  <p>Once the Driver is set up, the render method
-     is called. Depending on whether DOM or SAX is being used, the
-     invocation of the method is either <code>render(Document)</code> or
-     <code>render(Parser, InputSource)</code> respectively.
-  </p>
-  <p>
-     <strong>Another possibility may be used to build the FO Tree. You can
-     call <code>getContentHandler()</code> and fire the SAX events yourself.
-     </strong>
-  </p>
-  <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:</p>
-  <source><![CDATA[
-  Driver driver = new Driver();
-  driver.setRenderer(Driver.RENDER_PDF);
-  driver.setInputSource(new FileInputSource(args[0]));
-  driver.setOutputStream(new FileOutputStream(args[1]));
-  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>
-  <source><![CDATA[
-  Driver driver = new Driver();
-  driver.setRenderer(Driver.RENDER_PDF);
-  InputHandler inputHandler = new XSLTInputHandler(xmlFile, xslFile);
-  XMLReader parser = inputHandler.getParser();
-  driver.setOutputStream(new FileOutputStream(outFile));
-  driver.render(parser, inputHandler.getInputSource());]]></source>
-  <p>Have a look at the classes CommandLineStarter or FopServlet for complete
-     examples. Also, have a look at the examples at the bottom of this page.
-  </p>
+  <section id="render-with-xslt">
+    <title>Processing XSL-FO generated from XML+XSLT</title>
+    <p>
+      If you want to process XSL-FO generated from XML using XSLT we recommend 
+      using standard JAXP to do the XSLT part and piping the generated SAX 
+      events directly through to FOP. Here's how this would look like:
+    </p>
+    <source><![CDATA[
+Driver driver = new Driver();
+//Setup logging here: driver.setLogger(...
+driver.setRenderer(Driver.RENDER_PDF);
+
+//Setup the OutputStream for FOP
+driver.setOutputStream(new java.io.FileOutputStream(outFile));
+
+//Make sure the XSL transformation's result is piped through to FOP
+Result res = new SAXResult(driver.getContentHandler());
+
+//Setup XML input
+Source src = new StreamSource(xmlFile);
 
-<note>If your XSL-FO files contain SVG then Batik will be used. When Batik is
-initialised it uses certain classes in <code>java.awt</code> that
-intialises the java AWT classes. This means that a daemon thread
-is created by the JVM and on Unix it will need to connect to a
-DISPLAY.
-The thread means that the Java application will not automatically quit
-when finished, you will need to call <code>System.exit()</code>. These
-issues should be fixed in the upcoming JDK 1.4</note>
+//Setup Transformer
+Source xsltSrc = new StreamSource(xslFile);
+TransformerFactory transformerFactory = TransformerFactory.newInstance();
+Transformer transformer = transformerFactory.newTransformer(xsltSrc);
 
+//Start the transformation and rendering process
+transformer.transform(src, res);]]></source>
+    <note>There's no need to call <code>run()</code> or <code>render()</code>.</note>
+    <p>
+      This may look complicated at first, but it's really just the combination of an 
+      XSL transformation and a FOP run. It's also easy to comment out the FOP part
+      for debugging purposes, for example when you're tracking down a bug in your 
+      stylesheet. You can easily write the XSL-FO output from the XSL transformation
+      to a file to check if that part generates the expected output.
+    </p>
+    <p>
+      For fully working examples of the above and hints to some interesting 
+      possibilities, see the <link href="#examples">examples section</link> below.
+    </p>
+  </section>
   </section>
   <section id="logging">
     <title>Controlling logging</title>
-    <p>FOP uses Jakarta Avalon's
-      <fork href="http://jakarta.apache.org/avalon/api/org/apache/avalon/framework/logger/Logger.html">Logger</fork>
-       interface to do logging. See the <fork href="http://jakarta.apache.org/avalon/">Jakarta Avalon project</fork> 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>
+    <p>
+      FOP uses the
+      <fork href="http://avalon.apache.org/framework/api/org/apache/avalon/framework/logger/package-summary.html">Logger package</fork>
+      from Apache Avalon Framework to do logging. See the 
+      <fork href="http://avalon.apache.org/framework/">Apache Avalon Framework</fork>
+      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}" );
+Hierarchy hierarchy = Hierarchy.getDefaultHierarchy();
+PatternFormatter formatter = new PatternFormatter(
+    "[%{priority}]: %{message}\n%{throwable}" );
 
-    LogTarget target = null;
-    target = new StreamTarget(System.out, formatter);
+LogTarget target = null;
+target = new StreamTarget(System.out, formatter);
 
-    hierarchy.setDefaultLogTarget(target);
-    log = hierarchy.getLoggerFor("fop");
-    log.setPriority(Priority.INFO);
+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 <fork href="http://jakarta.apache.org/avalon/logkit/index.html">here</fork>.</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>
-  </section>
-    <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>
-See the <link href="#examples">Examples</link> for some variations on input. 
-     </p>
-    </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
-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>
-    </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 
-<code>Driver.getResults()</code>. 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.
-      </p>
-    </section>
-  </section>
-  <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 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 id="servlet-transform">
-    <title>Using FOP in a Servlet with an XSLT Transformation</title>
+driver.setLogger(new org.apache.avalon.framework.logger.LogKitLogger(log));]]></source>
     <p>
-      If both the source XML and XSL are read from files, use the TraxInputHandler:
+      The LogKitLogger class implements the Logger interface so all logging calls are being redirected to LogKit.
+      More information on Jakarta LogKit can be found <fork href="http://jakarta.apache.org/avalon/logkit/index.html">here</fork>.
     </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>.
+      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 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:
+      If you want FOP to be totally silent you can also set an org.apache.avalon.framework.logger.NullLogger instance.
     </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.
+      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 id="input">
+    <title>Input Sources</title>
     <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.
+      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>
-      Because you have an explicit transformer object, you can also use it to explicitly set parameters for the transformation run.
+      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>
+      See the <link href="#examples">Examples</link> for some variations on input. 
     </p>
   </section>
   <section id="config-external">
@@ -268,9 +215,19 @@ You may also use dynamically generated XSL if you like.
     <p>
       To access an external configuration:
     </p>
-    <source>org.apache.fop.apps.Options options = new Options(new File("userconfig.xml"));</source>
+    <source><![CDATA[
+import org.apache.fop.apps.Options;
+
+/*..*/
+
+userConfigFile = new File(userConfig);
+options = new Options(userConfigFile);]]></source>
+    <note>
+        This is all you need to do, it sets up a static configuration class.
+    </note>
     <p>
       No further reference to the <code>options</code> variable is necessary.
+      The "options = " is actually not even necessary.
     </p>
     <p>
       See <link href="#multithreading">Multithreading FOP</link> for issues related to changing configuration in a multithreaded environment.
@@ -290,6 +247,82 @@ You may also use dynamically generated XSL if you like.
       See <link href="#multithreading">Multithreading FOP</link> for issues related to changing configuration in a multithreaded environment.
     </p>
   </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
+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 <code>reset()</code> method is called.
+You will need to setup the driver again with a new OutputStream,
+IntputStream and renderer.
+     </p>
+    </section>
+    <section id="awt">
+      <title>AWT issues</title>
+      <p>
+        If your XSL-FO files contain SVG then Batik will be used. When Batik is
+        initialised it uses certain classes in <code>java.awt</code> that
+        intialises the java AWT classes. This means that a daemon thread
+        is created by the JVM and on Unix it will need to connect to a
+        DISPLAY.
+      </p>
+      <p>
+        The thread means that the Java application may not automatically quit
+        when finished, you will need to call <code>System.exit()</code>. These
+        issues should be fixed in the upcoming JDK 1.4.
+      </p>
+      <p>
+        If you run into trouble running FOP on a head-less server, please see the
+        <link href="graphics.html#batik">notes on Batik</link>.
+      </p>
+    </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 
+<code>Driver.getResults()</code>. 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.
+      </p>
+    </section>
+  </section>
+  <section id="performance">
+    <title>Improving performance</title>
+    <p>
+      There are several options to consider:
+    </p>
+    <ul>
+      <li>
+        Whenever possible, try to use SAX to couple the individual components involved 
+        (parser, XSL transformer, SQL datasource etc.).
+      </li>
+      <li>
+        Depending on the target OutputStream (in case of an FileOutputStream, but not 
+        for a ByteArrayOutputStream, for example) it may improve performance considerably 
+        if you buffer the OutputStream using a BufferedOutputStream: 
+        <code>driver.setOutputStream(new java.io.BufferedOutputStream(out));</code>
+        <br/>
+        Make sure you properly close the OutputStream when FOP is finished.
+      </li>
+      <li>
+        Cache the stylesheet. If you use the same stylesheet multiple times 
+        you can setup a JAXP <code>Templates</code> object and reuse it each time you do
+        the XSL transformation.
+      </li>
+      <li>
+        Use an XSLT compiler like XSLTC that comes with Xalan-J.
+      </li>
+    </ul>
+  </section>
   <section id="multithreading">
     <title>Multithreading FOP</title>
     <p>
@@ -299,44 +332,24 @@ 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>
+        To avoid having your threads blocked, create a Driver object for each thread.
       </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>
+        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. 
+The directory "{fop-fir}/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>