aboutsummaryrefslogtreecommitdiffstats
path: root/src/documentation/content/xdocs/trunk/upgrading.xml
blob: b8aa58200b9fe807e817a0f4420d948acbb45cce (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
<?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>.
        </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>
          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 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/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> will be available in 
          January 2007.
        </li>
        <li>
          The PCL 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>
        <li>
          By looking at the <a href="../compliance.html">Compliance page</a> you might get the impression
          that the new code is much more advanced than version 0.20.5. That's true but there may still
          be a few things that may not be handled as gracefully by the new code as by version 0.20.5.
        </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>&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.
        </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>