diff options
Diffstat (limited to 'src/documentation/content/xdocs/0.20.5')
| -rw-r--r-- | src/documentation/content/xdocs/0.20.5/anttask.xml | 180 | ||||
| -rw-r--r-- | src/documentation/content/xdocs/0.20.5/compiling.xml | 88 | ||||
| -rw-r--r-- | src/documentation/content/xdocs/0.20.5/configuration.xml | 104 | ||||
| -rw-r--r-- | src/documentation/content/xdocs/0.20.5/embedding.xml | 520 | ||||
| -rw-r--r-- | src/documentation/content/xdocs/0.20.5/extensions.xml | 109 | ||||
| -rw-r--r-- | src/documentation/content/xdocs/0.20.5/fonts.xml | 262 | ||||
| -rw-r--r-- | src/documentation/content/xdocs/0.20.5/graphics.xml | 288 | ||||
| -rw-r--r-- | src/documentation/content/xdocs/0.20.5/hyphenation.xml | 237 | ||||
| -rw-r--r-- | src/documentation/content/xdocs/0.20.5/index.xml | 30 | ||||
| -rw-r--r-- | src/documentation/content/xdocs/0.20.5/output.xml | 324 | ||||
| -rwxr-xr-x | src/documentation/content/xdocs/0.20.5/pdfencryption.xml | 209 | ||||
| -rw-r--r-- | src/documentation/content/xdocs/0.20.5/running.xml | 189 | ||||
| -rw-r--r-- | src/documentation/content/xdocs/0.20.5/servlets.xml | 263 |
13 files changed, 2803 insertions, 0 deletions
diff --git a/src/documentation/content/xdocs/0.20.5/anttask.xml b/src/documentation/content/xdocs/0.20.5/anttask.xml new file mode 100644 index 000000000..51623f4a3 --- /dev/null +++ b/src/documentation/content/xdocs/0.20.5/anttask.xml @@ -0,0 +1,180 @@ +<?xml version="1.0" standalone="no"?> +<!-- + Copyright 1999-2004 The Apache Software Foundation + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<!-- $Id$ --> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" + "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/core/context/resources/schema/dtd/document-v12.dtd"> + +<document> + <header> + <title>Ant task</title> + <version>$Revision$</version> + </header> + <body> + <p> + FOP provides an Ant task for automating the document build process.</p> + <section id="basics"><title>Description</title> + <p> + The FOP Ant task will convert XSL-FO documents to PDF/PS/PCL/MIF/RTF output + (see <link href="output.html">Output formats</link> for available formats).</p> + <p> + To call FOP tasks within Ant, first add a FOP task definition to your Ant build file. + One method of defining the task is as follows: + </p> + <source><![CDATA[ +<property name="fop.dir" value="....path to your FOP jar files..."/> + +<taskdef name="fop" + classname="org.apache.fop.tools.anttasks.Fop"> + <classpath> + <pathelement location="${fop.dir}\fop.jar"/> + <pathelement location="${fop.dir}\avalon.jar"/> + <pathelement location="${fop.dir}\batik.jar"/> + </classpath> +</taskdef> + ]]></source> +<p> + Then create FOP tasks within your Ant build file, using the FOP task parameters listed below.</p> + </section> + <!-- TODO: Installation/Configuration --> + <section id="parameters"><title>Parameters for FOP Ant task</title> + <table><caption>Parameters specified as attributes</caption> + <tr> + <th>Attribute</th> + <th>Description</th> + <th>Required</th> + </tr> + <tr> + <td>fofile</td> + <td>XSL-FO file to be rendered</td> + <td>Yes, if no fileset nested element is used</td> + </tr> + <tr> + <td>outfile</td> + <td>Output filename</td> + <td>Yes, when fofile is used. (This attribute is not valid for filesets.)</td> + </tr> + <tr> + <td>format</td> + <td>Possible output formats:<br/> + <code>application/pdf</code><br/> + <code>application/postscript</code><br/> + <code>application/vnd.mif</code><br/> + <code>application/rtf</code><br/> + <code>application/vnd.hp-PCL</code><br/> + <code>text/plain</code><br/> + <code>text/xml</code><br/> + </td> + <td>No, defaults to <code>application/pdf</code></td> + </tr> + <tr> + <td>outdir</td> + <td>Output directory</td> + <td>Required if a fileset is used to specify the files to render; optional for fofile. (Can alternatively specify the full path in the fofile value.)</td> + </tr> + <tr> + <td>force</td> + <td>Recreate target files, even if they are newer than their corresponding + source files. Note: This attribute is available in post-0.20.5 + versions (0.20.x nightly build and 1.0dev) only; target files are + always generated (i.e., force=true) in 0.20.5 release. + </td> + <td>No, default is <code>false</code></td> + </tr> + <tr> + <td>basedir</td> + <td>Base directory to resolve relative references (e.g., graphics files) within the + FO document. + </td> + <td>No, for single FO File entry, default is to use the location + of that FO file. + </td> + </tr> + <tr> + <td>relativebase</td> + <td>For fileset usage only. A value of <code>true</code> specifies using the location + of each .fo file as the base directory for resolving relative file references located + within that .fo file. A value of <code>false</code> specifies using the value of + basedir for all files within the fileset, or just the current working directory + if basedir is not specified. + </td> + <td>No, default is <code>false</code>. + </td> + </tr> + <tr> + <td>userconfig</td> + <td>User configuration file (same as the FOP "-c" command line option)</td> + <td>No</td> + </tr> + <tr> + <td>messagelevel</td> + <td>Logging level<br/> + Possible values: <code>error</code>, <code>warn</code>, <code>info</code>, <code>verbose</code>, <code>debug</code></td> + <td>No, defaults to <code>verbose</code></td> + </tr> + <tr> + <td>logFiles</td> + <td>Controls whether the names of the files that are processed are logged + (<code>true</code>) or not (<code>false</code>)</td> + <td>No, default is <code>true</code></td> + </tr> + </table> + <p/> + <table><caption>Parameters specified as nested elements</caption> + <tr> + <th>Attribute</th> + <th>Description</th> + <th>Required</th> + </tr> + <tr> + <td>fileset</td> + <td><link href="http://ant.apache.org/manual/CoreTypes/fileset.html">FileSets</link> + are used to specify multiple XSL-FO files to be rendered.</td> + <td>Yes, if no fofile attribute is supplied</td> + </tr> + </table> + </section> + <section id="examples"> + <title>Examples</title> + <p> + The following example converts a single XSL-FO file to a PDF document: + </p> + + <source><![CDATA[ +<target name="generate-pdf" description="Generates a single PDF file"> + <fop format="application/pdf" + fofile="c:\working\foDirectory\foDocument.fo" + outfile="c:\working\pdfDirectory\pdfDocument.pdf" /> +</target> + ]]></source> + <p> + This example converts all XSL-FO files within an entire directory to PostScript: + </p> + <source><![CDATA[ +<target name="generate-multiple-ps" + description="Generates multiple PostScript files"> + <fop format="application/postscript" + outdir="${build.dir}" messagelevel="debug"> + <fileset dir="${fo.examples.dir}"> + <include name="*.fo"/> + </fileset> + </fop> +</target> + ]]></source> + </section> + </body> +</document> + diff --git a/src/documentation/content/xdocs/0.20.5/compiling.xml b/src/documentation/content/xdocs/0.20.5/compiling.xml new file mode 100644 index 000000000..6f66d15d8 --- /dev/null +++ b/src/documentation/content/xdocs/0.20.5/compiling.xml @@ -0,0 +1,88 @@ +<?xml version="1.0" standalone="no"?> +<!-- + Copyright 1999-2004 The Apache Software Foundation + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<!-- $Id$ --> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" + "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/core/context/resources/schema/dtd/document-v12.dtd"> + +<document> + <header> + <title>FOP: Building from Source Code</title> + <version>$Revision$</version> + </header> + <body> + <section id="build-needed"> + <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 id="env"> + <title>Set Up Your Environment</title> + <section id="env-jdk"> + <title>JDK</title> + <p> + Building FOP requires a minimum Java Development Kit (JDK/SDK) of 1.3 + (A Java Runtime Environment is not sufficient). + </p> + </section> + <section id="env-classpath"> + <title>CLASSPATH</title> + <p>There is 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 id="env-java-home"> + <title>JAVA_HOME</title> + <p>The build script uses <link href="http://jakarta.apache.org/ant/">Ant</link>, a popular java-based build tool, which 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 does not need this setting.</p> + </section> + </section> + <section id="build-script"> + <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 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 id="problems"> + <title id="Troubleshooting">Troubleshooting</title> + <p>If you have problems building FOP, please try the following:</p> + <ul> + <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> + </body> +</document> + diff --git a/src/documentation/content/xdocs/0.20.5/configuration.xml b/src/documentation/content/xdocs/0.20.5/configuration.xml new file mode 100644 index 000000000..90e6e7067 --- /dev/null +++ b/src/documentation/content/xdocs/0.20.5/configuration.xml @@ -0,0 +1,104 @@ +<?xml version="1.0" standalone="no"?> +<!-- + Copyright 1999-2004 The Apache Software Foundation + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<!-- $Id$ --> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" + "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/core/context/resources/schema/dtd/document-v12.dtd"> + +<document> + <header> + <title>FOP: Configuration</title> + <version>$Revision$</version> + </header> + + <body> + <section id="general"> + <title>Configuration File Basics</title> + <p>The FOP configuration file is an XML file containing a variety of settings that are useful for controlling FOP's behavior, and for helping it find resources that you wish it to use.</p> + <p>The easiest way to get started using a FOP configuration file is to copy the sample found at <code>{fop-dir}/conf/userconfig.xml</code> to a location of your choice, and then to edit it according to your needs. +It contains templates for the various configuration options, most of which are commented out. Remove the comments and change the settings for entries that you wish to use. +Be sure to follow any instructions, including comments which specify the value range. +Also, since the configuration file is XML, be sure to keep it well-formed.</p> + <note>Do <strong>not</strong> change <code>{fop-dir}/conf/config.xml</code> or use it as the basis for your configuration file. It has an entirely different purpose.</note> + <section id="general-entries"> + <title>Creating Entries</title> + <p>The general structure of the configuration file is a series of <entry> tags, each containing a <key> and a <value>. (Fonts use a different format). Here is an example:</p> + <source><![CDATA[<entry> + <key>strokeSVGText</key> + <value>false</value> +</entry>]]></source> + </section> + <section id="general-available"> + <title>Making Configuration Available to FOP</title> + <p>After creating your configuration file, you must tell FOP how to find it:</p> + <ul> + <li>If running FOP from the command-line, see the "-c" command-line option in <link href="running.html">Running FOP</link>.</li> + <li>If running FOP as an embedded application, see <link href="embedding.html#config-external">FOP: Embedding, Using a Configuration File</link>.</li> + </ul> + <p>See <link href="embedding.html#config-internal">Setting the Configuration Programmatically</link> for instructions on how to do so in an embedded environment.</p> + </section> + </section> + <section id="summary-key-value"> + <title>Summary of Key-Value Configuration Options</title> + <table> + <tr> + <th>Option (key)</th> + <th>Data Type (for the value)</th> + <th>Default Value</th> + </tr> + <tr> + <td>baseDir</td> + <td>URL</td> + <td>For command-line, the directory containing the input FO or XML file. For embedded, the current working directory.</td> + </tr> + <tr> + <td>fontBaseDir</td> + <td>URL</td> + <td>value of baseDir</td> + </tr> + <tr> + <td><link href="#hyphenation-dir">hyphenation-dir</link></td> + <td>URL</td> + <td>None. This is for custom hyphenation patterns.</td> + </tr> + <tr> + <td><link href="#svg-strokeSVGText">strokeSVGText</link></td> + <td>Boolean</td> + <td>True</td> + </tr> + </table> + </section> + <section id="detail-key-value"> + <title>Detail for Key-Value Configuration Options</title> + <p>The sections below provide detailed information for configuration options that are not self-explanatory. The parenthetical information after each key name indicates (Data Type, Default).</p> + <section id="hyphenation-dir"> + <title>hyphenation-dir (URL, none)</title> + <p>Use this entry to indicate a directory containing custom hyphenation files (if any). +See <link href="hyphenation.html">FOP: Hyphenation</link> for more information on creating and modifying hyphenation within FOP.</p> + </section> + <section id="strokeSVGText"> + <title>strokeSVGText (boolean, True)</title> + <p>In some cases, some text in SVG documents is converted to graphical shapes instead of retaining its character as text. To force all text to be rendered as text, set strokeSVGText = false. For a discussion of this issue, see <link href="graphics.html#svg-pdf-text">FOP: Graphics, Placing SVG Text into PDF</link>.</p> + <note>strokeSVGText is currently only effective in the PDF renderer.</note> + </section> + </section> + <section id="fonts"> + <title>Fonts</title> + <p>Font configuration information is included in the FOP configuration file, but is documented at <link href="fonts.html">FOP: Fonts</link>. Note especially the section entitled <link href="fonts.html#register">Register Fonts with FOP</link>.</p> + </section> + </body> +</document> + diff --git a/src/documentation/content/xdocs/0.20.5/embedding.xml b/src/documentation/content/xdocs/0.20.5/embedding.xml new file mode 100644 index 000000000..5baec0d12 --- /dev/null +++ b/src/documentation/content/xdocs/0.20.5/embedding.xml @@ -0,0 +1,520 @@ +<?xml version="1.0" standalone="no"?> +<!-- + Copyright 1999-2004 The Apache Software Foundation + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<!-- $Id$ --> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" + "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/core/context/resources/schema/dtd/document-v12.dtd"> + + +<!-- Embedding FOP --> +<document> + <header> + <title>FOP: Embedding</title> + <subtitle>How to Embed FOP in a Java application</subtitle> + <version>$Revision$</version> + </header> + + <body> + <section id="overview"> + <title>Overview</title> + <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 + 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 + instantiate the class itself. The advantage of the latter is it + enables runtime determination of Renderer and ElementMapping(s). + </p> + </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 + call the run method. + </p> + <p>Here is an example use of Driver which outputs PDF: + </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); +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> + <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; + +/*..*/ + +Driver driver = new Driver(); +Logger logger = new ConsoleLogger(ConsoleLogger.LEVEL_INFO); +MessageHandler.setScreenLogger(logger); +driver.setLogger(logger);]]></source> + </section> + + <section id="basic-logging-new-version"> + <title>Logging (Upcoming FOP 1.0 Version only)</title> + <p> + Logging is handled automatically via Jakarta Commons-Logging, which uses + JDK logging by default. No special driver configuration is needed. + For specialized configuration of Commons-Logging (e.g. to use a + different logger or to change logging levels), please see the + <fork href="http://jakarta.apache.org/commons/logging/">Jakarta Commons-Logging</fork> + site. + </p> + </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[ +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> + + <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); + +//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> + Current FOP 0.20.x production 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 SimpleLog 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 <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="config-external"> + <title>Using a Configuration File</title> + <p> + To access an external configuration: + </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> + <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. + </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="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. (More information can be found + <fork href="http://www.javaworld.com/javaworld/jw-05-2003/jw-0502-xsl.html">here</fork>.) + </li> + <li> + Use an XSLT compiler like <fork href="http://xml.apache.org/xalan-j/xsltc_usage.html">XSLTC</fork> + that comes with Xalan-J. + </li> + </ul> + </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> + <p>There is also a known issue with fonts being jumbled between threads when using the AWT renderer (which is used by the -awt and -print output options). +In general, you cannot safely run multiple threads through the AWT renderer.</p> + </section> +<section id="examples"> + <title>Examples</title> + <p> +The directory "{fop-dir}/examples/embedding" contains several working examples. +In contrast to 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 id="ExampleFO2PDF"> + <title>ExampleFO2PDF.java</title> + <p>This example + <fork href="http://svn.apache.org/viewcvs.cgi/xmlgraphics/fop/tags/fop-0_20_5/examples/embedding/java/embedding/ExampleFO2PDF.java?view=markup"> + (current 0.20.5)</fork> + <fork href="http://svn.apache.org/viewcvs.cgi/xmlgraphics/fop/trunk/examples/embedding/java/embedding/ExampleFO2PDF.java?view=markup"> + (future 1.0dev)</fork> +demonstrates the basic usage pattern to transform an XSL-FO +file to PDF using FOP. + </p> + <figure src="images/EmbeddingExampleFO2PDF.png" alt="Example XSL-FO to PDF"/> + </section> + <section id="ExampleXML2FO"> + <title>ExampleXML2FO.java</title> + <p>This example + <fork href="http://svn.apache.org/viewcvs.cgi/xmlgraphics/fop/tags/fop-0_20_5/examples/embedding/java/embedding/ExampleXML2FO.java?view=markup"> + (current 0.20.5)</fork> + <fork href="http://svn.apache.org/viewcvs.cgi/xmlgraphics/fop/trunk/examples/embedding/java/embedding/ExampleXML2FO.java?view=markup"> + (future 1.0dev)</fork> +has nothing to do with FOP. It is there to show you how an XML +file can be converted to XSL-FO using XSLT. The JAXP API is used to do the +transformation. Make sure you've got a JAXP-compliant XSLT processor in your +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 id="ExampleXML2PDF"> + <title>ExampleXML2PDF.java</title> + <p>This example + <fork href="http://svn.apache.org/viewcvs.cgi/xmlgraphics/fop/tags/fop-0_20_5/examples/embedding/java/embedding/ExampleXML2PDF.java?view=markup"> + (current 0.20.5)</fork> + <fork href="http://svn.apache.org/viewcvs.cgi/xmlgraphics/fop/trunk/examples/embedding/java/embedding/ExampleXML2PDF.java?view=markup"> + (future 1.0dev)</fork> +demonstrates how you can convert an arbitrary XML file to PDF +using XSLT and XSL-FO/FOP. It is a combination of the first two examples +above. The example uses JAXP to transform the XML file to XSL-FO and FOP to +transform the XSL-FO to PDF. + </p> + <figure src="images/EmbeddingExampleXML2PDF.png" alt="Example XML to PDF (via XSL-FO)"/> + <p> +The output (XSL-FO) from the XSL transformation is piped through to FOP using +SAX events. This is the most efficient way to do this because the +intermediate result doesn't have to be saved somewhere. Often, novice users +save the intermediate result in a file, a byte array or a DOM tree. We +strongly discourage you to do this if it isn't absolutely necessary. The +performance is significantly higher with SAX. + </p> + </section> + <section id="ExampleObj2XML"> + <title>ExampleObj2XML.java</title> + <p>This example + <fork href="http://svn.apache.org/viewcvs.cgi/xmlgraphics/fop/tags/fop-0_20_5/examples/embedding/java/embedding/ExampleObj2XML.java?view=markup"> + (current 0.20.5)</fork> + <fork href="http://svn.apache.org/viewcvs.cgi/xmlgraphics/fop/trunk/examples/embedding/java/embedding/ExampleObj2XML.java?view=markup"> + (future 1.0dev)</fork> +is a preparatory example for the next one. It's an example that +shows how an arbitrary Java object can be converted to XML. It's an often +needed task to do this. Often people create a DOM tree from a Java object and +use that. This is pretty straightforward. The example here however shows how +to do this using SAX which will probably be faster and not even more +complicated once you know how this works. + </p> + <figure src="images/EmbeddingExampleObj2XML.png" alt="Example Java object to XML"/> + <p> +For this example we've created two classes: ProjectTeam and ProjectMember +(found in xml-fop/examples/embedding/java/embedding/model). They represent +the same data structure found in +xml-fop/examples/embedding/xml/xml/projectteam.xml. We want to serialize a +project team with several members which exist as Java objects to XML. +Therefore we created the two classes: ProjectTeamInputSource and +ProjectTeamXMLReader (in the same place as ProjectTeam above). + </p> + <p> +The XMLReader implementation (regard it as a special kind of XML parser)is +responsible for creating SAX events from the Java object. The InputSource +class is only used to hold the ProjectTeam object to be used. + </p> + <p> +Have a look at the source of ExampleObj2XML.java to find out how this is +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 id="ExampleObj2PDF"> + <title>ExampleObj2PDF.java</title> + <p>This example + <fork href="http://svn.apache.org/viewcvs.cgi/xmlgraphics/fop/tags/fop-0_20_5/examples/embedding/java/embedding/ExampleObj2PDF.java?view=markup"> + (current 0.20.5)</fork> + <fork href="http://svn.apache.org/viewcvs.cgi/xmlgraphics/fop/trunk/examples/embedding/java/embedding/ExampleObj2PDF.java?view=markup"> + (future 1.0dev)</fork> +combines the previous and the third to demonstrate +how you can transform a Java object to a PDF directly in one smooth run +by generating SAX events from the Java object that get fed to an XSL +transformation. The result of the transformation is then converted to PDF +using FOP as before. + </p> + <figure src="images/EmbeddingExampleObj2PDF.png" alt="Example Java object to PDF (via XML and XSL-FO)"/> + </section> + <section id="ExampleDOM2PDF"> + <title>ExampleDOM2PDF.java</title> + <p>This example + <fork href="http://svn.apache.org/viewcvs.cgi/xmlgraphics/fop/tags/fop-0_20_5/examples/embedding/java/embedding/ExampleDOM2PDF.java?view=markup"> + (current 0.20.5)</fork> + <fork href="http://svn.apache.org/viewcvs.cgi/xmlgraphics/fop/trunk/examples/embedding/java/embedding/ExampleDOM2PDF.java?view=markup"> + (future 1.0dev)</fork> +has FOP use a DOMSource instead of a StreamSource in order to +use a DOM tree as input for an XSL transformation. + </p> + </section> + <section id="ExampleSVG2PDF"> + <title>ExampleSVG2PDF.java (PDF Transcoder example)</title> + <p>This example + <fork href="http://svn.apache.org/viewcvs.cgi/xmlgraphics/fop/trunk/examples/embedding/java/embedding/ExampleSVG2PDF.java?view=markup"> + (applies to 0.20.5 and future 1.0dev)</fork> +shows use of the PDF Transcoder, a sub-application within FOP. +It is used to generate a PDF document from an SVG file. + </p> + </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 +to adjust these examples to your needs. Also, if you have other examples that you +think should be added here, please let us know via either the FOP-USER or FOP-DEV +mailing lists. Finally, for more help please send your questions to the FOP-USER +mailing list. + </p> + </section> +</section> + </body> +</document> + diff --git a/src/documentation/content/xdocs/0.20.5/extensions.xml b/src/documentation/content/xdocs/0.20.5/extensions.xml new file mode 100644 index 000000000..6f286dd46 --- /dev/null +++ b/src/documentation/content/xdocs/0.20.5/extensions.xml @@ -0,0 +1,109 @@ +<?xml version="1.0" standalone="no"?> +<!-- + Copyright 1999-2004 The Apache Software Foundation + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<!-- $Id$ --> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" + "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/core/context/resources/schema/dtd/document-v12.dtd"> + +<document> + <header> + <title>Standard FOP Extensions</title> + <version>$Revision$</version> + </header> + <body> + <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="graphics.html#svg">SVG documentation</link> for more details. + </p> + </section> + <section id="fo-extensions"> + <title>FO Extensions</title> + <section id="fox-namespace"> + <title>Namespace</title> + <p>By convention, FO extensions in FOP use the "fox:" namespace identifier. +To use any of the FO extensions, add a namespace entry for http://xml.apache.org/fop/extensions +to the root element:</p> +<source><![CDATA[<fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format" + xmlns:fox="http://xml.apache.org/fop/extensions">]]></source> + </section> + <section id="bookmarks"> + <title>PDF Bookmarks</title> + <p> +You can provide outlines inside the root object (but outside any +page-sequences or other formatting objects). Here's an example of an outline +entry: + </p> + <source> +<![CDATA[<fox:outline internal-destination="sec3"> + <fox:label>Running FOP</fox:label> + + <fox:outline internal-destination="sec3-1"> + <fox:label>Prerequisites</fox:label> + </fox:outline> + </fox:outline> +</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 +examples/fo/basic for a more complete example. + </p> + </section> + <section id="named-destinations"> + <title>Anchors or Named Destinations</title> + <p>Use the fox:destination element to define "named destinations" inside a PDF document. +These are useful as fragment identifiers, e.g. "http://server/document.pdf#anchor-name". +fox:destination elements can be placed almost anywhere in the fo document, including a child of +root, a block-level element, or an inline-level element. +For the destination to actually work, it must correspond to an "id" attribute on some fo element +within the document. In other words, the "id" attribute actually creates the "view" within the +PDF document. The fox:destination simply gives that view an independent name. +</p> + <source><![CDATA[<fox:destination internal-destination="table-of-contents"/> +... +<fo:block id="table-of-contents">Table of Contents</fo:block>]]></source> + <warning>It is possible that in some future release of FOP, <em>all </em>elements with +"id" attributes will generate named-destinations, which will eliminate the need for +fox:destination.</warning> + </section> + <section id="table-continue-label"> + <title>Table Continuation Label</title> + <p>Use the fox:continued-label element to create content in table-header and +table-footer cells that will appear only on pages after the first page that the table +appears. fox:continued-label is itself inline content, and is a container of fo:inline +content. This content will be laid out only if the table does not fit on a single page and flows +to following pages. Here is an example of FO code creating such a table-header:</p> +<source><![CDATA[<fo:table-header> + <fo:table-row> + <fo:table-cell> + <fo:block>Header column 1 with continued label + <fox:continued-label><fo:inline> (cont.)</fo:inline></fox:continued-label> + </fo:block> + </fo:table-cell> + <fo:table-cell> + <fo:block>Header column 2 with no continued label</fo:block> + </fo:table-cell> + </fo:table-row> +</fo:table-header>]]></source> + </section> + </section> + </body> +</document> + diff --git a/src/documentation/content/xdocs/0.20.5/fonts.xml b/src/documentation/content/xdocs/0.20.5/fonts.xml new file mode 100644 index 000000000..1262bf0dd --- /dev/null +++ b/src/documentation/content/xdocs/0.20.5/fonts.xml @@ -0,0 +1,262 @@ +<?xml version="1.0" standalone="no"?> +<!-- + Copyright 1999-2004 The Apache Software Foundation + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<!-- $Id$ --> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" + "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/core/context/resources/schema/dtd/document-v12.dtd"> +<document> + <header> + <title>FOP: Fonts</title> + <version>$Revision$</version> + <authors> + <person name="Jeremias Märki" email=""/> + <person name="Tore Engvig" email=""/> + </authors> + </header> + <body> + <section id="intro"> + <title>Summary</title> + <p>The following table summarizes the font capabilities of the various FOP renderers:</p> + <table> + <tr> + <th>Renderer</th> + <th>Base-14</th> + <th>AWT/OS</th> + <th>Custom</th> + <th>Custom Embedding</th> + </tr> + <tr> + <td>PDF</td> + <td>yes</td> + <td>no</td> + <td>yes</td> + <td>yes</td> + </tr> + <tr> + <td>PostScript</td> + <td>yes</td> + <td>no</td> + <td>yes</td> + <td>no</td> + </tr> + <tr> + <td>PCL</td> + <td>yes (modified)</td> + <td>no</td> + <td>no</td> + <td>no</td> + </tr> + <tr> + <td>TXT</td> + <td>yes (used for layout but not for output)</td> + <td>no</td> + <td>yes (used for layout but not for output)</td> + <td>no</td> + </tr> + <tr> + <td>AWT</td> + <td>if available from OS</td> + <td>yes</td> + <td>yes</td> + <td>n/a (display only)</td> + </tr> + <tr> + <td>Print</td> + <td>if available from OS</td> + <td>yes</td> + <td>yes</td> + <td>controlled by OS printer driver</td> + </tr> + <tr> + <td>RTF</td> + <td>n/a (font metrics not needed)</td> + <td>n/a</td> + <td>n/a</td> + <td>n/a</td> + </tr> + <tr> + <td>MIF</td> + <td>n/a (font metrics not needed)</td> + <td>n/a</td> + <td>n/a</td> + <td>n/a</td> + </tr> + <tr> + <td>SVG</td> + <td>if available from OS</td> + <td>yes</td> + <td>no</td> + <td>no</td> + </tr> + <tr> + <td>XML</td> + <td>yes</td> + <td>no</td> + <td>yes</td> + <td>n/a</td> + </tr> + </table> + </section> + <section> + <title>Base-14 Fonts</title> + <p>The Adobe PDF Specification specifies a set of 14 fonts that must be available to every PDF reader: Helvetica (normal, bold, italic, bold italic), Times (normal, bold, italic, bold italic), Courier (normal, bold, italic, bold italic), Symbol and ZapfDingbats.</p> + </section> + <section id="awt"> + <title>AWT/Operating System Fonts</title> + <p>The AWT family of renderers (AWT, Print, SVG), use the Java AWT libraries for font metric information. Through operating system registration, the AWT libraries know what fonts are available on the system, and the font metrics for each one.</p> + </section> + <section id="custom"> + <title>Custom Fonts</title> + <p>Support for custom fonts is added by creating font metric files (written in XML) from the actual font files, and registering them with FOP. Currently only Type 1 and TrueType fonts can be added. +More information about fonts can be found at:</p> + <ul> + <li><link href="http://partners.adobe.com/asn/developer/type/ftypes.html">Adobe font types</link></li> + <li><link href="http://partners.adobe.com/asn/developer/technotes/fonts.html">Adobe Font Technote</link> +</li> + </ul> + <section id="type1-metrics"> + <title>Type 1 Font Metrics</title> + <p>FOP includes PFMReader, which reads the PFM file that normally comes with a Type 1 font, and generates an appropriate font metrics file for it. +To use it, run the class org.apache.fop.fonts.apps.PFMReader:</p> + <p>Windows:</p> + <source>java -cp build\fop.jar;lib\avalon-framework.jar;lib\xml-apis.jar; + lib\xercesImpl.jar;lib\xalan.jar + org.apache.fop.fonts.apps.PFMReader [options] pfm-file xml-file</source> + <p>Unix:</p> + <source>java -cp build/fop.jar:lib/avalon-framework.jar:lib/xml-apis.jar: + lib/xercesImpl.jar:lib/xalan.jar + org.apache.fop.fonts.apps.PFMReader [options] pfm-file xml-file</source> + <p>PFMReader [options]:</p> + <ul> + <li><strong>-fn <fontname></strong> By default, FOP uses the fontname from the +.pfm file when embedding the font. Use the "-fn" option to override this name with one you have +chosen. This may be useful in some cases to ensure that applications using the output document +(Acrobat Reader for example) use the embedded font instead of a local font with the same +name.</li> + </ul> + <note>The classpath in the above example has been simplified for readability. +You will have to adjust the classpath to the names of the actual JAR files in the lib directory. +avalon-framework.jar is necessary only for versions 0.20.5 or later. +xml-apis.jar, xercesImpl.jar and xalan.jar are not necessary for JDK version 1.4 or later.</note> + <note>The tool will construct some values (FontBBox, StemV and ItalicAngle) based on assumptions and calculations which are only an approximation to the real values. +FontBBox and Italic Angle can be found in the human-readable part of the PFB file or in the AFM file. +The PFMReader tool does not yet interpret PFB or AFM files, so if you want to be correct, you may have to adjust the values in the XML file manually. +The constructed values however appear to have no visible influence.</note> + </section> + <section id="truetype-metrics"> + <title>TrueType Font Metrics</title> + <p>FOP includes TTFReader, which reads the TTF file and generates an appropriate font metrics file for it. +Use it in a similar manner to PFMReader. +For example, to create such a metrics file in Windows from the TrueType font at c:\myfonts\cmr10.ttf:</p> + <source>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 [options] + C:\myfonts\cmr10.ttf ttfcm.xml</source> + <p>TTFReader [options]:</p> + <ul> + <li><strong>-d <DEBUG | INFO ></strong> Sets the debug level (default is +INFO).</li> + <li><strong>-fn <fontname></strong> Same as for PFMReader.</li> + <li><strong>-ttcname <fontname></strong> If you're reading data from a +TrueType Collection (.ttc file) you must specify which font from the collection you will read +metrics from. +If you read from a .ttc file without this option, the fontnames will be listed for you.</li> + <li><strong>-enc ansi</strong> Creates a WinAnsi-encoded font metrics file. +Without this option, a CID-keyed font metrics file is created. +The table below summarizes the differences between these two encoding options as currently +used within FOP. +Please note that this information only applies to TrueType fonts and TrueType collections:</li> + </ul> + <table id="ttf-encoding"> + <tr> + <th>Issue</th> + <th>WinAnsi</th> + <th>CID-keyed</th> + </tr> + <tr> + <td>Usable Character Set</td> + <td>Limited to WinAnsi character set, which is roughly equivalent to iso-8889-1.</td> + <td>Limited only by the characters in the font itself.</td> + </tr> + <tr> + <td>Character Encoding in the Output Document.</td> + <td>Correct.</td> + <td>Never correct. Search, index, and cut-and-paste operations in the output document +will produce incorrect results.</td> + </tr> + <tr> + <td>Character Display</td> + <td>Correct.</td> + <td>Correct if and only if the font is embedded in the output. (This is possible +because, although the underlying characters are encoded incorrectly, the embedded font is +also encoded incorrectly).</td> + </tr> + </table> + <warning id="cid-keyed-encoding-ttf">As shown in the above table, regardless of +whether the font is embedded or not, text generated from a CID-keyed font metrics file +will <em>never </em>be encoded properly. +Further, if the related font is not embedded, it cannot even be displayed properly. +Obviously, this behavior is not desirable, and we hope to correct it in upcoming releases.</warning> + </section> + <section id="truetype-collections-metrics"> + <title>TrueType Collections Font Metrics</title> + <p>TrueType collections (.ttc files) contain more than one font. +To create metrics files for these fonts, you must specify which font in the collection should be generated, by using the "-ttcname" option with the TTFReader.</p> + <p>To get a list of the fonts in a collection, just start the TTFReader as if it were a normal TrueType file (without the -ttcname option). +It will display all of the font names and exit with an Exception.</p> + <p>Here is an example of generating a metrics file for a .ttc file:</p> + <source>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 -ttcname "MS Mincho" + msmincho.ttc msminch.xml</source> + </section> + <section id="register"> + <title>Register Fonts with FOP</title> + <p>You must tell FOP how to find and use the font metrics files by registering them in the <link href="configuration.html">FOP Configuration</link>. Add entries for your custom fonts, regardless of font type, to the configuration file in a manner similar to the following:</p> + <source><![CDATA[<font metrics-file="FTL_____.xml" kerning="yes" + embed-file="C:\myfonts\FTL_____.pfb"> + <font-triplet name="FrutigerLight" style="normal" weight="normal"/> +</font>]]></source> + <note>Review the documentation for <link href="configuration.html">FOP Configuration</link> for instructions on making the FOP configuration available to FOP when it runs. Otherwise, FOP has no way of finding your custom font information.</note> + <ul> + <li>Starting with FOP version 0.20.5 you can use URLs for the paths to the font files. +Relative URLs are resolved relative to the fontBaseDir property (or baseDir) if available. See <link href="configuration.html">FOP: Configuration</link> for more information.</li> + <li>The "kerning" and "embed-file" attributes are optional. Kerning is currently not used at all. If embedding is off, the output will position the text correctly (from the metrics file), but it will not be displayed or printed correctly unless the viewer has the applicable font available to their local system.</li> + <li>When setting the embed-file attribute for Type 1 fonts, be sure to specify the PFB (actual font data), not PFM (font metrics) file that you used to generate the XML font metrics file.</li> + </ul> + <note>Cocoon users will need to setup the config, see FOPSerializer for more information.</note> + </section> + <section id="embedding"> + <title>Embedding</title> + <note>The PostScript renderer does not yet support font embedding.</note> + <note>The font is simply embedded into the PDF file, it is not converted.</note> + <p>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 adds a prefix to the fontname to ensure that the name 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 subset of the original font, containing only the glyphs used, is embedded in the output document. +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 "-enc 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. +See <link href="#ttf-encoding">Table of TTF Encoding Options</link> for more details.</p> + </section> + </section> + </body> +</document> diff --git a/src/documentation/content/xdocs/0.20.5/graphics.xml b/src/documentation/content/xdocs/0.20.5/graphics.xml new file mode 100644 index 000000000..ea9774405 --- /dev/null +++ b/src/documentation/content/xdocs/0.20.5/graphics.xml @@ -0,0 +1,288 @@ +<?xml version="1.0" standalone="no"?> +<!-- + Copyright 1999-2004 The Apache Software Foundation + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<!-- $Id$ --> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" + "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/core/context/resources/schema/dtd/document-v12.dtd"> +<document> + <header> + <title>FOP: Graphics Formats</title> + <version>$Revision$</version> + </header> + <body> + <section id="support-overview"> + <title>Overview of Graphics Support</title> + <p> + The table below summarizes the <em>theoretical</em> support for graphical formats within FOP. In other words, within the constraints of the limitations listed here, these formats <em>should</em> work. However, many of them have not been tested, and there may be limitations that have not yet been discovered or documented. The packages needed to support some formats are not included in the FOP distribution and must be installed separately. Follow the links in the "Support Thru" column for more details. + </p> + <table> + <tr> + <th>Format</th> + <th>Type</th> + <th>Support Thru</th> + </tr> + <tr> + <td><link href="#bmp">BMP</link> (Microsoft Windows Bitmap)</td> + <td>bitmap</td> + <td><link href="#native">FOP native</link></td> + </tr> + <tr> + <td><link href="#eps">EPS</link> (Encapsulated PostScript)</td> + <td>metafile (both bitmap and vector), probably most frequently used for vector drawings</td> + <td><link href="#native">FOP native</link> (limited support, see restrictions below)</td> + </tr> + <tr> + <td>GIF (Graphics Interchange Format)</td> + <td>bitmap</td> + <td><link href="#native">FOP native</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><link href="#png">PNG</link> (Portable Network Graphic)</td> + <td>bitmap</td> + <td><link href="#jimi">JIMI</link> or <link href="#jai">JAI</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>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> + </tr> + </table> + </section> + <section id="packages"> + <title>Graphics Packages</title> + <section id="native"> + <title>FOP Native</title> + <p> + FOP has native ability to handle some graphic file formats. + </p> + </section> + <section id="jimi"> + <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. + </p> + </section> + <section id="jai"> + <title>JAI (Java Advanced Imaging API)</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. +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> + <section id="batik"> + <title>Batik</title> + <p>Current FOP distributions include a distribution of the Apache Software Foundation's <jump href="http://xml.apache.org/batik">Batik</jump> version 1.5beta4. +It is automatically installed with FOP. +Because Batik's API changes frequently, it is highly recommended that you use the version that ships with FOP, at least when running FOP.</p> + <warning>Batik must be run in a graphical environment.</warning> + <p>Batik must be run in a graphical environment. +It uses AWT classes for rendering SVG, which in turn require an X server on Unixish systems. +If you run a server without X, or if you can't connect to the X server due to security restrictions or policies (a so-called "headless" environment), SVG rendering will fail.</p> + <p>Here are some workarounds:</p> + <ul> + <li>If you are using JDK 1.4, start it with the <code>-Djava.awt.headless=true</code> command line option.</li> + <li>Install an X server which provides an in-memory framebuffer without actually using a screen device or any display hardware. One example is Xvfb.</li> + <li>Install a toolkit which emulates AWT without the need for an underlying X server. One example is the <link href="http://www.eteks.com/pja/en">PJA toolkit</link>, which is free and comes with detailed installation instructions.</li> + </ul> + </section> + </section> + <section id="bmp"> + <title>BMP</title> + <p>FOP native support for BMP images is limited to the RGB color-space.</p> + </section> + <section id="eps"> + <title>EPS</title> + <p>FOP provides support for two output targets:</p> + <ul> + <li>PostScript (full support).</li> + <li> + PDF (partial support). Due to the lack of a built-in PostScript interpreter, FOP + can only embed the EPS file into the PDF. Acrobat Reader will not currently display + the EPS (it doesn't have a PostScript interpreter, either) but it will be shown + correctly when you print the PDF on a PostScript-capable printer. PostScript devices + (including GhostScript) will render the EPS correctly. + </li> + </ul> + <p> + Other output targets can't be supported at the moment because + FOP lacks a PostScript interpreter. + </p> + </section> + <section id="jpeg"> + <title>JPEG</title> + <p>FOP native support of JPEG does not include all variants, especially those containing unusual color lookup tables and color profiles. +If you have trouble with a JPEG image in FOP, try opening it with an image processing program (such as Photoshop or Gimp) and then saving it. +Specifying 24-bit color output may also help. +For the PDF and PostScript renderers most JPEG images can be passed through without decompression. +User reports indicate that grayscale, RGB, and CMYK color-spaces are all rendered properly. + </p> + </section> + <section id="png"> + <title>PNG</title> + <p>If using JAI for PNG support, only RGB and RGBA color-spaces are supported for FOP rendering.</p> + </section> + <section id="svg"> + <title>SVG</title> + <section id="svg-intro"> + <title>Introduction</title> + <p>FOP uses <link href="#batik">Batik</link> for SVG support. +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>.</p> + <note> +Batik's SVG Rasterizer utility may also be used to convert standalone SVG +documents into PDF. For more information please see the +<link href="http://xml.apache.org/batik/svgrasterizer.html">SVG Rasterizer documentation</link> +on the Batik site. + </note> + </section> + <section id="svg-pdf-graphics"> + <title>Placing SVG Graphics into PDF</title> + <p> +The SVG is rendered 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. +We hope to improve this in the future.</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 id="svg-pdf-text"> + <title>Placing SVG Text into PDF</title> + <p>If possible, Batik will use normal PDF text when inserting text. It does +this by checking if the text can be drawn normally and the font is +supported. This example svg <link href="dev/svg/text.svg">text.svg</link> / +<!--link href="dev/svg/text.pdf"-->text.pdf<!--/link--> +shows how various types and effects with text are handled. +Note that tspan and outlined text are not yet implemented.</p> + <p> +Otherwise, text is converted and drawn as a set of shapes by batik, using the stroking text painter. +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> +For PDF output, there is a <link href="configuration.html#svg-strokeSVGText">configuration option to force SVG text to be rendered as text</link>. +The drawback to this approach is that it is effective only for available fonts (including embedded fonts). +Font sizes are rounded to the next integer point size. +This will be improved in the future. + </p> + <p>Note that because SVG text can be rendered as either text or a vector graphic, you may need to consider settings in your viewer for both. +The Acrobat viewer has both "smooth line art" and "smooth text" settings that may need to be set for SVG images to be displayed nicely on your screen (see Edit / Preferences / Display). +This setting will not affect the printing of your document, which should be OK in any case, but will only affect the quality of the screen display.</p> + </section> + <section id="svg-scaling"> + <title>Scaling</title> + <p>Currently, SVG images are rendered with the dimensions specified <em>in the SVG file</em>, within the viewport specified in the fo:external-graphic element. +For everything to work properly, the two should be equal. +The SVG standard leaves this issue as an implementation detail. +FOP will probably implement a scaling mechanism in the future.</p> + </section> + <section id="svg-problems"> + <title>Known Problems</title> + <ul> + <li> +soft mask transparency is combined with white so that it looks better +on pdf 1.3 viewers but this causes the soft mask to be slightly lighter +or darker on pdf 1.4 viewers + </li> + <li> +there is some problem with a gradient inside a pattern causing a pdf +error when viewed in acrobat 5 + </li> + <li> +text is not always handled correctly, it may select the wrong font +especially if characters have multiple fonts in the font list + </li> + <li> +more pdf text handling could be implemented +It could draw the string using the attributed character iterator +to handle tspans and other simple changes of text. + </li> + <li> +JPEG images are not inserted directly into the pdf document +This area has not been implemented yet since the appropriate +method in batik is static + </li> + <li> +Uniform transparency for images and other svg elements that are converted +into a raster graphic are not drawn properly in PDF. The image is opaque. + </li> + </ul> + </section> + </section> + <section id="tiff"> + <title>TIFF</title> + <p>FOP-native TIFF support is limited to PDF and PostScript output only. Also, according to user reports, FOP's native support for TIFF is limited to images with the following characteristics (all must be true for successful rendering):</p> + <ul> + <li>single channel images (i.e., bi-level and grayscale only)</li> + <li>uncompressed images, or images using CCITT T.4, CCITT T.6, or JPEG compression</li> + <li>images using white-is-zero encoding in the TIFF PhotometricInterpretation tag</li> + </ul> + <p><em>JAI:</em> Supports RGB and RGBA only for FOP rendering.</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> + <ul> + <li>If no dimensions are given, FOP uses a default value of 72 dpi to compute the graphic's dimensions. For example, suppose a graphic 300 pixels wide and 400 pixels high. FOP will render the graphic at 4.167 inches wide, 5.555 inches high, with an apparent resolution of 72 dpi.</li> + <li>If only one dimension is given, FOP by default uses the same aspect ratio to compute the other dimension (to avoid the appearance of stretching). For example, suppose a graphic 300 pixels wide and 400 pixels high, for which content-width = ".5in". FOP will compute the content-height = .667 inches, and will render the graphic at that size, with an apparent resolution of 600 dpi.</li> + <li>If both dimensions are given, FOP simply renders the image in that space. For example, suppose a graphic 300 pixels wide and 400 pixels high, for which content-width = "3in" and content-height = "4in". FOP will render the graphic at that size, with an apparent resolution of 100 dpi.</li> + </ul> + <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> diff --git a/src/documentation/content/xdocs/0.20.5/hyphenation.xml b/src/documentation/content/xdocs/0.20.5/hyphenation.xml new file mode 100644 index 000000000..db82c6362 --- /dev/null +++ b/src/documentation/content/xdocs/0.20.5/hyphenation.xml @@ -0,0 +1,237 @@ +<?xml version="1.0" standalone="no"?> +<!-- + Copyright 1999-2004 The Apache Software Foundation + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<!-- $Id$ --> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" + "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/core/context/resources/schema/dtd/document-v12.dtd"> +<document> + <header> + <title>FOP: Hyphenation</title> + <version>$Revision$</version> + </header> + <body> + <section id="support"> + <title>Hyphenation Support</title> + <section id="intro"> + <title>Introduction</title> + <p>FOP uses Liang's hyphenation algorithm, well known from TeX. It needs + language specific pattern and other data for operation.</p> + <p>Because of <link href="#license-issues">licensing issues</link> (and for + convenience), all hyphenation patterns for FOP are made available through + the <fork href="http://offo.sourceforge.net/hyphenation/index.html">Objects For + Formatting Objects</fork> project.</p> + <note>If you have made improvements to an existing FOP hyphenation pattern, + or if you have created one from scratch, please consider contributing these + to OFFO so that they can benefit other FOP users as well. + Please inquire on the <link href="maillist.html#fop-user">FOP User + mailing list</link>.</note> + </section> + <section id="license-issues"> + <title>License Issues</title> + <p>Many of the hyphenation files distributed with TeX and its offspring are + licenced under the <fork href="http://www.latex-project.org/lppl.html">LaTeX + Project Public License (LPPL)</fork>, which prevents them from being + distributed with Apache software. The LPPL puts restrictions on file names + in redistributed derived works which we feel can't guarantee. Some + hyphenation pattern files have other or additional restrictions, for + example against use for commercial purposes.</p> + <p>Although Apache FOP cannot redistribute hyphenation pattern files that do + not conform with its license scheme, that does not necessarily prevent users + from using such hyphenation patterns with FOP. However, it does place on + the user the responsibility for determining whether the user can rightly use + such hyphenation patterns under the hyphenation pattern license.</p> + <warning>The user is responsible to settle license issues for hyphenation + pattern files that are obtained from non-Apache sources.</warning> + </section> + <section id="sources"> + <title>Sources of Custom Hyphenation Pattern Files</title> + <p>The most important source of hyphenation pattern files is the + <fork href="http://www.ctan.org/tex-archive/language/hyphenation/">CTAN TeX + Archive</fork>.</p> + </section> + <section id="install"> + <title>Installing Custom Hyphenation Patterns</title> + <p>To install a custom hyphenation pattern for use with FOP:</p> + <ol> + <li>Convert the TeX hyphenation pattern file to the FOP format. The FOP + format is an xml file conforming to the DTD found at + <code>{fop-dir}/hyph/hyphenation.dtd</code>.</li> + <li>Name this new file following this schema: + <code>languageCode_countryCode.xml</code>. The country code is + optional, and should be used only if needed. For example: + <ul> + <li><code>en_US.xml</code> would be the file name for American + English hyphenation patterns.</li> + <li><code>it.xml</code> would be the file name for Italian + hyphenation patterns.</li> + </ul> + The language and country codes must match the XSL-FO input, which + follows <link href="http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt">ISO + 639</link> (languages) and <link href="http://www.ics.uci.edu/pub/ietf/http/related/iso3166.txt">ISO + 3166</link> (countries). NOTE: The ISO 639/ISO 3166 convention is that + language names are written in lower case, while country codes are written + in upper case. FOP does not check whether the language and country specified + in the FO source are actually from the current standard, but it relies + on it being two letter strings in a few places. So you can make up your + own codes for custom hyphenation patterns, but they should be two + letter strings too (patches for proper handling extensions are welcome)</li> + <li>There are basically three ways to make the FOP-compatible hyphenation pattern + file(s) accessible to FOP: + <ul> + <li>Download the precompiled JAR from <fork href="http://offo.sourceforge.net/hyphenation/index.html">OFFO + </fork> and place it either in the <code>{fop-dir}/lib</code> directory, or + in a directory of your choice (and append the full path to the JAR to + the environment variable <code>FOP_HYPHENATION_PATH</code>).</li> + <li>Download the desired FOP-compatible hyphenation pattern file(s) from + <fork href="http://offo.sourceforge.net/hyphenation/index.html">OFFO</fork>, + and/or take your self created hyphenation pattern file(s), + <ul> + <li>place them in the directory <code>{fop-dir}/hyph</code>, </li> + <li>or place them in a directory of your choice and set the Ant variable + <code>user.hyph.dir</code> to point to that directory (in + <code>build-local.properties</code>),</li> + </ul> + and run Ant with build target + <code>jar-hyphenation</code>. This will create a JAR containing the + compiled patterns in <code>{fop-dir}/build</code> that will be added to the + classpath on the next run. + (When FOP is built from scratch, and there are pattern source file(s) + present in the directory pointed to by the + <code>user.hyph.dir</code> variable, this JAR will automatically + be created from the supplied pattern(s)).</li> + <li>Put the pattern source file(s) into a directory of your choice and + configure FOP to look for custom patterns in this directory, by setting the + <link href="configuration.html#hyphenation-dir"><hyphenation-dir></link> + configuration option.</li> + </ul> + </li> + </ol> + <warning> + Either of these three options will ensure hyphenation is working when using + FOP from the command-line. If FOP is being embedded, remember to add the location(s) + of the hyphenation JAR(s) to the CLASSPATH (option 1 and 2) or to set the + <link href="configuration.html#hyphenation-dir"><hyphenation-dir></link> + configuration option programmatically (option 3). + </warning> + </section> + </section> + <section id="patterns"> + <title>Hyphenation Patterns</title> + <p>If you would like to build your own hyphenation pattern files, or modify + existing ones, this section will help you understand how to do so. Even + when creating a pattern file from scratch, it may be beneficial to start + with an existing file and modify it. See <fork href="http://offo.sourceforge.net/hyphenation/index.html"> + OFFO's Hyphenation page</fork> for examples. + Here is a brief explanation of the contents of FOP's hyphenation patterns:</p> + <warning>The remaining content of this section should be considered "draft" + quality. It was drafted from theoretical literature, and has not been + tested against actual FOP behavior. It may contain errors or omissions. + Do not rely on these instructions without testing everything stated here. + If you use these instructions, please provide feedback on the + <link href="maillist.html#fop-user">FOP User mailing list</link>, either + confirming their accuracy, or raising specific problems that we can + address.</warning> + <ul> + <li>The root of the pattern file is the <hyphenation-info> element.</li> + <li><hyphen-char>: its attribute "value" contains the character signalling + a hyphen in the <exceptions> section. It has nothing to do with the + hyphenation character used in FOP, use the XSLFO hyphenation-character + property for defining the hyphenation character there. At some points + a dash U+002D is hardwired in the code, so you'd better use this too + (patches to rectify the situation are welcome). There is no default, + if you declare exceptions with hyphenations, you must declare the + hyphen-char too.</li> + <li><hyphen-min> contains two attributes: + <ul> + <li>before: the minimum number of characters in a word allowed to exist + on a line immediately preceding a hyphenated word-break.</li> + <li>after: the minimum number of characters in a word allowed to exist + on a line immediately after a hyphenated word-break.</li> + </ul> + This element is unused and not even read. It should be considered a + documentation for parameters used during pattern generation. + </li> + <li><classes> contains whitespace-separated character sets. The members + of each set should be treated as equivalent for purposes of hyphenation, + usually upper and lower case of the same character. The first character + of the set is the canonical character, the patterns and exceptions + should only contain these canonical representation characters (except + digits for weight, the period (.) as word delimiter in the patterns and + the hyphen char in exceptions, of course).</li> + <li><exceptions> contains whitespace-separated words, each of which + has either explicit hyphen characters to denote acceptable breakage + points, or no hyphen characters, to indicate that this word should + never be hyphenated, or contain explicit <hyp> elements for specifying + changes of spelling due to hyphenation (like backen -> bak-ken or + Stoffarbe -> Stoff-farbe in the old german spelling). Exceptions override + the patterns described below. Explicit <hyp> declarations don't work + yet (patches welcome). Exceptions are generally a bit brittle, test + carefully.</li> + <li><patterns> includes whitespace-separated patterns, which are what + drive most hyphenation decisions. The characters in these patterns are + explained as follows: + <ul> + <li>non-numeric characters represent characters in a sub-word to be + evaluated</li> + <li>the period character (.) represents a word boundary, i.e. either + the beginning or ending of a word</li> + <li>numeric characters represent a scoring system for indicating the + acceptability of a hyphen in this location. Odd numbers represent an + acceptable location for a hyphen, with higher values overriding lower + inhibiting values. Even numbers indicate an unacceptable location, with + higher values overriding lower values indicating an acceptable position. + A value of zero (inhibiting) is implied when there is no number present. + Generally patterns are constructed so that valuse greater than 4 are rare. + Due to a bug currently patterns with values of 8 and greater don't + have an effect, so don't wonder.</li> + </ul> + Here are some examples from the English patterns file: + <ul> + <li>Knuth (<em>The TeXBook</em>, Appendix H) uses the example <strong>hach4</strong>, which indicates that it is extremely undesirable to place a hyphen after the substring "hach", for example in the word "toothach-es".</li> + <li><strong>.leg5e</strong> indicates that "leg-e", when it occurs at the beginning of a word, is a very good place to place a hyphen, if one is needed. Words like "leg-end" and "leg-er-de-main" fit this pattern.</li> + </ul> + Note that the algorithm that uses this data searches for each of the word's substrings in the patterns, and chooses the <em>highest</em> value found for letter combination. + </li> + </ul> + <p>If you want to convert a TeX hyphenation pattern file, you have to undo + the TeX encoding for non-ASCII text. FOP uses Unicode, and the patterns + must be proper Unicode too. You should be aware of the XML encoding issues, + preferably use a good Unicode editor.</p> + <p>Note that FOP does not do Unicode character normalization. If you use + combining chars for accents and other character decorations, you must + declare character classes for them, and use the same sequence of base character + and combining marks in the XSLFO source, otherwise the pattern wouldn't match. + Fortunately, Unicode provides precomposed characters for all important cases + in common languages, until now nobody run seriously into this issue. Some dead + languages and dialects, especially ancient ones, may pose a real problem + though.</p> + <p>If you want to generate your own patterns, an open-source utility called + patgen is available on many Unix/Linux distributions and every TeX + distribution which can be used to assist in + creating pattern files from dictionaries. Pattern creation for languages like + english or german is an art. If you can, read Frank Liang's original paper + "Word Hy-phen-a-tion by Com-pu-ter" (yes, with hyphens). It is not available + online. The original patgen.web source, included in the TeX source distributions, + contains valuable comments, unfortunately technical details obscure often the + high level issues. Another important source is + <fork href="http://www.ctan.org/tex-archive/systems/knuth/tex/texbook.tex">The + TeX Book</fork>, appendix H (either read the TeX source, or run it through + TeX to typeset it). Secondary articles, for example the works by Petr Sojka, + may alos give some much needed insigth into problems arising in automated + hyphenation.</p> + </section> + </body> +</document> diff --git a/src/documentation/content/xdocs/0.20.5/index.xml b/src/documentation/content/xdocs/0.20.5/index.xml new file mode 100644 index 000000000..d05e8704b --- /dev/null +++ b/src/documentation/content/xdocs/0.20.5/index.xml @@ -0,0 +1,30 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + Copyright 1999-2005 The Apache Software Foundation + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<!-- $Id$ --> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.3//EN" "http://forrest.apache.org/dtd/document-v13.dtd"> +<document> + <header> + <title>Apache FOP Version 0.20.5</title> + <version>$Revision: 201586 $</version> + </header> + <body> + <section id="intro"> + <title>Introduction</title> + <p>These pages contain information that should be helpful for those </p> + </section> + </body> +</document> diff --git a/src/documentation/content/xdocs/0.20.5/output.xml b/src/documentation/content/xdocs/0.20.5/output.xml new file mode 100644 index 000000000..0e4da30b8 --- /dev/null +++ b/src/documentation/content/xdocs/0.20.5/output.xml @@ -0,0 +1,324 @@ +<?xml version="1.0" standalone="no"?> +<!-- + Copyright 1999-2004 The Apache Software Foundation + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<!-- $Id$ --> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" + "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/core/context/resources/schema/dtd/document-v12.dtd"> + +<!-- Output Formats: Renderers --> +<document> + <header> + <title>FOP Output Options</title> + <version>$Revision$</version> + <authors> + <person name="Keiron Liddle" email="keiron@aftexsw.com"/> + <person name="Art Welch" email=""/> + </authors> + </header> + + <body> + <p> +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> +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> + <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> +Here are Windows command-line examples for Postscript and PCL: + </p> + <source><![CDATA[fop ... -ps \\computername\printer]]></source> + <source><![CDATA[fop ... -pcl \\computername\printer]]></source> + <p> +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> + <p> +Set the OutputStream (out) to the PCLRenderer and it happily sends the +PCL to the UNIX printer queue. + </p> + </section> +</section> +<section id="pdf"> + <title>PDF</title> + <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 +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> + <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: + +<em>"PDF prescribes a set of 14 standard fonts that can be used without prior +definition. +These include four faces each of three Latin text typefaces (Courier, +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 id="pcl"> + <title>PCL</title> + <p> +This format is for the Hewlett-Packard PCL printers. +It should produce output as close to identical as possible to the +printed output of the PDFRenderer within the limitations of the +renderer, and output device. + </p> + <p> +The output created by the PCLRenderer is generic PCL 5 as documented +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 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> + <li>The Helvetica and Times fonts are not well supported among PCL printers so Helvetica is mapped to Arial and Times is mapped to Times New. This is done in the PCLRenderer, no changes are required in the FO's. The metrics and appearance for Helvetica/Arial and Times/Times New are nearly identical, so this has not been a problem so far.</li> + <li>Only the original fonts built into FOP are supported.</li> + <li>For the non-symbol fonts, the ISO 8859/1 symbol set is used (PCL set "0N").</li> + <li>Multibyte characters are not supported.</li> + <li>SVG is not supported.</li> + <li>Images print black and white only (not dithered). When the renderer prints a color image it uses a threshold value, colors above the threshold are printed as white and below are black. If you need to print a non-monochrome image you should dither it first.</li> + <li>Image scaling is accomplished by modifying the effective resolution of the image data. The available resolutions are 75, 100, 150, 300, and 600 DPI.</li> + <li>Color printing is not supported. Colors are rendered by mapping the color intensity to one of the PCL fill shades (from white to black in 9 steps).</li> + </ul> + </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> + + <dl> + <dt>orientation</dt> + <dd>The logical page orientation is controlled by the public orientation variable. Legal values are: + <!--ul> + <li>0 Portrait</li> + <li>1 Landscape</li> + <li>2 Reverse Portrait</li> + <li>3 Reverse Landscape</li> + </ul--> + </dd> + <dt>curdiv, paperheight</dt> + <dd>The curdiv and paperheight variables allow multiple virtual pages to be printed on a piece of paper. This allows a standard laser printer to use perforated paper where every perforation will represent an individual page. The paperheight sets the height of a piece of paper in decipoints. This will be divided by the page.getHeight() to determine the number of equal sized divisions (pages) that will fit on the paper. The curdiv variable may be read/written to get/set the current division on the page (to set the starting division and read the ending division for multiple invocations).</dd> + <dt>topmargin, leftmargin</dt> + <dd>The topmargin and leftmargin may be used to increase the top and left margins for printing.</dd> + </dl> + </section> +</section> +<section id="ps"> + <title>PostScript</title> + <p> +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> + <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> + <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> + </section> +</section> +<section id="rtf"> + <title>RTF</title> + <p> +This is currently not integrated with FOP but it will soon. +This will create an rtf (rich text format) document that will +attempt to contain as much information from the fo document as +possible. + </p> +</section> +<section id="svg"> + <title>SVG</title> + <p> +This format creates an SVG document that has links between the pages. +This is primarily for slides and creating svg images of pages. +Large documents will create SVG files that are far too large for +and SVG viewer to handle. Since fo documents usually have text the +SVG document will have a large number of text elements. +The font information for the text is obtained from the jvm in the +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 id="xml"> + <title>XML</title> + <p> +This is for testing and verification. The XML created is simply +a representation of the internal area tree put into XML. It does +not perform any other purpose. + </p> +</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 id="awt"> + <title>AWT</title> + <p> +The AWT viewer shows a window with the pages displayed inside a +java graphic. It displays one page at a time. +The fonts used for the formatting and viewing depend on the fonts +available to your JRE. + </p> +</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 id="txt"> + <title>TXT</title> + <p> +The text renderer produces plain ASCII text output +that attempts to match the output of the PDFRenderer as closely as +possible. This was originally developed to accommodate an archive system +that could only accept plain text files, and is primarily useful for getting +a quick-and-dirty view of the document text. The renderer is very limited, +so do not be surprised if it gives unsatisfactory results. + </p> + <p> +The Text renderer works with a fixed size page buffer. The size of this +buffer is controlled with the textCPI and textLPI public variables. +The textCPI is the effective horizontal characters per inch to use. +The textLPI is the vertical lines per inch to use. From these values +and the page width and height the size of the buffer is calculated. +The formatting objects to be rendered are then mapped to this grid. +Graphic elements (lines, borders, etc) are assigned a lower priority +than text, so text will overwrite any graphic element representations. + </p> + <p>Because FOP lays the text onto a grid during layout, there are frequently extra or missing spaces between characters and lines, which is generally unsatisfactory. +Users have reported that the optimal settings to avoid such spacing problems are:</p> + <ul> + <li>font-family="Courier"</li> + <li>font-size="7.3pt"</li> + <li>line-height="10.5pt"</li> + </ul> +</section> + + </body> +</document> + diff --git a/src/documentation/content/xdocs/0.20.5/pdfencryption.xml b/src/documentation/content/xdocs/0.20.5/pdfencryption.xml new file mode 100755 index 000000000..1921b97a9 --- /dev/null +++ b/src/documentation/content/xdocs/0.20.5/pdfencryption.xml @@ -0,0 +1,209 @@ +<?xml version="1.0" standalone="no"?> +<!-- + Copyright 1999-2004 The Apache Software Foundation + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<!-- $Id$ --> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" + "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/core/context/resources/schema/dtd/document-v12.dtd"> + +<document> + <header> + <title>PDF encryption.</title> + <version>$Revision$</version> + <authors> + <person name="J.Pietschmann" email="pietsch@apache.org"/> + <person name="Jeremias Märki" email="jeremias@apache.org"/> + </authors> + </header> + <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 viewing, printing, editing, copying text from the + document and doing annotations. It is also possible to ask the + user for a password in order to view the contents. Note that + there already exist third party applications which can decrypt + an encrypted PDF without effort and allow the aforementioned + operations, therefore the degree of protection is limited. + </p> + <p> + For further information about features and restrictions regarding PDF + encryption, look at the documentation coming with Adobe Acrobat or the + technical documentation on the Adobe web site. + </p> + </section> + <section> + <title>Usage (command line)</title> + <p> + Encryption is enabled by supplying any of the encryption related + options. + </p> + <p> + An owner password is set with the <code>-o</code> option. This + password is actually used as encryption key. Many tools for + PDF processing ask for this password to disregard any + restriction imposed on the PDF document. + </p> + <p> + If no owner password has been supplied but FOP was asked to apply some + restrictions, a random password is used. In this case it is obviously + impossiible to disregard restrictions in PDF processing tools. + </p> + <p> + A user password, supplied with the <code>-u</code> option, will + cause the PDF display software to ask the reader for this password in + order to view the contents of the document. If no user password was + supplied, viewing the content is not restricted. + </p> + <p> + Further restrictions can be imposed by using the <code>-noprint</code>, + <code>-nocopy</code>, <code>-noedit</code> and + <code>-noannotations</code> options, which disable printing, copying + text, editing in Adobe Acrobat and making annotations, respectively. + </p> + </section> + <section> + <title>Usage (embedded)</title> + <p> + When FOP is embedded in another Java application you need to set an + options map on the renderer. These are the supported options: + </p> + <table> + <tr> + <th>Option</th> + <th>Description</th> + <th>Values</th> + <th>Default</th> + </tr> + <tr> + <td>ownerPassword</td> + <td>The owner password</td> + <td>String</td> + <td/> + </tr> + <tr> + <td>userPassword</td> + <td>The user password</td> + <td>String</td> + <td/> + </tr> + <tr> + <td>allowPrint</td> + <td>Allows/disallows printing of the PDF</td> + <td>"TRUE" or "FALSE"</td> + <td>"TRUE"</td> + </tr> + <tr> + <td>allowCopyContent</td> + <td>Allows/disallows copy/paste of content</td> + <td>"TRUE" or "FALSE"</td> + <td>"TRUE"</td> + </tr> + <tr> + <td>allowEditContent</td> + <td>Allows/disallows editing of content</td> + <td>"TRUE" or "FALSE"</td> + <td>"TRUE"</td> + </tr> + <tr> + <td>allowEditAnnotations</td> + <td>Allows/disallows editing of annotations</td> + <td>"TRUE" or "FALSE"</td> + <td>"TRUE"</td> + </tr> + </table> + <note> + Encryption is enabled as soon as one of these options is set. + </note> + <p> + An example to enable PDF encryption in Java code: + </p> + <source><![CDATA[ +Driver driver = new Driver(); +driver.setRenderer(Driver.RENDER_PDF); +Map rendererOptions = new java.util.HashMap(); +rendererOptions.put("ownerPassword", "mypassword"); +rendererOptions.put("allowCopyContent", "FALSE"); +rendererOptions.put("allowEditContent", "FALSE"); +rendererOptions.put("allowPrint", "FALSE"); +driver.getRenderer().setOptions(rendererOptions); +driver.setOutputStream(...]]></source> + </section> + <section> + <title>Environment</title> + <p> + In order to use PDF encryption, FOP has to be compiled with + cryptography support. Currently, only <link + href="http://java.sun.com/j2se/1.4/docs/guide/security/jce/JCERefGuide.html">JCE</link> + is supported. JCE is part of JDK 1.4. For earlier JDKs, it can + be installed separately. The build process automatically + detects JCE presence and installs PDF encryption support if + possible, otherwise a stub is compiled in. + </p> + <p> + Cryptography support must also be present at run time. In particular, a + provider for the RC4 cipher is needed. Unfortunately, the sample JCE + provider in Sun's JDK 1.4 does <strong>not</strong> provide RC4. If you + get a message saying + </p> + <source>"Cannot find any provider supporting RC4"</source> + <p> + then you don't have the needed infrastructure. + </p> + <p> + There are several commercial and a few Open Source packages which + provide RC4. A pure Java implementation is produced by <link + href="http://www.bouncycastle.org/">The Legion of the Bouncy + Castle</link>. <link + href="http://www.mozilla.org/projects/security/pki/jss/">Mozilla + JSS</link> is an interface to a native implementation. + </p> + </section> + <section id="install_crypto"> + <title>Installing a crypto provider</title> + <p> + The pure Java implementation from <link + href="http://www.bouncycastle.org/">Bouncy Castle</link> is easy to + install. + </p> + <ol> + <li> + Download the binary distribution for your JDK version. If you have JDK + 1.3 or earlier you must also download a JCE from the same page. + </li> + <li> + Unpack the distribution. Add the jar file to your classpath. A + convenient way to use the jar on Linux is to simply drop it into the + FOP lib directory, it will be automatically picked up by + <code>fop.sh</code>. If you have JDK 1.3 or earlier don't forget to + install the JCE as well. + </li> + <li> + Open the <code>java.security</code> file and add<br/> + <code>security.provider.6=org.bouncycastle.jce.provider.BouncyCastleProvider</code>,<br/> + preferably at the end of the block defining the other crypto + providers. For JDK 1.4 this is detailed on <link href="http://java.sun.com/j2se/1.4/docs/guide/security/jce/JCERefGuide.html#InstallProvider">Sun's web site</link>. + </li> + </ol> + <p> + If you have any experience with Mozilla JSS or any other + cryptography provider, please post it to the fop-user list. + </p> + </section> + </body> +</document> diff --git a/src/documentation/content/xdocs/0.20.5/running.xml b/src/documentation/content/xdocs/0.20.5/running.xml new file mode 100644 index 000000000..549444928 --- /dev/null +++ b/src/documentation/content/xdocs/0.20.5/running.xml @@ -0,0 +1,189 @@ +<?xml version="1.0" standalone="no"?> +<!-- + Copyright 1999-2004 The Apache Software Foundation + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<!-- $Id$ --> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" + "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/core/context/resources/schema/dtd/document-v12.dtd"> + +<document> + <header> + <title>Running FOP</title> + <version>$Revision$</version> + </header> + + <body> + <section id="require"> + <title>System Requirements</title> + <p>The following software must be installed:</p> + <ul> + <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 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 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] <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 + -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 + 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 could be replaced by PDF bookmarks instead or moved to the end of the document (reshuffle the paper could 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. +If FOP is running embedded, clearing the image from time to time cache might prevent memory exhaustion, you can call +<code>org.apache.fop.image.FopImageFactory.resetCache()</code> to empty the +<jump href="graphics.html#caching">image cache</jump>. + </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 is freed after the page sequence has been rendered. +This can be substantial if the page sequence contains lots of FO elements. + </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> diff --git a/src/documentation/content/xdocs/0.20.5/servlets.xml b/src/documentation/content/xdocs/0.20.5/servlets.xml new file mode 100644 index 000000000..89ce0b848 --- /dev/null +++ b/src/documentation/content/xdocs/0.20.5/servlets.xml @@ -0,0 +1,263 @@ +<?xml version="1.0" standalone="no"?> +<!-- + Copyright 1999-2004 The Apache Software Foundation + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<!-- $Id$ --> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" + "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/core/context/resources/schema/dtd/document-v12.dtd"> +<document> + <header> + <title>Servlets</title> + <subtitle>How to use FOP in a Servlet</subtitle> + <version>$Revision$</version> + </header> + <body> + <section id="overview"> + <title>Overview</title> + <p> + This page discusses topic all around using FOP in a servlet environment. + </p> + </section> + <section id="example-servlets"> + <title>Example Servlets in the FOP distribution</title> + <p> + In the directory {fop-dir}/examples/servlet, you'll find a working example + of a FOP-enabled servlet. + </p> + <p> + You can build the servlet easily by using the supplied Ant script. After building + the servlet, drop fop.war into the webapps directory of Tomcat. Then, you can use + URLs like the following to generate PDF files: + </p> + <ul> + <li>http://localhost:8080/fop/fop?fo=/home/path/to/fofile.fo</li> + <li>http://localhost:8080/fop/fop?xml=/home/path/to/xmlfile.xml&xsl=/home/path/to/xslfile.xsl</li> + </ul> + <p/> + <p>The source code for the servlet can be found under {fop-dir}/examples/servlet/src/FopServlet.java.</p> + </section> + <section id="servlet"> + <title>Create your own Servlet</title> + <note> + This section assumes you are familiar with <link href="embedding.html">embedding FOP</link>. + </note> + <section id="minimal-servlet"> + <title>A minimal Servlet</title> + <p> + Here is a minimal code snippet to demonstrate the basics: + </p> + <source>public void doGet(HttpServletRequest request, + HttpServletResponse response) throws ServletException { + try { + response.setContentType("application/pdf"); + Driver driver = new Driver(new InputSource("foo.fo"), + response.getOutputStream()); + driver.setRenderer(Driver.RENDER_PDF); + driver.run(); + } catch (Exception ex) { + throw new ServletException(ex); + } +}</source> + <note> + There are numerous problems with the code snippet above. + Its purpose is only to demonstrate the basic concepts. + See below for details. + </note> + </section> + <section id="xslt"> + <title>Adding XSL tranformation (XSLT)</title> + <p> + A common requirement is the to transform an XML source to + XSLFO using an XSL transformation. It is recommended to use + JAXP for this task. The following snippet shows the basic + code: + </p> + <source> +protected Logger log; +protected TransformerFactory transformerFactory; + +public void init() throws ServletException { + this.log = new SimpleLog(SimpleLog.LOG_LEVEL_WARN); + this.transformerFactory = TransformerFactory.newInstance(); +} + +[..] + + //Setup FOP + Driver driver = new Driver(); + driver.setLogger(this.log); + driver.setRenderer(Driver.RENDER_PDF); + + //Setup a buffer to obtain the content length + ByteArrayOutputStream out = new ByteArrayOutputStream(); + driver.setOutputStream(out); + + //Setup Transformer + Source xsltSrc = new StreamSource(new File("foo-xml2fo.xsl")); + Transformer transformer = this.transformerFactory.newTransformer(xsltSrc); + + //Make sure the XSL transformation's result is piped through to FOP + Result res = new SAXResult(driver.getContentHandler()); + + //Setup input + Source src = new StreamSource(new File("foo.xml")); + + //Start the transformation and rendering process + transformer.transform(src, res); + + //Prepare response + response.setContentType("application/pdf"); + response.setContentLength(out.size()); + + //Send content to Browser + response.getOutputStream().write(out.toByteArray()); + response.getOutputStream().flush();</source> + <note> + Buffering the generated PDF in a ByteArrayOutputStream is done to avoid potential + problems with the Acrobat Reader Plug-in in IEx. + </note> + <p> + The <code>Source</code> instance used above is simply an + example. 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 <code>Transformer</code> object, you can also use it to + explicitly set parameters for the transformation run. + </p> + </section> + <section id="cfg"> + <title>Custom configuration</title> + <p> + If you need to supply a special configuration do this in the <code>init()</code> + method so it will only be done once and to avoid multithreading problems. + </p> + <source>public void init() throws ServletException { + [..] + new Options(new File("userconfig.xml")); + //or + Configuration.put("baseDir", "/my/base/dir"); +}</source> + </section> + <section id="performance"> + <title>Improving performance</title> + <p> + There are several options to consider: + </p> + <ul> + <li> + Instead of java.io.ByteArrayOutputStream consider using the ByteArrayOutputStream + implementation from the Jakarta Commons IO project which allocates less memory. + </li> + <li> + In certain cases it can help to write the generated PDF to a temporary file so + you can quickly reuse the file. This is especially useful, if Internet Explorer + calls the servlet multiple times with the same request or if you often generate + equal PDFs. + </li> + </ul> + <p> + Of course, the + <link href="embedding.html#performance">performance hints from the Embedding page</link> + apply here, too. + </p> + </section> + </section> + <section id="ie"> + <title>Notes on Microsoft Internet Explorer</title> + <p> + Some versions of Internet Explorer will not automatically show the PDF or call the servlet multiple times. + These are well-known limitations of Internet Explorer and are not a problem of the servlet. + However, Internet Explorer can still be used to download the PDF so that it can be viewed later. + Here are some suggestions in this context: + </p> + <ul> + <li> + Use an URL ending in <code>.pdf</code>, like + <code>http://myserver/servlet/stuff.pdf</code>. Yes, the servlet can + be configured to handle this. If the URL has to contain parameters, + try to have <strong>both</strong> the base URL as well as the last parameter end in + <code>.pdf</code>, if necessary append a dummy parameter, like + <code>http://myserver/servlet/stuff.pdf?par1=a&par2=b&d=.pdf</code>. The + effect may depend on IEx version. + </li> + <li> + Give IEx the opportunity to cache. In particular, ensure the + server does not set any headers causing IEx not to cache the + content. This may be a real problem if the document is sent + over HTTPS, because most IEx installations will by default + <em>not</em> cache any content retrieved over HTTPS. + Setting the <code>Expires</code> header entry may help in + this case:<br/> <code>response.setDateHeader("Expires", + System.currentTimeMillis() + cacheExpiringDuration * + 1000);</code><br/> Consult your server manual and the + relevant RFCs for further details on HTTP headers and + caching. + </li> + <li> + Cache in the server. It may help to include a parameter in + the URL which has a timestamp as the value min order to + decide whether a request is repeated. IEx is reported to + retrieve a document up to three times, but never more often. + </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="complex-usecases"> + <title>Handling complex use cases</title> + <p> + Sometimes the requirements for a servlet get quite sophisticated: SQL data sources, + multiple XSL transformations, merging of several datasources etc. In such a case + consider using <fork href="http://cocoon.apache.org">Apache Cocoon</fork> instead + of a custom servlet to accomplish your goal. + </p> + </section> + </body> +</document> +<!-- Last Line of $RCSfile$ --> |