<answer>
<p>
XSLFO is an XML vocabulary that is used to specify a pagination and
- other styling for page layout output. The acronym “FO” stands for
+ other styling for page layout output. The acronym “FO”
+ stands for
<strong>F</strong>ormatting <strong>O</strong>bjects. XSLFO can be
- used in conjunction with <jump href="#XSLT">XSLT</jump> to convert
+ used in conjunction with <link href="#XSLT">XSLT</link> to convert
from any XML format into a paginated layout ready for printing or
displaying.
</p>
<answer>
<p>
XSLT describes the transformation of arbitrary XML input into other
- XML (like XSLFO), HTML or plain text. The “T” comes from
+ XML (like XSLFO), HTML or plain text. The “T” comes from
<strong>T</strong>ransformation. For historical reasons, a
- transformation is often also called a “style sheet”.
+ transformation is often also called a “style sheet”.
</p>
<p>
Synonyms: XSL transformation, XSL:T, XSL style sheet.
<question>My PNG images don't work.</question>
<answer>
<p>
- The Jimi image library, which is used for processing images in PNG and
- other formats, was removed from the distribution for licensing
- reasons. You have to <fork href="http://java.sun.com">download</fork>
+ The Jimi image library, which is by default used for processing
+ images in PNG and other formats, was removed from the distribution
+ for licensing reasons. You have to <fork
+ href="http://java.sun.com">download</fork>
and install it by yourself.
</p>
</answer>
<faq>
<question>I get a NoClassDefFound exception.</question>
<answer>
- <p>This is typically a problem with your classpath.</p>
+ <p>
+ This is typically a problem with your <link
+ href="classpath.html">classpath</link>.</p>
<p>If you are running FOP from the command line:</p>
<ul>
<li>
</p>
<ul>
<li>
- Avoid forward references. Forward references cause all
- pages from the page with the reference on to be held in memory until
- the page with the referenced element is encountered. Common forward
+ Increase memory settings of the JVM, see for example <link
+ href="http://java.sun.com/j2se/1.3/docs/tooldocs/solaris/java.html">the
+ -Xmx option</link>. Be aware that it is usually unwise to
+ increase the memory allocated to the JVM beyond the amount of
+ physical RAM, it will significantly slow down. YMMV.
+ </li>
+ <li>
+ Avoid forward references. Forward references cause all pages from
+ the page with the reference on to be held in memory until the
+ page with the referenced element is encountered. Common forward
references are table of contents at the beginning of the document
- and the <link href="#pagenum">"page N of TOTAL"</link> in footers. Forward
- references may be required by the task, however, if you are getting
- a memory overflow you should at least check whether this is really
- as necessary as claimed. A TOC, for example, could often be placed
- at the end of the document without dimishing it's value too much,
- the paper can be reshuffled after printing, and you can use
+ and the <link href="#pagenum">"page N of TOTAL"</link> in footers.
+ Forward references may be required by the task, however, if you are
+ getting a memory overflow you should at least check whether this is
+ really as necessary as claimed. A TOC, for example, could often be
+ placed at the end of the document without dimishing it's value too
+ much, the paper can be reshuffled after printing, and you can use
bookmarks in PDF.
</li>
<li>
page by page, some memory allocated for other purposes could
possibly be freed after the page sequence has been rendered.
</li>
- <li>
- Increase memory settings of the JVM. Be aware that it
- is usually unwise to increase the memory allocated to the JVM beyond
- the amount of physical RAM, it will significantly slow down. YMMV.
- </li>
</ul>
<p>
There are also some bugs which cause FOP to go into an nonterminating
resolving process, which transforms it into an absolute
URL.
</p>
- <p>
+ <!--p>
See Understanding URIs and URLs and Understanding
URL resolving.
- </p>
+ </p-->
</answer>
</faq>
<faq>
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.
+ 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
Relative URLs are resolved against the baseDir property of FOP. For
the command line FOP application, the baseDir is the directory of the
input file, either the FO file or the XML source. If FOP is used
- embedded in a servlet, <link href="embedding.html">baseDir can be set explicitely</link>. If
- it's not set, it is usually the current working directory of the
- process which runs FOP.
+ embedded in a servlet, <link href="embedding.html">baseDir can be
+ set explicitely</link>. If it's not set, it is usually the current
+ working directory of the process which runs FOP.
</p>
- <p>
+ <!--p>
See Understanding URIs and URLs and Understanding
URL resolving.
- </p>
+ </p-->
</answer>
</faq>
<faq>
<question>FOP does not find my fonts.</question>
<answer>
<p>
- Did you get: «Failed to read font metrics file C:\foo\arial.xml
- : File "C:\foo\arial.xml" not found»? The value for the
+ Did you get: «Failed to read font metrics file C:\foo\arial.xml
+ : File "C:\foo\arial.xml" not found²? The value for the
metrics-file attribute in the user config file is actually an URL, not
a file name. Use "file:///C:/foo/arial.xml" instead.
</p>
don't work.</question>
<answer>
<p>
- These properties are not implemented, except for keep-with-next and
- keep-with-previous on table rows. In order to take advantage of them,
- you have to nest stuff to be kept together in a table.
+ These properties are not implemented, except on table rows. In
+ order to take advantage of them, you have to nest stuff to be
+ kept together in a table.
</p>
<p>
- The concept is called “blind table”. The table is used for
+ The concept is called “blind table”. The table is used for
pure layout reasons and not obvious in the output.
</p>
<p>
<question>A graphic is not displayed.</question>
<answer>
<p>
- Several possibilities:
+ The most common reason is that the file is not found because
+ of an empty or wrong baseDir setting, spelling errors in the
+ file name, in particular using the wrong case, or, if the
+ image is retrieved over HTTP, the image was not delivered because
+ of security settings in the server, missing cookies or other
+ authorization information or other server misconfigurations.
+ One way to check this is to cut&paste the source URL
+ from the fo:external-graphic into the Location field of
+ a browser <strong>on the machine where the FOP process
+ will be running</strong>.
+ </p>
+ <p>
+ Several other possibilities:
</p>
<ul>
<li>
content (very rare, but has happened).
</li>
</ul>
- <p>
+ <!-- p>
See also supported image formats.
- </p>
+ </p -->
</answer>
</faq>
<faq>
</faq>
</part>
<part>
- <title>Embedding FOP. Using FOP in a servlet</title>
+ <title>Embedding FOP. Using FOP in a servlet.</title>
<faq>
<question>How do I use FOP in a servlet?</question>
<answer>
with IEx and view it later. There are other problems with this code.
</p>
<p>
- Please look into Howto embed FOP in a servlet for all
- kinds of details.
+ Please look into <link href="embedding.html">Embedding FOP</link>
+ for all kinds of details.
</p>
</answer>
</faq>
</answer>
</faq>
<faq>
- <question>Problems with SVG referring to gradients etc. using
- "uri(#stuff)" (MalformedURLException or stuff not found)</question>
+ <question>I have problems with SVG referring to gradients etc. using
+ "uri(#stuff)". I get a MalformedURLException.</question>
<answer>
<p>
This is really a "resolving relative URI" problem with some
</answer>
</faq>
<faq>
- <question>Characters not displayed, or displayed incorrectly, or displayed
- as "#"</question>
- <answer>
- <p>Answers are that fonts must be available for the output format, and
- the selected font must contain glyphs for the desired character.
-PDF has a set of <link href="output.html#pdf-fonts">defined fonts</link>, other fonts can be embedded following the
-<link href="fonts.html">instructions</link>.
-To find out if the characters you need are in the core fonts then
-(todo - find a glyph font table for the fonts).
-</p>
- <p> For example, for most symbols, the symbol font has to be selected
- explicitely (in future it should be possible to specify a list of fonts
-where it will select the font for the specified character):
-</p>
-<p> <fo:inline font-family="Symbol">&#x2205;</fo:inline></p>
-<p> gives EMPTY SET while the same characters in the default font results
- in AE LIGATURE (which happens to occupy the same place in the default
- font as the EMPTY SET in the Symbol font). The "#" shows up if the
- selected font does not define a glyph for the translated index.</p>
+ <question>Some characters are not displayed, or displayed incorrectly, or
+ displayed as “#”.</question>
+ <answer>
+ <p>
+ There are a few fonts supplied with Acrobat Reader. If you use other
+ fonts, the font must be available on the machine where the PDF is
+ viewed or it must have been embedded in the PDF file. See
+ <link href="fonts.html">embedding fonts</link>.
+ </p>
+ <p>
+ Furthermore, if you select a certain font family, the font must
+ contain glyphs for the desired character. There is an <link
+ href="output.html#pdf-fonts">overview</link> available for the
+ default PDF fonts. For most symbols, it is better to select the symbol
+ font explicitely, for example in order to get the symbol for the
+ mathematical empty set, write:
+ </p>
+ <source><![CDATA[<fo:inline font-family="Symbol">∅</fo:inline>]]></source>
+ <p>
+ The "#" shows up if the selected font does not define a glyph for the
+ required character, for example if you try:
+ </p>
+ <source><![CDATA[<fo:inline font-family="Helvetica">∅</fo:inline>]]></source>
</answer>
</faq>
<faq id="PDF-postprocess">
<question>What tools are available for post-processing my PDF document?</question>
<answer>
<ul>
- <li>The most popular one that we are aware of is <link href="http://www.lowagie.com/iText">iText</link>, which has tools for adding security features, document properties, watermarks, and many other features to PDF files. See also Joerg Pietschmann's <link href="http://marc.theaimsgroup.com/?l=fop-dev&m=102002975028427&w=2">posting on PDF Encryption</link> for an example of Java application using iText.</li>
- <li>You can use Adobe Acrobat (the full version, not the Reader) to process the file manually or with scripting that it supports.</li>
+ <li>
+ The most popular one that we are aware of is <link
+ href="http://www.lowagie.com/iText">iText</link>, which has tools
+ for adding security features, document properties, watermarks, and
+ many other features to PDF files. FOP and iText can be integrated
+ into one Java application, see sample code for <link
+ href="pdf-security">encryption</link>.
+ The bad news is that iText swallows PDF bookmarks.
+ </li>
+ <li>
+ You can use Adobe Acrobat (the full version, not the Reader) to
+ process the file manually or with scripting that it supports.
+ </li>
</ul>
</answer>
</faq>
- <faq>
- <question>How do I add security features (encryption, for example) to my PDF document?</question>
- <answer>
- <p>FOP does not currently support this feature. Possible workarounds include those mentioned in the <link href="#PDF-postprocess">PDF Post-Processing FAQ</link>.</p>
+ <faq id="pdf-security">
+ <question>How do I add security features (encryption, disable printing) to my PDF document?</question>
+ <answer>
+ <p>
+ FOP does not currently support this feature. Possible workarounds
+ include those mentioned in the <link href="#PDF-postprocess">PDF
+ Post-Processing FAQ</link>.
+ </p>
+ <p>
+ Some sample code for encrypting a FOP generated PDF with iText to
+ get you started:
+ </p>
+ <source><![CDATA[public static void main(String args[]) {
+ try {
+ ByteArrayOutputStream fopout=new ByteArrayOutputStream();
+ FileOutputStream outfile=new FileOutputStream(args[2]);
+ Driver driver =new Driver();
+ driver.setOutputStream(fopout);
+ driver.setRenderer(Driver.RENDER_PDF);
+ Transformer transformer=TransformerFactory
+ .newInstance().newTransformer(new StreamSource(new File(args[1])));
+ transformer.transform(new StreamSource(new File(args[0])),
+ new SAXResult(driver.getContentHandler()));
+ PdfReader reader = new PdfReader(fopout.toByteArray());
+ int n = reader.getNumberOfPages();
+ Document document = new Document(reader.getPageSizeWithRotation(1));
+ PdfWriter writer = PdfWriter.getInstance(document, outfile);
+ writer.setEncryption(PdfWriter.STRENGTH40BITS, "pdf", null,
+ PdfWriter.AllowCopy);
+ document.open();
+ PdfContentByte cb = writer.getDirectContent();
+ PdfImportedPage page;
+ int rotation;
+ int i = 0;
+ while (i < n) {
+ i++;
+ document.setPageSize(reader.getPageSizeWithRotation(i));
+ document.newPage();
+ page = writer.getImportedPage(reader, i);
+ rotation = reader.getPageRotation(i);
+ if (rotation == 90 || rotation == 270) {
+ cb.addTemplate(page, 0, -1f, 1f, 0, 0,
+ reader.getPageSizeWithRotation(i).height()); }
+ else {
+ cb.addTemplate(page, 1f, 0, 0, 1f, 0, 0);
+ }
+ System.out.println("Processed page " + i);
+ }
+ document.close();
+ }
+ catch( Exception e) {
+ e.printStackTrace();
+ }
+}]]></source>
+ <p>
+ Check the iText tutorial and documentation for setting access flags,
+ password, encryption strength and other parameters.
+ </p>
</answer>
</faq>
<faq>
<answer>
<p>FOP does not currently support this feature. Possible workarounds:</p>
<ul>
- <li>See the <link href="#PDF-postprocess">PDF Post-Processing FAQ</link>.</li>
- <li>(submitted by Trevor_Campbell@kaz.com.au) Place an image in a region that overlaps the flowing text. For example, make region-before large enough to contain your image. Then include a block (if necessary, use an absolutely positioned block-container) containing the watermark image in the static-content for the region-before.</li>
+ <li>
+ Use a background image for the body region.
+ </li>
+ <li>
+ See the <link href="#PDF-postprocess">PDF Post-Processing
+ FAQ</link>.
+ </li>
+ <li>
+ (submitted by Trevor_Campbell@kaz.com.au) Place an image in a
+ region that overlaps the flowing text. For example, make
+ region-before large enough to contain your image. Then include
+ a block (if necessary, use an absolutely positioned
+ block-container) containing the watermark image in the
+ static-content for the region-before.
+ Note that the image will be drawn on top of the normal content.
+ </li>
</ul>
</answer>
</faq>
<faq>
- <question>PDF prints contorted</question>
- <answer>
- <p>Check paper size in Acrobat settings and "fit to page" (or something)</p>
- </answer>
- </faq>
- <faq>
- <question>Controlling Acrobat bookmark display</question>
+ <question>The PDF is printed contorted!</question>
<answer>
- <p> Not possible with FOP. Postprocess the PDF.</p>
+ <p>
+ Check the paper size in Acrobat settings and the "fit to page" print
+ setting. Contorted printing is often caused by a mismatched paper
+ format, for example if the setting is "US Letter" but the PDF was made
+ for A4.
+ Sometimes also the printer driver interferes, check its settings
+ too.
+ </p>
</answer>
</faq>
<faq>
- <question>PDF (more precise: Acrobat Reader) and IEx</question>
+ <question>How do I control the Acrobat bookmark display?</question>
<answer>
- <p>see #later</p>
+ <p>
+ FOP does not currently support this feature. Possible workarounds
+ include those mentioned in the <link href="#PDF-postprocess">PDF
+ Post-Processing FAQ</link>.
+ </p>
</answer>
</faq>
</part>
</p>
<ul>
<li>
- Use a URL ending in <code>.pdf</code>, like
+ Use an URL ending in <code>.pdf</code>, like
<code>http://myserver/servlet/stuff.pdf</code>. Yes, the servlet can
be configured to handle this. If the URL has to contain parameters,
try to have both the base URL as well as the last parameter end in
</p>
<p>
For the first problem, look at the print servlet in the FOP
- examples. You'll have to gather any printer settings in an HTML form
+ examples. You'll have to gather any printer settings in a HTML form
and send it to the server.
</p>
<p>
</answer>
</faq>
<faq>
- <question>(FO) How to get Euro sign/checkbox/some other stuff</question>
+ <question>(FO) How do I print an Euro sign, a checkbox or other some other
+ special symbols?</question>
<answer>
<p>
- Try to look it up in the Unicode reference at the <link
+ Try to look the character up in the Unicode reference at the <link
href="http://www.unicode.org">Unicode Consortium</link>, in
particular search the <link
href="http://www.unicode.org/charts/charindex.html">reference by
- name</link>. Use <link
+ name</link>.
+ </p>
+ <p>
+ Use <link
href="http://www.w3.org/TR/2000/REC-xml-20001006#sec-references">XML
character references</link> to put the character into your source
XML, XSLT or FO.
</p>
<p>
- Watch out for font traps, see #, change font temporarily using
- fo:inline if necessary.
+ For example, the following will result in an Euro sign:
+ </p>
+ <source><![CDATA[€]]></source>
+ <p>
+ The selected font family must have a glyph for the character you want
+ to show. This is actually a somewhat tricky issue, especially for
+ symbol characters.
+ </p>
+ <p>
+ Some environments provide also a character table utility (like Win2K
+ or WinXP), which can also help you to get an idea what glyphs are
+ available in a certain font.
</p>
<p>
Alternative: Use an embedded graphic: GIF, PNG, SVG, whatever.
</answer>
</faq>
<faq>
- <question>(FO) How do I keep linebreaks/hard spaces? How do I get
- preformatted text displayed as expected.</question>
+ <question>(FO) How do I keep linebreaks and hard spaces? How do I get
+ preformatted text displayed as expected?</question>
<answer>
<p>
The specification provides some properties for this: <link
<answer>
<anchor id="pagenum"/>
<p>
- (XSL FAQ)
+ This is an XSL FAQ.
</p>
<p>
Put an empty block with an id at the end of the flow:
</p>
<source><![CDATA[<fo:flow ...>
- ...
+ ...
<fo:block id="last-page"/>
- </fo:flow>]]></source>
+</fo:flow>]]></source>
<p>
Get the number of the last page as follows:
</p>
</faq>
<faq>
<question>(FO) The header overlaps body content. The body extends into
- footer.</question>
+ the footer.</question>
<answer>
<p>
Contrary to popular opinion, the regions on a page may overlap.
<faq id="FO-validate">
<question>(FO) How do I validate my FO document?</question>
<answer>
- <p><link href="http://www.renderx.com">RenderX</link> has provided an <link href="http://www.renderx.com/Tests/validator/fo.dtd.html">Unofficial DTD for FO Documents</link>. This document may be helpful in validating general FO issues.</p>
- <p>FOP also maintains an <link href="http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-fop/docs/foschema/fop.xsd?rev=HEAD&content-type=text/plain">Unofficial FOP Schema</link> in the FOP CVS Repository. This document can be used either to validate against the FO standard, or against the actual FOP implementation. See the notes near the beginning of the document for instructions on how to use it.</p>
+ <p>
+ <link href="http://www.renderx.com">RenderX</link> has provided an
+ <link
+ href="http://www.renderx.com/Tests/validator/fo.dtd.html">Unofficial
+ DTD for FO Documents</link>. This document may be helpful in
+ validating general FO issues.
+ </p>
+ <p>
+ FOP also maintains an <link
+ href="http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-fop/docs/foschema/fop.xsd?rev=HEAD&content-type=text/plain">Unofficial
+ FOP Schema</link> in the FOP CVS Repository. This document can be
+ used either to validate against the FO standard, or against the
+ actual FOP implementation. See the notes near the beginning of the
+ document for instructions on how to use it.
+ </p>
</answer>
</faq>
<faq>
- <question>(XML) Complaints about &nbsp;. How do I get a non-breaking
- space in FO?</question>
+ <question>(XML) There are complaints about <code>&nbsp;</code>. How
+ do I get a non-breaking space in FO?</question>
<answer>
<p>
Use &#160; everywhere. In your own XML, you could also use a DTD
</faq>
<faq>
<question>(XML) There are complaints about undefined entities, for example
- complaints about &uuml; which used to work in HTML. How do I enter
- special characters like in HTML?</question>
+ about <code>&uuml;</code> which used to work in HTML. How do I enter
+ special characters like in HTML?</question>
<answer>
<p>
Don't use names as in HTML, use numbers (unless you have a DTD which
offending characters.
</p>
<p>
- Refer to the <link href="http://www.w3.org/XML/">XML specification</link> or to a good tutorial for
+ Refer to the <link href="http://www.w3.org/XML/">XML
+ specification</link> or to a good tutorial for
details of the XML file format.
</p>
</answer>
packages producing XML, in particular most XSLT processors, produce by
default UTF-8 encoded files. If you view them with something not aware
of the encoding, like Notepad for Win95/98/ME/NT, funny characters are
- displayed. A Å is a giveaway.
+ displayed. A Å is a giveaway.
</p>
</answer>
</faq>
</part>
<part>
- <title>General suggestions. How to solve problems</title>
+ <title>General suggestions. How to solve problems.</title>
<faq>
- <question>Where to post bugs</question>
+ <question>Where to post bugs.</question>
<answer>
<p>
- See docs. See also <jump href="#postquestions">"where to post
- questions"</jump>.
+ See <link href="bugs.html">documentation</link>. See also
+ <link href="#postquestions">"where to post
+ questions"</link>.
</p>
</answer>
</faq>
You get exceptions. First, check the FAQ whether the exception is
mentioned. ClassNotFoundException, NoSuchMethodException and
NoSuchFieldException problems are almost always a problem with the
- local environment. Check <link
+ local environment, try to get local help first. Check <link
href="http://nagoya.apache.org">bugzilla</link>. If still not found,
post to fop-dev.
</li>
XSLT specific stuff sould go to the <link
href="http://www.mulberrytech.com/xsl/xsl-list/">XSL
list</link>. This includes problems with the language and XSLT
- How-Tos.
+ HOW-TOs.
</li>
<li>
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.
+ 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 $$$FIXME on how to use more recent versions or other
+ packages instead.
</li>
<li>
Problems with servlet containers should be asked on the vendor
- specific lists for these software packets.
+ specific lists for these software packages.
</li>
<li>
More general questions regarding Java, including deployment, Java
projects / xmlgraphics-fop.git / commitdiff