</section>
<section id="issues_new">
<title>Unreported Issues (Reporting New Issues)</title>
- <p>User reports of bugs and requests for enhancements are extremely
-important parts of FOP development, and we appreciate the time you take to help
-us track these issues down.</p>
+ <p>
+ User reports of bugs and requests for enhancements are extremely
+ important parts of FOP development, and we appreciate the time you take to help
+ us track these issues down.
+ </p>
<ul>
- <li>To help us ensure that the bug database is as useful as it should be, please
-use the <link href="gethelp.html">Getting Help</link> checklist to determine whether a bug report should be entered.</li>
- <li>Review the <link href="http://issues.apache.org/bugzilla/page.cgi?id=bug-writing.html">Apache Bug Writing Guidelines</link> before submitting your report.</li>
- <li>Enter a new issue report at <link href="http://issues.apache.org/bugzilla/enter_bug.cgi?product=Fop">The FOP issue database (Bugzilla)</link>.
-You will be asked to login to an existing Bugzilla account or to create a new
-one.
-When entering the bug report, please make your description complete and concise.
-If appropriate, attach a minimal fo file to your report which demonstrates the
-problem.</li>
- <li>After submission, a copy of your bug report will be automatically
-sent to the FOP developer discussion list.</li>
+ <li>
+ To help us ensure that the bug database is as useful as it should be, please
+ use the <link href="gethelp.html">Getting Help</link> checklist to determine whether a bug report should be entered.
+ </li>
+ <li>
+ Review the <link href="http://issues.apache.org/bugzilla/page.cgi?id=bug-writing.html">Apache Bug
+ Writing Guidelines</link> before submitting your report.
+ </li>
+ <li>
+ Enter a new issue report at <link href="http://issues.apache.org/bugzilla/enter_bug.cgi?product=Fop">The
+ FOP issue database (Bugzilla)</link>. You will be asked to login to an existing Bugzilla account or to
+ create a new one. When entering the bug report, please make your description complete and concise.
+ If the issue involves a specific input or output file, then you <strong>MUST</strong> include the
+ following information in the bug report (preferably as one or more attachments):
+ <ul>
+ <li>
+ an input XSL-FO file (an input XML plus XSLT file is not acceptable, unless and only if the
+ issue being reported is related to the built-in XSLT transform processing convenience function provided
+ by FOP); this input <strong>SHOULD</strong> be <em>maximally minimal</em>, which means that it should
+ contain nothing more than the minimum needed to demonstrate the problem; if you do not take the effort
+ to provide a maximally minimal input FO file, then you will be subsequently asked to do so before the
+ bug is processed;
+ </li>
+ <li>
+ a resulting output file, preferably in PDF format; if the issue being reported involves a different output
+ format, then provide both a PDF output file and the output file for the output format for which the report
+ applies;
+ </li>
+ <li>
+ a copy of the FOP configuration file you used (e.g., fop.xconf);
+ </li>
+ <li>
+ if FOP was invoked using the command line (or an equivalent), then a dump of both the input
+ command line and any console output (stderr or stdout) produced; if the report involves an
+ exception, then this <strong>MUST</strong> include the full stack back trace;
+ </li>
+ <li>
+ information describing the version of FOP you are using and the platform (and OS) on which
+ you are invoking FOP;
+ </li>
+ <li>
+ if the report applies to the use of a specific font other than one of the built-in, base 14
+ fonts, then information that describes where to obtain the font.
+ </li>
+ </ul>
+ </li>
+ <li>
+ After submission, a copy of your bug report will be automatically
+ sent to the FOP developer discussion list. If additional information is needed to
+ process the bug, then the bug will be set to the <code>NEEDSINFO</code> state, and
+ you will be asked to provide the additional information. You can avoid this extra
+ step by being diligent about providing <strong>all</strong> of the information
+ indicated above.
+ </li>
</ul>
</section>
</body>
<question>What is Apache™ FOP?</question>
<answer>
<p>
- FOP is a print formatter for <link href="#XSLFO">XSL formatting
+ FOP is a print formatter for <link href="#xslfo">XSL formatting
objects</link>.
</p>
<p>
<question>How does FOP interact with other Apache Projects?</question>
<answer>
<p>
- FOP is distributed with <link
- href="http://xml.apache.org/cocoon">Cocoon</link> as a PDF serializer
- for XSL (FO) documents.
+ <link href="http://xmlgraphics.apache.org/commons">XML Graphics Commons</link> is used with
+ FOP to provide graphics functions that are common to a number of Apache projects.
</p>
<p>
- <link href="http://xmlgraphics.apache.org/batik">Batik</link> can be used with
+ <link href="http://xmlgraphics.apache.org/batik">Batik</link> is used with
FOP to <link
href="http://xmlgraphics.apache.org/batik/svgrasterizer.html">transcode an SVG
image</link> into a PDF document.
</p>
+ <p>FOP also makes use of the following Apache projects:</p>
+ <ul>
+ <li><link href="http://excalibur.apache.org/framework/">Avalon Framework</link></li>
+ <li><link href="http://jakarta.apache.org/commons/io/">Jakarta Commons IO</link></li>
+ <li><link href="http://jakarta.apache.org/commons/logging/">Jakarta Commons Logging</link></li>
+ <li><link href="http://xalan.apache.org/">Xalan-J</link></li>
+ <li><link href="http://xml.apache.org/commons/components/external/">XML Commons Externals</link></li>
+ </ul>
</answer>
</faq>
<faq id="xsl-def">
<p>
XSL is a W3C standard concerned with publishing XML documents. It
consists of two parts: <link href="#XSLT">XSLT</link> and <link
- href="#XSLFO">XSL-FO</link>. The acronym expands to
+ href="#xslfo">XSL-FO</link>. The acronym expands to
e<strong>X</strong>tensible <strong>S</strong>tylesheet
<strong>L</strong>anguage.
</p>
<question>What is XSL-FO?</question>
<answer>
<p>
- XSLFO (aka XSL-FO) is an XML vocabulary that is used to specify a pagination and
+ XSLFO (aka XSL-FO) is an XML vocabulary, defined by W3C Recommendation
+ <link href="http://www.w3.org/TR/xsl/">Extensible Stylesheet Language (XSL)
+ Version 1.1</link>, that is used to specify a pagination and
other styling for page layout output. The acronym “FO”
stands for
<strong>F</strong>ormatting <strong>O</strong>bjects. XSLFO can be
<answer>
<p>
This is usually caused by an older version of one of the FOP jars or
- old XML tools in the classpath. Check in particular for parser.jar,
- jaxp.jar, xml4j.jar or lotusxsl.jar.
+ old XML tools in the classpath.
</p>
<p>
Incompatible versions of Batik may also cause this problem. Use the
the <code>file:</code> prefix, for example <code>file.ext</code>,
<code>path/file.ext</code> or <code>../file.ext</code>. The string
<code>file:path/file.ext</code> is <em>not</em> a relative URL,
- in fact, it isn't a valid URL at all. A relative URL is subject to a
- resolving process, which transforms it into an absolute
+ in fact, it isn't a valid URL at all since the <code>file</code>
+ scheme does not (officially) support relative paths. A relative URL
+ is subject to a resolving process, which transforms it into an absolute
URL.
</p>
<!--p>
<question>I get an "[ERROR]: null", or a NullPointerException.</question>
<answer>
<p>
- This is often caused by an invalid FO document. Currently only very
- common errors are intercepted and produce a comprehensible error
- message. If you forgot container elements like <code>fo:page-sequence</code> or
- <code>fo:flow</code> and put blocks and inline elements directly as children of
- <code>fo:root</code> or <code>fo:page-sequence</code>, you'll only get a
- NullPointerException. Check whether your FO file has a proper
- structure. In some cases there are mandatory properties, like the
- master-reference in <code>fo:conditional-page-master-reference</code>, check also
- whether you got them right.
- </p>
- <p>
- You may find it helpful to use the <link href="#fo-validate">validation tools</link> to validate your
- FO document. This will catch most problems, but should not be
- relied upon to catch all.
- </p>
- <p>
- If you use XSLT, problems in your style sheet and in your
- source XML also can produce a NullPointerException. <link
- href="1.0/running.html#check-input">Run the transformation
- separately</link> to check for this, usually you'll get a
- detailed error message from the XSLT processor.
- </p>
- <p>
- If you turn on debugging with the "<code>-d</code>" option you may be able to
- see more detailed information.
+ This is a very likely a bug in FOP. If you encounter this error, please
+ <link href="bugs.html#issues_new">Open a New Bug</link>.
</p>
</answer>
</faq>
<answer>
<p>
The most likely reason is a known problem with the Java run time
- environment which is triggered by rendering SVGs. Suns JDK 1.4 does
- not have this problem. See also <link href="#svghangs">FOP does not
- exit if a SVG is included</link>.
+ environment which is triggered by rendering SVGs. Sun's JDK 1.4 and
+ later do not have this problem. See also <link href="#svghangs">FOP
+ does not exit if a SVG is included</link>.
</p>
<p>
Another possibility is that FOP went into a non terminating
the FOP output regularly to empty the pipe buffer. It is best to avoid
exec'ing FOP, use the library interface instead.
</p>
+ <p>
+ If you can reproduce this problem given a specific input and configuration,
+ then please <link href="bugs.html#issues_new">Open a New Bug</link>.
+ </p>
</answer>
</faq>
<faq id="boxoverflow">
To avoid the warning you can simply delete the
old Font Cache file, which lives in ${base}\conf\font.cache (see <link
href="1.0/configuration.html#general-elements">font-base
- configuration</link>). Or you can disable Font Caching altogether using
- the option "use-cache."
+ configuration</link>).
</p>
</answer>
</faq>
HTTP. Possible issues include security settings on the
server, server configuration, and missing cookies or other
authorization information. Any easy way to check this is to
- cut&paste the source URL from the fo:external-graphic
+ cut and paste the source URL from the <code>fo:external-graphic</code>
into the Location field of a browser <strong>on the machine
where the FOP process will be running</strong>.</li>
</ul>
explicit wrapping+clipping,
</li>
<li>
- insert zero width spaces (U+200B or &#x200B;) to allow FOP to
+ insert zero width spaces (&#x200B;) to allow FOP to
wrap.
</li>
</ul>
<question>Where can I learn how the FOP docs and web site are built?</question>
<answer>
<p>
- See FOP <link href="dev/doc.html">Doc Management</link>. ;-)
+ See FOP <link href="dev/doc.html">Doc Management</link>.
</p>
</answer>
</faq>
If you have a runtime exception or other runtime problem:
<ul>
<li>
- double-check the <link href="#part-running">Runtime FAQs</link>.
+ Double check the <link href="#part-running">Runtime FAQs</link>.
</li>
<li>
ClassNotFoundException, NoSuchMethodException and
</li>
<li>
In the case where something works properly with another formatter,
- (AntennaHouse, PassiveTex, etc.) but doesn't work with FOP, please
+ (e.g., AntennaHouse, PassiveTex, etc.) but doesn't work with FOP, please
check the <!--link href="relnotes.html"-->Release Notes<!--/link-->, the
<link href="compliance.html">FOP Standards Compliance</link> document,
and the remaining FAQ in this document. If not found there, look at the
Problems specific to a certain XSLT processor, like Xalan, Saxon or
MSXML, should be handled by processor specific lists. This includes
problems with deployment, processor specific extensions, suspected
- bugs and processor specific APIs. Note that JDK 1.4 comes with an
- XML parser and an XSLT processor which are older versions of
- Xerces and Xalan, respectively, and both have a number of annoying
- bugs. See http://java.sun.com/developer/EJTechTips/2003/tt0311.html
- and http://java.sun.com/j2se/1.4.2/docs/guide/standards/ (or similar
- pages for later Java releases) for some hints on how to use more
- recent versions or other packages instead.
+ bugs and processor specific APIs. Note that JDK 1.4 and later come with an
+ XML parser and an XSLT processor which may be the source of the problem.
</li>
<li>
Problems with servlet containers should be asked on the vendor
projects / xmlgraphics-fop.git / commitdiff