123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126 |
- <?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.krysalis.org">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>
|