fop-1_1/src/documentation/content/xdocs/0.95/upgrading.xml - xmlgraphics-fop - Git at Google

 <?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 Apache™ 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.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. 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>&lt;fo:table-cell&gt;&lt;/fo:table-cell&gt;</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>
	<?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 Apache™ 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.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. 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>