| <?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 four years. With version 0.93 the code has reached |
| <strong>production level</strong>, and continues to improve with |
| version 0.94 and 0.95. |
| </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. The font metrics files are, for |
| the moment, still required if you use a TrueType Collection (*.ttc) |
| and in that case you 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.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 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/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. This does not mean |
| that the new FOP is at fault. Quite the opposite actually! See below: |
| </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> |
| 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. So please |
| update your stylesheets accordingly. |
| </li> |
| </ul> |
| </section> |
| </body> |
| </document> |
