123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209 |
- <?xml version="1.0" encoding="ISO-8859-1"?>
- <!--
- 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 faqs PUBLIC "-//APACHE//DTD FAQ V1.1//EN" "http://forrest.apache.org/dtd/faq-v12.dtd">
-
- <faqs title="FOP FAQ">
- <part id="part-general">
- <title>General questions</title>
- <faq id="fop-general">
- <question>What is FOP?</question>
- <answer>
- <p>
- FOP is a print formatter for <link href="#XSLFO">XSL formatting
- objects</link>.
- </p>
- <p>
- It can be used to render an XML file containing XSL formatting objects
- into a page layout. The main target is PDF but other rendering targets
- are supported, such as AWT, PCL, text and direct printing.
- </p>
- </answer>
- </faq>
- <faq id="fop-functions">
- <question>What can I do with FOP?</question>
- <answer>
- <p>
- FOP provides both an application and a library that converts an XSL FO
- document into paginated output.
- </p>
- <p>
- The FOP command line application can be directly used to transform XML
- into PDF, PostScript, PCL and other formats, there is also an AWT
- based viewer integrated.
- </p>
- <p>
- The library can be used in servlets and other Java applications.
- </p>
- </answer>
- </faq>
- <faq id="fop-acronym">
- <question>What does "FOP" stand for?</question>
- <answer>
- <p>
- FOP is an acronym for <strong>F</strong>ormatting
- <strong>O</strong>bject <strong>P</strong>rocessor
- </p>
- </answer>
- </faq>
- <faq id="fop-other-apache">
- <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.
- </p>
- <p>
- <link href="http://xml.apache.org/batik">Batik</link> can be used with
- FOP to <link
- href="http://xml.apache.org/batik/svgrasterizer.html">transcode an SVG
- image</link> into a PDF document.
- </p>
- </answer>
- </faq>
- <faq id="xsl-def">
- <question>What is XSL?</question>
- <answer>
- <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">XSLFO</link>. The acronym expands to
- e<strong>X</strong>tensible <strong>S</strong>tylesheet
- <strong>L</strong>anguage.
- </p>
- </answer>
- </faq>
- <faq id="xslfo">
- <question>What is XSL-FO?</question>
- <answer>
- <p>
- XSLFO (aka XSL-FO) is an XML vocabulary 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
- 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>
- <p>
- XSLFO defines a set of elements in XML that describes the way pages
- are set up. The contents of the pages are filled from flows. There can
- be static flows that appear on every page (for headers and footers)
- and the main flow which fills the body of the page.
- </p>
- <p>
- Synonyms: XSL FO, XSL (FO), XSL:FO, XSL-FO, Formatting Objects
- </p>
- </answer>
- </faq>
- <faq id="XSLT">
- <question>What is XSLT?</question>
- <answer>
- <p>
- XSLT describes the transformation of arbitrary XML input into other
- 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”.
- </p>
- <p>
- Synonyms: XSL transformation, XSL:T, XSL style sheet.
- </p>
- </answer>
- </faq>
- <faq id="when">
- <question>When will feature X be implemented?</question>
- <answer>
- <p>The short answer is "Don't ask." For more details, see <link href="gethelp.html#limitations">Understand FOP's Limitations</link>.</p>
- </answer>
- </faq>
- <faq id="next-release">
- <question>When is the next released planned?</question>
- <answer>
- <p>
- When it's ready and the committers have enough time to go through
- the time-consuming process of creating a release. We
- released version 0.93 on 9 January 2007, and intend to
- release version 1.0 later in 2007. If you
- want to speed up the process, consider to
- <link href="dev/index.html#involved">contribute</link> to FOP.</p>
- </answer>
- </faq>
- <faq id="redesign">
- <question>Why did you redesign FOP?</question>
- <answer>
- <p>The code redesign of FOP was necessary in order to be able to adress following issues:</p>
- <ul>
- <li>Keeps and Breaks</li>
- <li>XSL-FO Compliance in general</li>
- <li>Process Files of Arbitrary Size</li>
- <li>Minimize Memory Use</li>
- <li>Table Layout</li>
- </ul>
- </answer>
- </faq>
- <faq id="contribute">
- <question>How can I contribute?</question>
- <answer>
- <p>
- There are numerous ways that you can help. They are outlined in the <link href="dev/index.html">Developer's Introduction</link> page.
- </p>
- </answer>
- </faq>
- </part>
- <part id="part-running">
- <title>Problems running FOP</title>
- <faq id="no-page-master">
- <question>I get the error: [ERROR]: 'master-reference' for
- 'fo:page-sequence'matches no 'simple-page-master' or
- 'page-sequence-master'</question>
- <answer>
- <p>
- FOP was changed to be in accordance with the latest standard (see
- <link href="resources.html#w3-xsl">XSL standard</link>).The page
- master for a fo:page-sequence is now refereced by the
- master-reference attribute. Replace the master-name attributes of
- your fo:page-sequence elements by master-reference attributes. You
- have to do this also for fo:single-page-master-reference,
- fo:repeatable-page-master-reference and
- fo:conditional-page-master-reference elements in you page master
- definitions.
- </p>
- <p>
- Update your FO documents and style sheets.
- </p>
- </answer>
- </faq>
- <faq id="NoClassDefFound">
- <question>I get a NoClassDefFound exception.</question>
- <answer>
- <p>This is typically a problem with your classpath.</p>
- <p>If you are running FOP from the command line:</p>
- <ul>
- <li>
- Use the <code>fop.bat</code>, <code>fop</code> or <code>fop.sh</code> command file from the FOP
- distribution. If you have a FOP version older than 0.20.5,
- ensure the directory where FOP and these files have been
- installed is the current working directory.
- </li>
- <li>
- If this doesn't help, check whether still all the jar files
- mentioned in the classpath in the <code>fop.bat</code> file are in their
- respective places.
- </li>
- </ul>
- <p>
- If you run FOP embedded in your servlet, web application or
- other Java application, check the classpath of the
- application. Check the also the information pertaining to <link
- href="0.93/servlets.html#servlet-engine">servlet engines</link>
- for further hints.
- </p>
- <p>
- If you downloaded the source distribution, or a snapshop
- from the repository, remember you have to build the FOP jars
- first.
- </p>
- </answer>
- </faq>
- <faq id="NoSuchMethodException">
- <question>I get a NoSuchMethodException or a NoSuchFieldException
- exception.</question>
- <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.
- </p>
- <p>
- Incompatible versions of Batik may also cause this problem. Use the
- version of Batik that comes with FOP. It is not always possible to
- use a more recent version of Batik.
- </p>
- </answer>
- </faq>
- <faq id="OutOfMemoryException">
- <question>I get an OutOfMemoryException.</question>
- <answer>
- <p>
- See <link href="0.93/running.html#memory">FOP Memory</link>.
- </p>
- </answer>
- </faq>
- <faq id="MalformedURLException">
- <question>I get a MalformedURLException.</question>
- <answer>
- <anchor id="MalformedURL"/>
- <p>
- What you probably think of as "file names" are usually URLs, in
- particular the <code>src</code> attribute of fo:external-graphic.
- </p>
- <p>
- Because usage of URLs is growing, you should make yourself familiar
- with it. The relevant specification is <link
- href="http://www.rfc-editor.org/rfc/rfc2396.txt">RFC 2396</link>.
- </p>
- <p>
- In a nutshell, the correct syntax for an absolute file URL is
- <code>file:///some/path/file.ext</code> on Unix and
- <code>file:///z:/some/path/file.ext</code> on Windows systems. Note
- the triple slash, and also that only forward slashes are used, even on
- windows.
- </p>
- <p>
- A relative file URL starts with anything but a slash, and doesn't have
- 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
- URL.
- </p>
- <!--p>
- See Understanding URIs and URLs and Understanding
- URL resolving.
- </p-->
- </answer>
- </faq>
- <faq id="NullPointerException">
- <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="0.93/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.
- </p>
- </answer>
- </faq>
- <faq id="not-implemented">
- <question>FOP returns the message "[ERROR] <em>object|property - 'x'</em> is not implemented yet." When will it be implemented?</question>
- <answer>
- <p>See FOP's Standards <link href="compliance.html">Compliance</link> page.</p>
- </answer>
- </faq>
- <faq id="fop-hangs">
- <question>FOP hangs. FOP does not exit.</question>
- <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>.
- </p>
- <p>
- Another possibility is that FOP went into a non terminating
- loop. Usually this is indicated by lots of log messages of the form
- "[INFO]: [NNNN]" which indicate a new page has been started or <link
- href="#boxoverflow">box overflows</link>. After some time, FOP will
- crash with an OutOfMemoryException.
- </p>
- <p>
- If you called the FOP command line application from some other
- programm, for example from Java using Runtime.exec(), it may hang
- while trying to write log entries to the output pipe. You have to read
- the FOP output regularly to empty the pipe buffer. It is best to avoid
- exec'ing FOP, use the library interface instead.
- </p>
- </answer>
- </faq>
- <faq id="boxoverflow">
- <question>FOP runs forever, writing lots of ">" to the log.</question>
- <answer>
- <p>
- There is something too large to fit into the intended place, usually a
- large image, a table whose rows are kept together or a block with a
- space-before or space-after larger than the page size. Catch the first
- page showing this phenomenon and check it. If it is not obvious which
- element causes the trouble, remove stuff until the problem goes
- away. Decrease the dimensions of the offending element or property, or
- increase the dimension of the enclosing element or container, or
- remove keep-with-* properties.
- </p>
- </answer>
- </faq>
- <faq id="cannot-find-external-graphics">
- <question>FOP cannot find a file for fo:external-graphics.</question>
- <answer>
- <p>The src attribute of the <code>fo:external-graphics</code> element requires a URI, not a file name. See <link href="fo.html#external-resources">External Resources</link> for more information about specifying URIs.</p>
- </answer>
- </faq>
- <faq id="fonts-not-found">
- <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
- metrics-file attribute in the user config file is actually an URL, not
- a file name. Use "file:///C:/foo/arial.xml" instead.
- </p>
- <p>
- If you used a relative URL, make sure your application has the working
- directory you expect. Currently FOP does not use the baseDir for
- resolving relative URLs pointing to font metric files.
- </p>
- <p>
- Try also setting the <link
- href="0.93/configuration.html#general-elements">font-base
- configuration</link>.
- </p>
- </answer>
- </faq>
- </part>
- <part id="part-output">
- <title>Problems with FOP output</title>
- <faq id="leader-expansion">
- <question>Leaders don't work anymore in 0.93. Instead of
- filling the line, only three dots or a short ruler is
- output.</question>
- <answer>
- <p>
- Leaders still work, in fact they work better than ever
- before. You'll just have to add <code>text-align="justify"</code> and/or
- <code>text-align-last="justify"</code> to the block with the leader. Be
- sure you haven't accidentally overridden the
- <code>leader-length.maximum="100%"</code> default value.
- </p>
- <p>
- Earlier versions of FOP used to expand a leader to fill the
- rest of the line unconditionally, anything following it,
- like page numbers in a TOC, was actually shifted beyong the
- right margin.
- </p>
- <p>
- The new implementation uses leader-length.optimum to
- determine where to break the line, and expands the leader
- only further if the line should be filled, as indicated by
- the text-aling and text-align-last properties.
- </p>
- <p>
- Actually due to the fuzzyness of the specification both the
- old and the new method are conformant (although adding text
- after the expanded leader in the old variant never was).
- </p>
- <p>
- If you want to have a longer ruler or space in a
- non-justified line, you have to increase the
- leader-length.optimum property.
- </p>
- </answer>
- </faq>
- <faq id="blank-page-between-page-sequences">
- <question>Why does FOP insert a blank page between my page sequences?</question>
- <answer>
- <p>
- This is because spec conformance has been improved.
- </p>
- <p>
- The <link
- href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice7.html#force-page-count">force-page-count
- property</link> controls how a FO processor pads page sequences in
- order to get certain page counts or last page numbers. The default is
- "<code>auto</code>". With this setting, if the next page sequence
- begins with an odd page number because you set the
- initial-page-number, and the current page sequence also ends with an
- odd page number, the processor inserts a blank page to keep odd and
- even page numbers alternating (similar for the case the current page
- sequence ends with an even page number and the next page sequence
- starts with an even page number.
- </p>
- <p>
- If you don't want to have this blank page, use
- <code>force-page-count="no-force"</code>.
- </p>
- </answer>
- </faq>
- <faq id="graphic-not-displayed">
- <question>Why is my graphic not rendered?</question>
- <answer>
- <p>Most commonly, the external file is not being found by FOP.
- Check the following:</p>
- <ul>
- <li>Empty or wrong baseDir setting.</li>
- <li>Spelling errors in the file name (including using the wrong case).</li>
- <li>Security Problems (i.e. the image could not be accessed
- because FOP is not allowed to read the file). This is
- especially a problem if the external file is retrieved over
- 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
- into the Location field of a browser <strong>on the machine
- where the FOP process will be running</strong>.</li>
- </ul>
- <p>Other possibilities:</p>
- <ul>
- <li>The image format is not supported or not supported completely.
- See <link href="0.93/graphics.html">FOP Graphics Formats</link> for a
- list of supported formats and related issues.</li>
- <li>The graphic may be too large to fit into the intended space.</li>
- <li>There may be something (static content) that is obscuring the
- graphic. (This is very rare).
- </li>
- </ul>
- </answer>
- </faq>
- <faq id="png-fails">
- <question>My graphical images do not work properly.</question>
- <answer>
- <p>See <link href="0.93/graphics.html">FOP Graphics Formats</link> for a
- list of supported graphics formats and related issues.</p>
- </answer>
- </faq>
- <faq id="graphic-resolution">
- <question>Why is my graphic rendered at a different resolution than it was created?</question>
- <answer>
- <p>See <link href="0.93/graphics.html#resolution">Graphics Resolution</link>.</p>
- </answer>
- </faq>
- <faq id="keep-with">
- <question>Keep-with-next, keep-with-previous, keep-together
- don't work.</question>
- <answer>
- <p>
- These properties are not implemented on version 0.20.5 and earlier, 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
- pure layout reasons and is not obvious in the output.
- </p>
- <p>
- An example of an image and the image caption to be kept together:
- </p>
- <source><![CDATA[<fo:table table-layout="fixed" width="100%">
- <fo:table-column column-width="proportional-column-width(1)"/>
- <fo:table-body>
- <fo:table-row keep-with-next="always">
- <fo:table-cell>
- <fo:block>
- <fo:external-graphic src="foo.jpg"/>
- </fo:block>
- </fo:table-cell>
- </fo:table-row>
- <fo:table-row>
- <fo:table-cell>
- <fo:block>Image Caption</fo:block>
- </fo:table-cell>
- </fo:table-row>
- </fo:table-body>
- </fo:table>]]></source>
- <p>
- Consider upgrading to the latest version which supports keeps.
- </p>
- </answer>
- </faq>
- <faq id="table-missing">
- <question>My tables are missing, or missing their content.</question>
- <answer>
- <p>
- Check for <code>fo:table-body</code> around the rows. FOP up to 0.20.4 doesn't
- raise an error if it is omitted, it just drops the content. More
- recent releases will catch this problem.
- </p>
- <p>
- Also, the <code>fo:table-with-caption</code> element is not implemented, tables
- within such an element are dropped too. FOP generates an error
- message for this problem. Older DocBook style sheets generate
- <code>fo:table-with-caption</code> elements, so watch out.
- </p>
- </answer>
- </faq>
- <faq id="cells-overflow">
- <question>Text overflowing table cells and the like is not clipped. Long
- text flows into adjacent cells/block, obscuring stuff there.</question>
- <answer>
- <p>
- Clipping as specified by the <code>overflow="hidden"</code> is not yet
- implemented. If you have long words overflowing table cells, try to
- get them hyphenated. Artificial names like product identifications or
- long numbers usually aren't hyphenated. You can try special processing
- at XSLT level, like
- </p>
- <ul>
- <li>
- clip long text,
- </li>
- <li>
- explicit wrapping+clipping,
- </li>
- <li>
- insert zero width spaces (U+200B or &#x200B;) to allow FOP to
- wrap.
- </li>
- </ul>
- <p>
- Check the <link href="http://dpawson.co.uk/xsl">XSL FAQ</link> and the
- <link href="http://www.mulberrytech.com/xsl/xsl-list/">XSL list
- archive</link> for how to perform these tasks.
- </p>
- </answer>
- </faq>
- <faq id="page-number-align">
- <question>Page numbers are not properly right aligned.</question>
- <answer>
- <p>
- This happens for <code>fo:page-number-citation</code> elements if the
- citation occurs before FOP formatted the requested page,
- usually in TOC or index pages. It is caused by the problem
- that FOP has to guess how much space the yet unknown page
- number will occupy, and usually the guesses are somewhat
- off.
- </p>
- <p>
- The most recent FOP releases should have this problem
- fixed. Check whether you can upgrade.
- </p>
- </answer>
- </faq>
- <faq id="hyphenation-fails">
- <question>Hyphenation does not work.</question>
- <answer>
- <p>Make sure you have set the language and optionally the country attributes for an appropriate XSL-FO element (fo:page-sequence, fo:block or fo:character):</p>
- <source><![CDATA[<fo:page-sequence language="fi">]]></source>
- <p>See <link href="0.93/hyphenation.html#support">Hyphenation Support</link> for details and instructions on using hyphenation with FOP.</p>
- <p>Explicitly enable hyphenation for an appropriate XSL-FO element (fo:block, fo:character):</p>
- <source><![CDATA[<fo:block hyphenate="true">]]></source>
- </answer>
- </faq>
- <faq id="indent-inheritance">
- <question>When I use margins, my content in a nested table or block-containers gets indented twice. Is this a bug?</question>
- <answer>
- <p>
- (Applies to version 0.90 and later)
- No, although you might easily think so. The problem has to do
- with property inheritance of the start-indent and end-indent
- properties to which the margin properties are mapped. Apache
- FOP strictly adheres to the XSL-FO specification here which many
- other commercial FO implementations don't do to better meet end-user
- expectations. You can make FOP behave like these if you set
- <code>setBreakIndentInheritanceOnReferenceAreaBoundary(true)</code>
- on the FOUserAgent. The better way is to reset <code>start-indent</code>
- and <code>end-indent</code> to "0pt" on table-body or block-container.
- For further details, please consult the
- <link href="http://wiki.apache.org/xmlgraphics-fop/IndentInheritance">Wiki page on Indent Inheritance</link>.
- </p>
- </answer>
- </faq>
- </part>
- <part id="part-embedding">
- <title>Embedding FOP. Using FOP in a servlet.</title>
- <faq id="servlet">
- <question>How do I use FOP in a servlet?</question>
- <answer>
- <p>
- See <link href="0.93/servlets.html">Using FOP in a Servlet</link>.
- </p>
- </answer>
- </faq>
- <faq id="servlet-with-xslt">
- <question>How do I use FOP in a servlet with an XSLT
- transformation?</question>
- <answer>
- <p>
- See <link href="0.93/servlets.html#xslt">Using FOP in a Servlet with XSLT Transformation</link>.
- </p>
- </answer>
- </faq>
- <faq id="servlet-xslt-params">
- <question>How do I pass parameters to the XSLT transformation?</question>
- <answer>
- <p>
- See <link href="0.93/servlets.html#xslt">Using FOP in a Servlet with XSLT Transformation</link>.
- </p>
- </answer>
- </faq>
- <faq id="servlet-nonstd-fonts">
- <question>How do I use my own fonts when running FOP from a servlet?</question>
- <answer>
- <p>
- Declare the fonts in the <code>userconfig.xml</code> file as usual.
- See <link href="#usercfg">loading the user configuration file</link>
- for further details.
- </p>
- </answer>
- </faq>
- <faq id="servlet-baseDir">
- <question>How do I set the baseDir property in a servlet environment?</question>
- <answer>
- <p>
- See <link href="0.93/embedding.html#config-internal">Setting the Configuration Programmatically</link>.
- </p>
- </answer>
- </faq>
- <faq id="usercfg">
- <question>How do I use a user configuration file from a servlet?</question>
- <answer>
- <p>
- See <link href="0.93/embedding.html#config-external">Using a Configuration File in an Embedded App</link>.
- </p>
- </answer>
- </faq>
- <faq id="servlet-NoClassDefFound">
- <question>I keep getting NoClassDefFound and other exceptions. How do I
- get FOP working for various servlet engines?</question>
- <answer>
- <p>
- See <link href="0.93/servlets.html#servlet-engine">Servlet Engines</link>.
- </p>
- </answer>
- </faq>
- <faq id="multithreaded">
- <question>Can FOP be used in multithreaded environments?</question>
- <answer>
- <p>
- See <link href="0.93/embedding.html#multithreading">Multithreading FOP</link>.
- </p>
- </answer>
- </faq>
- </part>
- <part id="part-svg">
- <title>SVG specific questions</title>
- <faq id="svg-text">
- <question>The rendering of SVG text in my PDF is of poor quality.
- Can I control this?</question>
- <answer>
- <p>See <link href="0.93/graphics.html#svg-pdf-text">Placing SVG Text into PDF</link>.</p>
- </answer>
- </faq>
- <faq id="svg-headless">
- <question>How do I use FOP with SVG on headless servers?</question>
- <answer>
- <p>See <link href="0.93/graphics.html#batik">FOP: Graphics (Batik)</link>.</p>
- </answer>
- </faq>
- <faq id="svghangs">
- <question>FOP does not exit if a SVG is included.</question>
- <answer>
- <p>
- Applies to older FOP versions and JDK 1.3 and older. That's because
- there is an AWT thread hanging around. The solution is to put a
- System.exit(0) somewhere.
- </p>
- </answer>
- </faq>
- <faq id="svg-url">
- <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
- twists. The problem is that the <code>#stuff</code> URL fragment
- identifier is resolved within the current SVG document. So the
- reference must be valid within the XML subset and it cannot
- reference other SVG documents in the same XML file. Some options
- to try:
- </p>
- <ul>
- <li>
- Put the SVG into a separate file and use it with
- fo:external-graphics.
- </li>
- <li>
- Use a separate SVG file which contains only the gradient (and
- perhaps other SVG stuff you want to reference) and point an absolute
- URL to it:
- <code>fill="url(file:///c:/refstuff/grad.svg#PurpleToWhite)"</code>.
- </li>
- <li>
- Same as above but use a relative URL:
- <code>fill="url(grad.svg#PurpleToWhite)"</code>. This may be easier
- to deploy.
- </li>
- <li>
- Make sure that the reference is valid in the current SVG document.
- </li>
- </ul>
- <p>
- In any case, the referenced stuff has to be pointed to by an URL. It
- doesn't necessarily have to be a file URL, HTTP should also
- work. Also, expect a performance hit in all cases, because another XML
- file has to be retrieved and parsed.
- </p>
- <p>
- Ultimately, both FOP and especially Batik should be fixed to make
- your code work as expected, but this will not only take some time
- but also some effort by a standard committee in order to make the
- semantics of this kind of references in embedded SVG clearer.
- </p>
- <p>See also <link href="#MalformedURL">MalformedURLException</link></p>
- </answer>
- </faq>
- <faq id="svg-scaling">
- <question>Why is my SVG rendered at a size different from that specified in my fo:external-graphic element?</question>
- <answer>
- <p>See <link href="0.93/graphics.html#svg-scaling">SVG Scaling</link>.</p>
- </answer>
- </faq>
- <faq id="svg-attribute-required">
- <question>FOP fails with something like "The attribute "width" of the element <rect> is required". What's wrong?</question>
- <answer>
- <p>
- This phenomenon occurs since FOP 0.92 beta. It surfaced due to a change in the handling of non-FO namespaces. It's not a
- bug in FOP, but rather in the dependent packages: Apache Batik, Apache Xalan-J and SAXON. The bug in Apache Batik will be
- fixed in the next release. In the latest release of Apache Xalan-J, the bug is already fixed. It only occurs in the Xalan
- version bundled with Sun's JVM, because Sun uses a rather old version.
- </p>
- <p>
- Bug description: In a namespace-enabled Level 3 DOM, an attribute in the default namespace must be set with
- <code>"null"</code> as the value for the namespace URI. SAX, on the other side, uses an empty string ("") to designate
- the default namespace. Many packages appear to not properly handle this difference in which case they still use the empty
- string as the namespace URI parameter for <code>org.w3c.dom.Element.setAttributeNS()</code>.
- </p>
- <p>
- Work-around: Use the latest version of Apache Xalan-J. Note that starting with JDK 1.4 it's not enough to replace Xalan-J
- on the normal application classpath and you need to override the Xalan-J version bundled with the Sun JVM using the
- <link href="http://java.sun.com/j2se/1.4.2/docs/guide/standards/">Endorsed Standards Override Mechanism</link>, i.e.
- you must place Xalan-J in the <code>"lib/endorsed"</code> directory of your JRE.
- </p>
- </answer>
- </faq>
- </part>
- <part id="part-pdf">
- <title>PDF specific (includes Acrobat peculiarities)</title>
- <faq id="pdf-embed-font">
- <question>How do I embed fonts in PDF?</question>
- <answer>
- <p>
- See the <link href="0.93/fonts.html">Fonts</link> page for information
- about embedding fonts.
- </p>
- </answer>
- </faq>
- <faq id="pdf-characters">
- <question>Some characters are not displayed, or displayed incorrectly, or
- displayed as “#”.</question>
- <answer>
- <p>
- This usually means the selected font doesn't have a glyph
- for the character.
- </p>
- <p>
- The standard text fonts supplied with Acrobat Reader have
- mostly glyphs for characters from the ISO Latin 1 character
- set. For a variety of reasons, even those are not completely
- guaranteed to work, for example you can't use the fi
- ligature from the standard serif font. Check the <link
- href="0.93/output.html#pdf-fonts">overview</link> for the default
- PDF fonts.
- </p>
- <p>
- If you use your own fonts, the font must have a glyph for
- the desired character. Furthermore 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="0.93/fonts.html">embedding fonts</link>.
- </p>
- <p>
- 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>
- <p>See <link href="0.93/output.html#pdf-postprocess">PDF Post-processing</link>.</p>
- </answer>
- </faq>
- <faq id="pdf-security">
- <question>How do I add security features (encryption, disable printing)
- to my PDF document?</question>
- <answer>
- <p>
- See <link href="0.93/pdfencryption.html">PDF Encryption</link>.
- See also <link href="0.93/output.html#pdf-postprocess">PDF Post-processing</link>.
- </p>
- </answer>
- </faq>
- <faq id="pdf-doc-properties">
- <question>How do I add document properties (title, author, etc.) to my
- PDF document?</question>
- <answer>
- <p>See <link href="0.93/output.html#pdf-postprocess">PDF Post-processing</link>.</p>
- </answer>
- </faq>
- <faq id="pdf-watermark">
- <question>How do I add watermarks to my PDF document?</question>
- <answer>
- <p>See <link href="0.93/output.html#pdf-watermark">PDF Watermarks</link>.</p>
- </answer>
- </faq>
- <faq id="pdf-print-contortion">
- <question>The PDF is printed contorted!</question>
- <answer>
- <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 id="pdf-bookmark-display">
- <question>How do I control the Acrobat bookmark display?</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>
- </answer>
- </faq>
- </part>
- <part id="part-iex">
- <title>IEx specific stuff</title>
- <faq id="iex-servlet-multiple">
- <question>The FOP servlet is called multiple times!</question>
- <answer>
- <p>
- This is a problem of Internet Explorer requesting the content several
- times. Please see the <link href="0.93/servlets.html#ie">notes on Internet Explorer</link>
- for more information.
- </p>
- </answer>
- </faq>
- <faq id="iex-pdf-print-from-browser">
- <question>How do I print PDF directly from the browser?</question>
- <answer>
- <p>
- It depends whether you mean "printing to a printer under control of
- the server" or "printing on the client's printer".
- </p>
- <p>
- For the first problem, look at the print servlet in the FOP
- examples. You'll have to gather any printer settings in a HTML form
- and send it to the server.
- </p>
- <p>
- For the second task, you can use some client side script to start
- Acrobat Reader in print mode, or use a Java applet based on the FOP
- print servlet. This depends heavily on the client installation and
- should not relied on except in tightly controlled environments.
- </p>
- <p>
- See also <link href="http://marc.theaimsgroup.com/?l=fop-dev&m=101065988325115&w=2">http://marc.theaimsgroup.com/?l=fop-dev&m=101065988325115&w=2</link>
- </p>
- </answer>
- </faq>
- </part>
- <part id="part-input">
- <title>General questions regarding XSLT, XSLFO, and basic XML</title>
- <faq id="fo-center">
- <question>(FO) How do I vertically center an image or a table (or
- whatever)?</question>
- <answer>
- <p>
- See <link href="fo.html#fo-center-vertical">XSL-FO Vertical Centering</link>.
- </p>
- </answer>
- </faq>
- <faq id="fo-center-table-horizon">
- <question>(FO) How do I center a table horizontally?</question>
- <answer>
- <p>
- See <link href="fo.html#fo-center-table-horizon">XSL-FO Horizontal Centering (Tables)</link>.
- </p>
- </answer>
- </faq>
- <faq id="fo-page-outer">
- <question>(FO) How to get page numbers printed on the "outer side" of the
- page (for books, for example)?</question>
- <answer>
- <p>
- See <link href="fo.html#fo-oddeven">Recto/Verso Static Content Differences</link>.
- </p>
- </answer>
- </faq>
- <faq id="oddeven">
- <question>(FO) How do I use different static content for odd and even
- pages?</question>
- <answer>
- <p>
- See <link href="fo.html#fo-oddeven">Recto/Verso Static Content Differences</link>.
- </p>
- </answer>
- </faq>
- <faq id="fo-first-page-header">
- <question>(FO) How do I get a special header on the first page?</question>
- <answer>
- <p>
- See <link href="fo.html#fo-first-page">Making the First Page Special</link>.
- </p>
- </answer>
- </faq>
- <faq id="fo-omit-headers">
- <question>(FO) How do I omit my headers on a blank page? How do I write
- "This page is left blank" on an intentionally blank page?</question>
- <answer>
- <p>
- See <link href="fo.html#fo-blank-pages">Blank Pages</link>.
- </p>
- </answer>
- </faq>
- <faq id="fo-special-symbols">
- <question>(FO) How do I print an Euro sign, a checkbox or other some other
- special symbols?</question>
- <answer>
- <p>
- See <link href="fo.html#xml-special-chars">Special Characters</link>.
- </p>
- </answer>
- </faq>
- <faq id="fo-preformat">
- <question>(FO) How do I keep linebreaks and hard spaces? How do I get
- preformatted text displayed as expected?</question>
- <answer>
- <p>
- See <link href="fo.html#fo-preformat">Preformatting Content</link>.
- </p>
- </answer>
- </faq>
- <faq id="fo-total-pages">
- <question>(FO) How do I print the total number of pages, for example "page 1
- of 12"</question>
- <answer>
- <p>
- See <link href="fo.html#fo-total-pages">Total Document Pages</link>.
- </p>
- </answer>
- </faq>
- <faq id="fo-region-overlap">
- <question>(FO) The header overlaps body content. The body extends into
- the footer.</question>
- <answer>
- <p>
- See <link href="fo.html#fo-region-align">Aligning Regions</link>.
- </p>
- </answer>
- </faq>
- <faq id="fo-lines">
- <question>(FO) How do I get lines in the document, as separators, side
- bars or folding marks?</question>
- <answer>
- <p>
- See <link href="fo.html#fo-lines">Drawing Lines</link>.
- </p>
- </answer>
- </faq>
- <faq id="fo-validate">
- <question>(FO) How do I validate my FO document?</question>
- <answer>
- <p>
- See <link href="fo.html#fo-validate">Validating XSL-FO</link>.
- </p>
- </answer>
- </faq>
- <faq id="xml-non-breaking-space">
- <question>(XML) How do I get a non-breaking space in FO? There are complaints about <code>&nbsp;</code>.</question>
- <answer>
- <p>
- See <link href="fo.html#xml-special-chars">XML Special Characters</link>.
- </p>
- </answer>
- </faq>
- <faq id="xml-undefined-entities">
- <question>(XML) How do I enter special characters in XML? There are complaints about undefined entities, such as <code>&uuml;</code>, which work in HTML. </question>
- <answer>
- <p>
- See <link href="fo.html#xml-special-chars">XML Special Characters</link>.
- </p>
- </answer>
- </faq>
- <faq id="xml-illegal-entities">
- <question>(XML) There are complaints about illegal characters and entities
- in the input.</question>
- <answer>
- <p>
- See <link href="fo.html#xml-entity-chars">Using HTML Character Names</link>.
- </p>
- </answer>
- </faq>
- <faq id="xml-illegal-chars">
- <question>(XML) There are complaints about illegal bytes or characters in
- the input. There are odd characters in the result.</question>
- <answer>
- <p>
- See <link href="fo.html#xml-encoding">XML Encoding Issues</link>.
- </p>
- </answer>
- </faq>
- <faq id="xslt-current-date">
- <question>(XSLT) How can I use the current date and time in my document?</question>
- <answer>
- <p>See <link href="fo.html#xslt-date">Current Date and Time</link>.</p>
- </answer>
- </faq>
- <faq id="xhtml-to-pdf">
- <question>Can I use FOP to convert XHTML or HTML files to PDF?</question>
- <answer>
- <p>
- You will get better results if you transform your source
- XML directly into XSLFO. It is tempting to use the
- XML->XHTML->XSLFO approach, because this apparently means
- there's only one transformation to maintain, but XHTML
- and publishing grade PDF are dissimilar enough that an
- "generic" XHTML->XSLFO(PDF) usually wont cut it, because
- the XHTML already lacks information from the original XML.
- It may be worthwhile to go from the source XML to an
- intermediate custom XML which on one hand is close enough
- to representation to allow simple transformation to either
- XHTML or XSLFO for most of the structure, but on the other
- hand retains enough semantic from the original XML that
- elements which must be handled differently in the two
- representations can be handled differently. Setting this
- up requires experience and most likely extensive prototyping.
- </p>
- </answer>
- </faq>
- <faq id="xhtml-to-pdf2">
- <question>I know it may be a bad idea to use FOP to convert XHTML or HTML files to PDF, but I want to do it anyway. Are there any tools available to help me?</question>
- <answer>
- <p>
- The <link href="resources.html">FOP Resources page</link> has links
- to a tool called <link href="http://html2fo.sourceforge.net/">html2fo</link>
- which can be used to make such a transformation. In addition, there
- are tools on the Antenna House <link href="http://www.antennahouse.com/XSLsample/XSLsample.htm">XSL-FO Tutorial and Sample</link>
- page.
- </p>
- </answer>
- </faq>
- </part>
- <part id="dev-help">
- <title>Development-related Questions.</title>
- <faq id="doc-mgt">
- <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>. ;-)
- </p>
- </answer>
- </faq>
- </part>
- <part id="part-help">
- <title>General suggestions. How to solve problems.</title>
- <faq id="bugs">
- <question>I think I have found a bug in FOP. What should I do?</question>
- <answer>
- <p>
- See <link href="bugs.html">the Bugs page</link> for information about
- bugs already reported and how to report new ones.
- </p>
- </answer>
- </faq>
- <faq id="postquestions">
- <question>I have questions that are not addressed in this FAQ. Where
- should I post them?</question>
- <answer>
- <ul>
- <li>If your question is a development-related question, please see the <link href="dev/faq.html">Developer FAQs</link>.</li>
- <li>
- If you have a runtime exception or other runtime problem:
- <ul>
- <li>
- double-check the <link href="#part-running">Runtime FAQs</link>.
- </li>
- <li>
- ClassNotFoundException, NoSuchMethodException and
- NoSuchFieldException problems are almost always a problem with
- the local environment. Try to get local help first.
- </li>
- <li>
- Check <link href="bugs.html#issues_existing">Reported Issues</link>
- to see if this is a known problem.
- </li>
- <li>If none of the above apply, post a question to the fop-dev
- mailing list.
- </li>
- </ul>
- </li>
- <li>
- In the case where something works properly with another formatter,
- (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
- list of <link href="bugs.html#issues_existing">Bugs Already Reported</link>.
- If not found there, please post a question on the fop-user mailing list
- or <link href="bugs.html#issues_new">Open a New Bug</link>.
- </li>
- <li>
- Question about how to use FOP, how to perform certain tasks with FOP
- or how to integrate FOP into another application should be posted to
- fop-user.
- </li>
- <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.
- </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. 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 packages.
- </li>
- <li>
- More general questions regarding Java, including deployment, Java
- APIs, classpath issues and property definitions should be redirected
- to some Java specific list.
- </li>
- </ul>
- </answer>
- </faq>
- </part>
- </faqs>
|