| <?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 |
| the tradition continues 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 <code>conf/fop.xconf</code> for |
| an example configuration file. A XML Schema file can be found under |
| <code>src/foschema/fop-configuration.xsd</code>. |
| </li> |
| <li> |
| If you are using font metrics files for version 0.20.5 or |
| 0.92 or earlier, you have to regenerate them in the new |
| format. The new format is characterized by a version |
| attribute on the top-level font-metrics element, whose value |
| is 2.0. The absence of a version attribute will be |
| interpreted as version 1.0, and such metrics files will no |
| longer be parsed. |
| </li> |
| <li> |
| <p> |
| The new code is much more strict about the interpretation of the XSL-FO 1.0 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 <a href="/0.94/running.html#fop-script">relaxed validation is enabled</a> via the <code>-r</code> switch via the command line) because the specification |
| demands at least one block-level element (<code>(%block;)+</code>, see |
| <a href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice6.html#fo_table-cell">XSL-FO 1.0, 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> |
| <li> |
| The <code>fox:destination</code> extension is also not implemented in this version |
| although it may be added in the future. See also |
| <a href="http://issues.apache.org/bugzilla/show_bug.cgi?id=37157">Bug 37157</a>. |
| </li> |
| </ul> |
| </section> |
| </body> |
| </document> |