diff options
Diffstat (limited to 'src/documentation/content/xdocs/1.0/upgrading.xml')
| -rw-r--r-- | src/documentation/content/xdocs/1.0/upgrading.xml | 128 |
1 files changed, 128 insertions, 0 deletions
diff --git a/src/documentation/content/xdocs/1.0/upgrading.xml b/src/documentation/content/xdocs/1.0/upgrading.xml new file mode 100644 index 000000000..9f5879174 --- /dev/null +++ b/src/documentation/content/xdocs/1.0/upgrading.xml @@ -0,0 +1,128 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You 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 V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd"> +<document> + <header> + <title>Upgrading from an Earlier Version of Apache FOP</title> + <version>$Revision$</version> + </header> + <body> + <section id="important"> + <title>Important!</title> + <p> + If you're planning to upgrade to the latest FOP version there are a few very important things + to consider: + </p> + <ul> + <li> + More than half of the codebase has been rewritten over the + last three years. With version 0.93 the code has reached + <strong>production level</strong>, and continues to improve with + version 0.94. + </li> + <li> + The API of FOP has changed considerably and is not + backwards-compatible with versions 0.20.5 and + 0.91beta. Version 0.92 introduced the <strong>new stable + API</strong>. + </li> + <li> + Since version 0.92 some deprecated methods which were part + of the old API have been removed. If you upgrade from 0.91 + beta, you will need to adjust your Java code. Similarly if + you upgrade from 0.92 and use deprecated methods. + </li> + <li> + If you are using a configuration file for version 0.20.5, you have to rebuild it in the new format. The format + of the configuration files has changed since version 0.20.5. See conf/fop.xconf for + an example configuration file. A XML Schema file can be found under + src/foschema/fop-configuration.xsd. + </li> + <li> + Beginning with version 0.94 you can skip the generation of + font metric files and remove the "font-metrics" attribute + in the font configuration. In the unlikely case that due to + a bug you still need to use font metrics files you will need + to regenerate the font metrics file if yours are from a FOP + version before 0.93. + </li> + <li> + <p> + The new code is much more strict about the interpretation of the XSL-FO 1.1 specification. + Things that worked fine in version 0.20.5 might start to produce warnings or even errors + now. FOP 0.20.5 contains many bugs which have been corrected in the new code. + </p> + <note label="An example"> + While FOP 0.20.5 allowed you to have empty <code>fo:table-cell</code> elements, the new code + will complain about that (unless relaxed validation is enabled) because the specification + demands at least one block-level element (<code>(%block;)+</code>, see + <a href="http://www.w3.org/TR/xsl/#fo_table-cell">XSL-FO 1.1, 6.7.10</a>) + inside an <code>fo:table-cell</code> element. + </note> + </li> + <li> + Extensions and Renderers written for version 0.20.5 will not work with the new code! The new FOP + extension for <a href="http://barcode4j.sourceforge.net">Barcode4J</a> is available since + January 2007. + </li> + <li> + The SVG Renderer and the MIF Handler have not been resurrected, yet! They are currently non-functional + and hope for someone to step up and reimplement them. + </li> + </ul> + </section> + <section id="issues"> + <title>What you need to know when you upgrade!</title> + <p> + When you use your existing FO files or XML/XSL files which work fine with FOP version + 0.20.5 against this FOP version some things may not work as expected. The following + list will hopefully help you to identify and correct those problems. + </p> + <ul> + <li> + Check the <a href="../compliance.html">Compliance page</a> for the feature causing + trouble. It may contain the necessary information to understand and resolve the problem. + </li> + <li> + Not all 0.20.5 output formats are supported. PDF and Postscript should be fully supported. + See <a href="output.html">Output Targets</a> for a more complete description. + </li> + <li> + As stated above empty table cells <code><fo:table-cell></fo:table-cell></code> + are not allowed by the specification. The same applies to empty <code>static-content</code> + and <code>block-container</code> elements, for example. + </li> + <li> + 0.20.5 is not XSL-FO compliant with respect to sizing images (<code>external-graphic</code>) + or <code>instream-foreign-object</code> + objects. If images or SVGs are sized differently in your outputs with the new FOP version + check <a href="http://issues.apache.org/bugzilla/show_bug.cgi?id=37136">Bug 37136</a> + as it contains some hints on what to do. The file + <a href="http://svn.apache.org/viewcvs.cgi/xmlgraphics/fop/trunk/examples/fo/basic/images.fo?view=markup"> + <code>"examples/fo/basic/images.fo"</code></a> has + a number of good examples that show the new, more correct behaviour. + </li> + <li> + The <code>fox:outline</code> extension is not implemented in this version anymore. + It has been superseded by the new bookmark elements from XSL-FO 1.1. + </li> + </ul> + </section> + </body> +</document> |