From: Keiron Liddle Date: Thu, 31 Oct 2002 09:37:30 +0000 (+0000) Subject: added Joerg's FAQ and modified dev version X-Git-Tag: Alt-Design-integration-base~367 X-Git-Url: https://source.dussan.org/?a=commitdiff_plain;h=1e2a567b1a53e251eabfd2d8957681fa7ee91625;p=xmlgraphics-fop.git added Joerg's FAQ and modified dev version git-svn-id: https://svn.apache.org/repos/asf/xmlgraphics/fop/trunk@195394 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/src/documentation/content/xdocs/book.xml b/src/documentation/content/xdocs/book.xml index 5d1dc1df9..257c61ae0 100644 --- a/src/documentation/content/xdocs/book.xml +++ b/src/documentation/content/xdocs/book.xml @@ -8,6 +8,7 @@ + diff --git a/src/documentation/content/xdocs/dev/book.xml b/src/documentation/content/xdocs/dev/book.xml index e17c4895d..fc10d5bfa 100644 --- a/src/documentation/content/xdocs/dev/book.xml +++ b/src/documentation/content/xdocs/dev/book.xml @@ -1,16 +1,17 @@ - + - + - - - - - - - - + + + + + + + + + diff --git a/src/documentation/content/xdocs/dev/faq.xml b/src/documentation/content/xdocs/dev/faq.xml new file mode 100644 index 000000000..138416210 --- /dev/null +++ b/src/documentation/content/xdocs/dev/faq.xml @@ -0,0 +1,1419 @@ + + + + + General questions + + What is FOP? + +

+ FOP is a print formatter for XSL formatting + objects. +

+

+ 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. +

+ + + + What can I do with FOP? + +

+ FOP provides both an application and a library that converts an XSL FO + document into paginated output. +

+

+ 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. +

+

+ The library can be used in servlets and other Java applications. +

+ + + + What does "FOP" stand for? + +

+ It's an acronym for Formatting + Object Processor +

+ + + + How does FOP interact with other Apache Projects? + +

+ FOP is distributed with Cocoon as a PDF serializer + for XSL (FO) documents. +

+

+ Batik can be used with + FOP to transcode an SVG + image into a PDF document. +

+ + + + What is XSL? + +

+ XSL is a W3C standard concerned with publishing XML documents. It + consists of two parts: XSLT and XSLFO. The acronym expands to + eXtensible Stylesheet + Language. +

+ + + + What is XSLFO? + +

+ XSLFO is an XML vocabulary that is used to specify a pagination and + other styling for page layout output. The acronym “FO” stands for + Formatting Objects. XSLFO can be + used in conjunction with XSLT to convert + from any XML format into a paginated layout ready for printing or + displaying. +

+

+ 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. +

+

+ Synonyms: XSL FO, XSL (FO), XSL:FO, XSL-FO, Formatting Objects +

+ + + + What is XSLT? + +

+ XSLT describes the transformation of arbitrary XML input into other + XML (like XSLFO), HTML or plain text. The “T” comes from + Transformation. For historical reasons, a + transformation is often also called a “style sheet”. +

+

+ Synonyms: XSL transformation, XSL:T, XSL style sheet. +

+ + + + How can I contribute? + +

+ There is always plenty of things to do. See limitations + and bugzilla. +

+ + + + + Common stumbling blocks + + I get the error: [ERROR]: 'master-reference' for + 'fo:page-sequence'matches no 'simple-page-master' or + 'page-sequence-master' + +

+ FOP was changed to be in accordance with the latest standard + (see XSL + standard).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. +

+

+ See also release notes. +

+ + + + My PNG images don't work. + +

+ 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 download + and install it by yourself. +

+ + + + I get a NoClassDefFound exception. + +

This is typically a problem with your classpath.

+

If you are running FOP from the command line:

+
    +
  • + Use the fop.bat or fop.sh command file from the FOP distribution. + Ensure the directory where FOP and these files have been installed + is the current working directory. +
    • +
  • + If this doesn't help, check whether still all the jar files + mentioned in the classpath in the fop.bat file are in their + respective places. +
    • +
+

+ If you run FOP embedded in your servlet, web application or other Java + application, check the classpath of the application. +

+ + + + I get a NoSuchMethodException or a NoSuchFieldException + exception. + +

+ 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. +

+

+ Incompatible versions of Batik may also cause this problem. Use + the version of Batik that comes with FOP. +

+ + + + I get an OutOfMemoryException. + +

+ FOP can consume quite a bit of memory, even though this has been + continually improved. The memory consumption is partially inherent to + the formatting process and partially caused by implementation + choices. For certain layouts, all FO processors currently on the + market have memory problems. +

+

+ Some hints regarding your document structure: +

+
    +
  • + 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 "page N of TOTAL" 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. +
    • +
  • + Avoid large images, especially if they are scaled down. Scale them + outside of FOP and use the already scaled images for the FOP + run. For many image formats it is mainly the size of the image file + which matters, not width*height, so you can try other means like + using a higher compression rate. +
    • +
  • + Use multiple page sequences. FOP starts rendering after the end of a + page sequence is encountered. While the actual rendering is done + page by page, some memory allocated for other purposes could + possibly be freed after the page sequence has been rendered. +
    • +
  • + 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. +
    • +
+

+ There are also some bugs which cause FOP to go into an nonterminating + loop, which also often results in a memory overflow. A characteristic + symptom are continuous box + overflows. Most of them are triggered by elements not fitting + in the available space, like big images and improperly specified width + of nested block elements. Look for such stuff and correct it. +

+

+ Reducing memory consumption in general and squishing bugs is an + ongoing effort, partially addressed in the redesign. +

+ + + + I get a MalformedURLException. + +

+ What you probably think of as "file names" are usually URLs, in + particular the src attribute of fo:external-graphic. +

+

+ Because usage of URLs is growing, you should make yourself familiar + with it. The relevant specification is RFC 2396. +

+

+ In a nutshell, the correct syntax for an absolute file URL is + file:///some/path/file.ext on Unix and + file:///z:/some/path/file.ext on Windows systems. Note + the triple slash, and also that only forward slashes are used, even on + windows. +

+

+ A relative file URL starts with anything but a slash, and doesn't have + the file: prefix, for example file.ext, + path/file.ext or ../file.ext. The string + file:path/file.ext is not 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. +

+

+ See Understanding URIs and URLs and Understanding + URL resolving. +

+ + + + I get an "[ERROR]: null", or a NullPointerException. + +

+ Most often, you supplied an invalid FO document to FOP. Currently only + very common errors are intercepted and produce a comprehensible error + message. If you forgot container elements like fo:page-sequence or + fo:flow and put blocks and inline elements directly as children of + fo:root or fo:page-sequence, 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 fo:conditional-page-master-reference, check also + whether you got them right. +

+

+ You can use the FOP DTD or FOP Schema to + validate your soure. This will catch most, but still not all problems. +

+

+ If you use XSLT, problems in your style sheet and in your source XML + also often produce a NullPointerException. Run the transformation + separately to check for this, usually you'll get a detailed error + message from the XSLT processor. +

+

+ If you turn on debugging with the "-d" option you may be able to + see more detailed information. +

+ + + + FOP hangs. FOP does not exit. + +

+ 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 FOP does not + exit if a SVG is included. +

+

+ 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 box overflows. After some time, FOP will + crash with an OutOfMemoryException. +

+

+ 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. +

+ + + + FOP runs forever, writing lots of ">" to the log. + +

+ 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. +

+ + + + FOP cannot find a file for fo:external-graphics. + +

+ The src attribute of the fo:external-graphics element takes an URI, + not a file name. +

+

+ 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, baseDir can be set explicitely. If + it's not set, it is usually the current working directory of the + process which runs FOP. +

+

+ See Understanding URIs and URLs and Understanding + URL resolving. +

+ + + + FOP does not find my fonts. + +

+ 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. +

+

+ 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. +

+ + + + Keep-with-next, keep-with-previous, keep-together + don't work. + +

+ 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. +

+

+ The concept is called “blind table”. The table is used for + pure layout reasons and not obvious in the output. +

+

+ An example of an image and the image caption to be kept together: +

+ + + + + + + + + + + + + Image Caption + + + + ]]> + + + + My tables are missing, or missing their content. + +

+ Check for fo:table-body around the rows. FOP doesn't raise an error if + it is omitted, it just drops the content. +

+

+ Also, the fo:table-with-caption element is not implemented, tables + within such an element are dropped too. The DocBook style sheets + generate fo:table-with-caption elements, so watch out. +

+ + + + Text overflowing table cells and the like is not clipped. Long text + flows into adjacent cells/block, obscuring stuff there. + +

+ Clipping as specified by the overflow="hidden" 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 +

+
    +
  • + clip long text, +
    • +
  • + explicit wrapping+clipping, +
    • +
  • + insert zero width spaces (U+200B or ​) to allow FOP to + wrap. +
    • +
+

+ Check the XSL FAQ and the + XSL list + archive for how to perform these tasks. +

+ + + + Page numbers are not properly right aligned. + +

+ This happens for fo:page-number-citation 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. You can try to use a non-proportional font like Courier + to remedy this. However, this is likely to look ugly, and wont fix the + problem completely. +

+ + + + A graphic is not displayed. + +

+ Several possibilities: +

+
    +
  • + The graphic is too large to fit into the intended space. +
    • +
  • + Some image format subclasses can't be handled, try to convert the + graphic to a format subclass known to work. (Sorry, no list of + formats known to work) +
    • +
  • + Something else obscures the graphic, for example stuff from a static + content (very rare, but has happened). +
    • +
+

+ See also supported image formats. +

+ + + + Hyphenation does not work. + +

+ Set the language attribute somewhere. Check whether you use a language + for which hyphenation is supported. Supported languages can be deduced + from the files in the hyph directory of the FOP source distribution. +

+ + + + + Embedding FOP. Using FOP in a servlet + + How do I use FOP in a servlet? + +

Look at the servlet example.

+

+ A rather minimal code snippet to demonstrate the basics: +

+ response.setContentType("application/pdf"); +Driver driver=new Driver( new InputSource("foo.fo"), + response.getOutputStream()); +driver.setRenderer(Driver.RENDER_PDF); +driver.run(); +

+ Caveat: Internet Explorer will not automatically show the PDF. Thats a + well known IEx problem, not with the servlet. You can download the PDF + with IEx and view it later. There are other problems with this code. +

+

+ Please look into Howto embed FOP in a servlet for all + kinds of details. +

+ + + + How do I use FOP in a servlet with an XSLT transformation? + +

+ Use the TraxInputHandler if both the source XML and XSL are read from + files. +

+

+ A demonstration: +

+ response.setContentType("application/pdf"); +XSLTInputHandler input + =new XSLTInputHandler(new File("foo.xml"), new File("foo.xsl")); +Driver driver=new Driver(); +driver.setOutputStream(response.getOutputStream()); +driver.setRenderer(Driver.RENDER_PDF); +driver.render(input.getParser(), input.getInputSource()); +

+ This minimal code snippet has the same problems as the one from the + question above. Please inform yourself about the details. +

+

+ If your source XML is generated on the fly, for example from a + database, a web service, or another servlet, you have to create a + transformer object explicitely and use a SAX event stream to feed the + transformation result into FOP. +

+

+ A demonstration: +

+ response.setContentType("application/pdf"); +Driver driver =new Driver(); +driver.setOutputStream(response.getOutputStream()); +driver.setRenderer(Driver.RENDER_PDF); +Transformer transformer=TransformerFactory.newInstance() + .newTransformer(new StreamSource("foo.xsl")); +transformer.transform(xmlsource, new SAXResult(driver.getContentHandler())); +

+ You don't have to call run() or render() on the driver object. +

+

+ The xmlsource is a placeholder for your actual XML + source. You can supply a new StreamSource( new + StringReader(xmlstring)) if you have to read the XML from a + string. Constructing an XML string and reparse it is not always a good + iea, consider to use a SAXSource if you generate your XML. You can, of + course, supply a DOMSource or whatever you like. You can also use + dynamically generated XSL if you want to. +

+

+ Because you have an explicit transformer object, you can set + parameters for the transformation run too. +

+ + + + How do I pass parameters to the XSLT transformation? + +

+ See the end of the answer for the question above. +

+ + + + How do I use my own fonts when running FOP from a servlet? + +

+ Declare the fonts in the userconfig.xml file as + usual. See loading the user configuration + file for further steps. +

+ + + + How do I set the baseDir property in a servlet environment? + +

+ Use: +

+

+ You need to use the FOUserAgent that contains a base url. + for caveats. +

+ + + + I keep getting NoClassDefFound and other exceptions. How do I + get FOP working for various servlet engines? + +

+ There are various classpath issues, and possible conflicts with + existing XML/XSLT libraries. Because servlet containers often use + their own classloaders for loading webapps, bugs and security problems + can be bothersome as well. +

+

+ Tomcat comes with detailed instructions for installing FOP and Cocoon, + check the documentation. There are known bugs to be circumvented, in + particular in Tomcat 4.0.3. +

+

+ Websphere 3.5: See next question. +

+ + + + FOP in IBM Websphere 3.5 + +

+ Put a copy of a working parser in some directory where WebSphere can + access it, for example, if /usr/webapps/yourapp/servlets is the + classpath for your servlets, copy the Xerces jar into it (any other + directory would also be fine). Do not add the jar to the servlet + classpath, but add it to the classpath of the application server which + contains your web application. In the WebSphere administration + console, click on the "environment" button in the "general" tab. Fill + CLASSPATH in the "variable name" box and + /usr/webapps/yourapp/servlets/Xerces.jar (or whatever your complete + path is) in the value box, press "OK", then apply the change and + restart the application server. +

+ + + + FOP and multithreading + +

+ FOP is not completely thread safe. At the very least you'll have to + create a Driver object for every thread unless you prefer your threads + being blocked. +

+

+ Even though the relevant methods of the Driver object are + synchronized, there are still problems because FOP uses static + variables for configuration data and loading images. Be sure not + to change the configuration data while there is a Driver object + rendering. It is recommended to setup the configuration only + once while initialising the servlet. If you have to change the + configuration data more often, or if you have several servlets + within the same webapp using FOP, consider implementing a + singleton class encapsulating both the configuration settings + and running FOP in synchronized methods. +

+ + + + + Batik/SVG specific questions + + SVG text rendered in bad quality. How do I put SVG text as text + into PDF? + +

+ There is an implementation of a Batik bridge and text painter + that handles SVG text nodes. + If it is possible for this to draw the text as PDF text in the + PDF document then it will do so otherwise the stroking + text painter is used. There are some cases that are not implemented + yet such as tspan and outlined text. See + SVG page for more details. +

+ + + + How do I use FOP with SVG on headless servers? + +

+ Batik uses AWT classes for rendering SVG, which in turn needs an X + server on Unixish systems. If you run a server without X, or if you + can't connect to the X server due to security restrictions or + policies, SVG rendering will fail. +

+

+ There are still several options: +

+
    +
  • + If you are using JDK 1.4, start it with the -Djava.awt.headless=true + command line option. +
    • +
  • + Install a X server which provides an im-memory framebuffer without + actually using a screen device or any display hardware, like Xvfb. +
    • +
  • + Use a toolkit which emulates AWT without the need of an underlying X + server, like PJA. The PJA toolkit is + free and comes with detailed installation instructions. +
    • +
+ + + + FOP does not exit if a SVG is included. + +

+ 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. +

+ + + + Problems with SVG referring to gradients etc. using + "uri(#stuff)" (MalformedURLException or stuff not found) + +

+ This is really a "resolving relative URI" problem with some + twists. The problem is that the #stuff 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: +

+
    +
  • + Put the SVG into a separate file and use it with + fo:external-graphics. +
    • +
  • + 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: + fill="url(file:///c:/refstuff/grad.svg#PurpleToWhite)". +
    • +
  • + Same as above but use a relative URL: + fill="url(grad.svg#PurpleToWhite)". This may be easier + to deploy. +
    • +
  • + Make sure that the reference is valid in the current SVG document. +
    • +
+

+ 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. +

+

+ 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. +

+

See also MalformedURLException

+ + + + + PDF specific (includes Acrobat peculiarities) + + How do I embed fonts in PDF? + +

+ Provide$$$ +

+ + + + Characters not displayed, or displayed incorrectly, or displayed + as "#" + +

Answers are that fonts must be available on the target platform, and + the selected font must contain glyphs for the desired character. +

+

For example, for most symbols, the symbol font has to be selected + explicitely (actually: is this a feature or a bug?): +

+

<fo:inline font-family="Symbol">&#x2205;</fo:inline>

+

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.

+

(Still applicable in 0.20.3?)

+ + + + PDF encryption, PDF protection (read-only) + +

use some other tool to postprocess the PDF (itext, or something?)

+ + + + Watermarks + +

Answer: see 3.3, or use a a region overlapping the flowing text and put + an image there: +

+

> From: Trevor_Campbell@kaz.com.au + Use the region-before. Make it large enough to contain your image and then + include a block (and if required an absolutely positioned block-container) + with your image in the static-content for the region-before. + Could use some code here... +

+ + + + PDF prints contorted + +

Check paper size in Acrobat settings and "fit to page" (or something)

+ + + + Controlling Acrobat bookmark display + +

Not possible with FOP. Postprocess the PDF.

+ + + + PDF (more precise: Acrobat Reader) and IEx + +

see #later

+ + + + + IEx specific stuff + + The FOP servlet is called multiple times. + +

+ This is a problem of Internet Explorer requesting the content several + times. Some suggestions: +

+
    +
  • + Use a URL ending in .pdf, like + http://myserver/servlet/stuff.pdf. 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 + .pdf, if necessary append a dummy parameter, like + http://myserver/servlet/stuff.pdf?par1=a&par2=b&d=.pdf. The + effect may depend on IEx version. +
    • +
  • + Give IEx the opportunity to cache. In particular, ensure the server + does not set any headers causing IEx not to cache the content. This + may be a real problem if the document is sent over HTTPS. Consult + your server manual. +
    • +
  • + Cache in the server. Including a parameter in the URL which has a + timestamp as the value may help you to decide whether a request is + repeated. IEx is reported to retrieve a document up to three times, + but never more often. +
    • +
+ + + + How do I print PDF directly from the browser? + +

+ It depends whether you mean "printing to a printer under control of the + server" or "printing on the client's printer". +

+

+ 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 + and send it to the server. +

+

+ 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. +

+

+ See also http://marc.theaimsgroup.com/?l=fop-dev&m=101065988325115&w=2 +

+ + + + + More general questions regarding XSLT and XSLFO and basic XML + + (FO) How do I vertically center an image or a table (or + whatever)? + +

+ Use display-align="center". FOP implements this for block containers + and table cell. A small self-contained document centering an image on + a page: +

+ + + + + + + + + + + + + + + + + + + + + + + +]]> + + + + (FO) How to get page numbers printed on the "outer side" of the + page (for books, obviously)? + +

+ That's about different static content on odd/even pages. +

+ + + + (FO) How do I get a special header on the first page? + +

+ You can insert it into the flow instead of the static content. + Alternatively, use a page master referring to different page masters + for the first page and the rest. It is quite similar to the odd/even + page mechanism. A code sample: +

+ + + + + + + + + + + + + + + + + + + + + First page. + + + Other page. + + + + + + + +]]> + + + + (FO) Different static content for odd/even pages + +

+ There are examples in the FO distribution and in the XSL FAQ FO + section http://www.dpawson.co.uk/xsl/sect3/index.html +

+

+ Define a page master with alternating pages masters for odd and even + pages, specify appropriate regions in these page masters, and be sure + to give them different names. You use these names to put different + static content in these regions. A self contained document + demonstrating this: +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +]]> + + + + (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? + +

+ A blank page can be forced by a break-before="page-even" + or similar properties, or by a force-page-count="end-on-odd" on a page + sequence, which ensures a new chapter or something starts on the + preferred page. +

+

+ You can define a conditional page master with a page master specific + for blank pages. This allows you to specify static content for blank + pages (by definition, a page is blank if no content from a flow is + rendered on the page). You can omit your normal headers and footers, + and use for example an extended header to print the "..left blank" + statement. +

+ + + + + + + + + + + + + + + + + + + + + Normal footer + + + + Intentionally left blank. + + + + + +]]> + + + + (FO) How to get Euro sign/checkbox/some other stuff + +

+ Try to look it up in the Unicode reference at the Unicode Consortium, in + particular search the reference by + name. Use XML + character references to put the character into your source + XML, XSLT or FO. +

+

+ Watch out for font traps, see #, change font temporarily using + fo:inline if necessary. +

+

+ Alternative: Use an embedded graphic: GIF, PNG, SVG, whatever. +

+ + + + (FO) How do I keep linebreaks/hard spaces? How do I get + preformatted text displayed as expected. + +

+ The specification provides some properties for this: white + space collapsing and line + feed treatment. In FOP, use white-space-collapse="false" on an + enclosing block. This will also preserve line breaks (which is + actually a bug, expect this to be changed). +

+ + + + (FO) How do I print the total number of pages, like in "page 1 + of 12" + +

+ (XSL FAQ) +

+

+ Put an empty block with an id at the end of the flow: +

+ + ... + + ]]> +

+ Get the number of the last page as follows: +

+ ]]> +

+ This does not work for all problems, for example if you have multiple + page sequences, an initial page number different from 1, or if you + force a certain page count, thereby producing blank pages at the end. +

+

+ There is no reliable way to get the real total page count with FO + mechanisms, you can only get page numbers. +

+

+ The FOP library provides a method to get the total page count after a + FO document has been rendered. You can implement your own wrapper to + do a dummy rendering, inquire the total page count and the perform the + real rendering, passing the total page count to the XSLT processor to + splice it into the generated FO. A sample code: +

+ +

+ Declare and use the parameter "page-count" in your XSLT. Be aware you + may run into convergence problems: replacing the "#" placeholder from + the first run by the actual page count may change it. +

+ + + + (FO) The header overlaps body content. The body extends into + footer. + +

+ Contrary to popular opinion, the regions on a page may overlap. + Defining a certain body region does not automatically constrain other + regions, this has to be done explicitely. +

+

+ If you have a header region with an extent of 20mm, you should define + a margin for the body region of at least 20mm too, otherwise the + header content may overwrite some stuff in the body region. This + applies similarly to the extent of the after region and the bottom + margin of the body region. +

+

+ The overlap effect can be used creatively for some purposes. +

+ + + + (FO) How do I get lines in the document, as separators, side + bars or folding marks? + +

+ Several possibilities: +

+
    +
  • + Use fo:leader (look up the details in the XSLFO + specification, or use a book). For horizontal lines only. +
    • +
  • + Use a solid border on a suitable fo:block. Horizontal and vertical + lines only. +
    • +
  • + Insert a graphic. GIF, PNG SVG, whatever. +
    • +
+ + + + (XML) Complaints about &nbsp;. How do I get a non-breaking + space in FO? + +

+ Use &#160; everywhere. In your own XML, you could also use a DTD + which declares the entity. +

+ + + + (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? + +

+ Don't use names as in HTML, use numbers (unless you have a DTD which + declares the entities). For predefined HTML entities and their Unicode + codepoints see Character entity + references in HTML 4 +

+ + + + (XML) There are complaints about illegal characters and entities + in the input. + +

+ Make sure ampersands in text and attributes are written as &amp;, + "<" is written as &lt; and ">" as &gt;. It's not necessary + everywhere but do it just to be sure. +

+

+ The XML parser should give the proper line and possibly column for + offending characters. +

+

+ Refer to the XML specification or to a good tutorial for + details of the XML file format. +

+ + + + (XML) There are complaints about illegal bytes or characters in + the input. There are odd characters in the result. + +

+ Usually, this is a character encoding problem. See XSL FAQ. Many software + 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. +

+ + + + + General suggestions. How to solve problems + + Where to post bugs + +

+ See docs. See also "where to post + questions". +

+ + + + Where to post questions. + +

+ Decide where to post: +

+
    +
  • + 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 bugzilla. If still not found, + post to fop-dev. +
    • +
  • + Something doesn't work with FOP but works with another formatter + (AntennaHouse, PassiveTex). Check whether this is already mentioned + in the release notes, the FOP limitations document or the FAQ. Post + to fop-dev or open a bug on bugzilla. +
    • +
  • + 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. +
    • +
  • + XSLT specific stuff sould go to the XSL + list. This includes problems with the language and XSLT + How-Tos. +
    • +
  • + 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. +
    • +
  • + Problems with servlet containers should be asked on the vendor + specific lists for these software packets. +
    • +
  • + More general questions regarding Java, including deployment, Java + APIs, classpath issues and property definitions should be redirected + to some Java specific list. +
    • +
+ + + + + diff --git a/src/documentation/content/xdocs/faq.xml b/src/documentation/content/xdocs/faq.xml new file mode 100644 index 000000000..8b45b9cd4 --- /dev/null +++ b/src/documentation/content/xdocs/faq.xml @@ -0,0 +1,1462 @@ + + + + + General questions + + What is FOP? + +

+ FOP is a print formatter for XSL formatting + objects. +

+

+ 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. +

+ + + + What can I do with FOP? + +

+ FOP provides both an application and a library that converts an XSL FO + document into paginated output. +

+

+ 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. +

+

+ The library can be used in servlets and other Java applications. +

+ + + + What does "FOP" stand for? + +

+ It's an acronym for Formatting + Object Processor +

+ + + + How does FOP interact with other Apache Projects? + +

+ FOP is distributed with Cocoon as a PDF serializer + for XSL (FO) documents. +

+

+ Batik can be used with + FOP to transcode an SVG + image into a PDF document. +

+ + + + What is XSL? + +

+ XSL is a W3C standard concerned with publishing XML documents. It + consists of two parts: XSLT and XSLFO. The acronym expands to + eXtensible Stylesheet + Language. +

+ + + + What is XSLFO? + +

+ XSLFO is an XML vocabulary that is used to specify a pagination and + other styling for page layout output. The acronym “FO” stands for + Formatting Objects. XSLFO can be + used in conjunction with XSLT to convert + from any XML format into a paginated layout ready for printing or + displaying. +

+

+ 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. +

+

+ Synonyms: XSL FO, XSL (FO), XSL:FO, XSL-FO, Formatting Objects +

+ + + + What is XSLT? + +

+ XSLT describes the transformation of arbitrary XML input into other + XML (like XSLFO), HTML or plain text. The “T” comes from + Transformation. For historical reasons, a + transformation is often also called a “style sheet”. +

+

+ Synonyms: XSL transformation, XSL:T, XSL style sheet. +

+ + + + How can I contribute? + +

+ There is always plenty of things to do. See limitations + and bugzilla. +

+ + + + + Common stumbling blocks + + I get the error: [ERROR]: 'master-reference' for + 'fo:page-sequence'matches no 'simple-page-master' or + 'page-sequence-master' + +

+ FOP was changed to be in accordance with the latest standard + (see XSL + standard).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. +

+

+ See also release notes. +

+ + + + My PNG images don't work. + +

+ 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 download + and install it by yourself. +

+ + + + I get a NoClassDefFound exception. + +

This is typically a problem with your classpath.

+

If you are running FOP from the command line:

+
    +
  • + Use the fop.bat or fop.sh command file from the FOP distribution. + Ensure the directory where FOP and these files have been installed + is the current working directory. +
    • +
  • + If this doesn't help, check whether still all the jar files + mentioned in the classpath in the fop.bat file are in their + respective places. +
    • +
+

+ If you run FOP embedded in your servlet, web application or other Java + application, check the classpath of the application. +

+ + + + I get a NoSuchMethodException or a NoSuchFieldException + exception. + +

+ 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. +

+

+ Incompatible versions of Batik may also cause this problem. Use + the version of Batik that comes with FOP. +

+ + + + I get an OutOfMemoryException. + +

+ FOP can consume quite a bit of memory, even though this has been + continually improved. The memory consumption is partially inherent to + the formatting process and partially caused by implementation + choices. For certain layouts, all FO processors currently on the + market have memory problems. +

+

+ Some hints regarding your document structure: +

+
    +
  • + 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 "page N of TOTAL" 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. +
    • +
  • + Avoid large images, especially if they are scaled down. Scale them + outside of FOP and use the already scaled images for the FOP + run. For many image formats it is mainly the size of the image file + which matters, not width*height, so you can try other means like + using a higher compression rate. +
    • +
  • + Use multiple page sequences. FOP starts rendering after the end of a + page sequence is encountered. While the actual rendering is done + page by page, some memory allocated for other purposes could + possibly be freed after the page sequence has been rendered. +
    • +
  • + 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. +
    • +
+

+ There are also some bugs which cause FOP to go into an nonterminating + loop, which also often results in a memory overflow. A characteristic + symptom are continuous box + overflows. Most of them are triggered by elements not fitting + in the available space, like big images and improperly specified width + of nested block elements. Look for such stuff and correct it. +

+

+ Reducing memory consumption in general and squishing bugs is an + ongoing effort, partially addressed in the redesign. +

+ + + + I get a MalformedURLException. + +

+ What you probably think of as "file names" are usually URLs, in + particular the src attribute of fo:external-graphic. +

+

+ Because usage of URLs is growing, you should make yourself familiar + with it. The relevant specification is RFC 2396. +

+

+ In a nutshell, the correct syntax for an absolute file URL is + file:///some/path/file.ext on Unix and + file:///z:/some/path/file.ext on Windows systems. Note + the triple slash, and also that only forward slashes are used, even on + windows. +

+

+ A relative file URL starts with anything but a slash, and doesn't have + the file: prefix, for example file.ext, + path/file.ext or ../file.ext. The string + file:path/file.ext is not 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. +

+

+ See Understanding URIs and URLs and Understanding + URL resolving. +

+ + + + I get an "[ERROR]: null", or a NullPointerException. + +

+ Most often, you supplied an invalid FO document to FOP. Currently only + very common errors are intercepted and produce a comprehensible error + message. If you forgot container elements like fo:page-sequence or + fo:flow and put blocks and inline elements directly as children of + fo:root or fo:page-sequence, 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 fo:conditional-page-master-reference, check also + whether you got them right. +

+

+ You can use the FOP DTD or FOP Schema to + validate your soure. This will catch most, but still not all problems. +

+

+ If you use XSLT, problems in your style sheet and in your source XML + also often produce a NullPointerException. Run the transformation + separately to check for this, usually you'll get a detailed error + message from the XSLT processor. +

+

+ If you turn on debugging with the "-d" option you may be able to + see more detailed information. +

+ + + + FOP hangs. FOP does not exit. + +

+ 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 FOP does not + exit if a SVG is included. +

+

+ 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 box overflows. After some time, FOP will + crash with an OutOfMemoryException. +

+

+ 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. +

+ + + + FOP runs forever, writing lots of ">" to the log. + +

+ 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. +

+ + + + FOP cannot find a file for fo:external-graphics. + +

+ The src attribute of the fo:external-graphics element takes an URI, + not a file name. +

+

+ 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, baseDir can be set explicitely. If + it's not set, it is usually the current working directory of the + process which runs FOP. +

+

+ See Understanding URIs and URLs and Understanding + URL resolving. +

+ + + + FOP does not find my fonts. + +

+ 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. +

+

+ 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. +

+ + + + Keep-with-next, keep-with-previous, keep-together + don't work. + +

+ 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. +

+

+ The concept is called “blind table”. The table is used for + pure layout reasons and not obvious in the output. +

+

+ An example of an image and the image caption to be kept together: +

+ + + + + + + + + + + + + Image Caption + + + + ]]> + + + + My tables are missing, or missing their content. + +

+ Check for fo:table-body around the rows. FOP doesn't raise an error if + it is omitted, it just drops the content. +

+

+ Also, the fo:table-with-caption element is not implemented, tables + within such an element are dropped too. The DocBook style sheets + generate fo:table-with-caption elements, so watch out. +

+ + + + Text overflowing table cells and the like is not clipped. Long text + flows into adjacent cells/block, obscuring stuff there. + +

+ Clipping as specified by the overflow="hidden" 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 +

+
    +
  • + clip long text, +
    • +
  • + explicit wrapping+clipping, +
    • +
  • + insert zero width spaces (U+200B or &#x200B;) to allow FOP to + wrap. +
    • +
+

+ Check the XSL FAQ and the + XSL list + archive for how to perform these tasks. +

+ + + + Page numbers are not properly right aligned. + +

+ This happens for fo:page-number-citation 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. You can try to use a non-proportional font like Courier + to remedy this. However, this is likely to look ugly, and wont fix the + problem completely. +

+ + + + A graphic is not displayed. + +

+ Several possibilities: +

+
    +
  • + The graphic is too large to fit into the intended space. +
    • +
  • + Some image format subclasses can't be handled, try to convert the + graphic to a format subclass known to work. (Sorry, no list of + formats known to work) +
    • +
  • + Something else obscures the graphic, for example stuff from a static + content (very rare, but has happened). +
    • +
+

+ See also supported image formats. +

+ + + + Hyphenation does not work. + +

+ Set the language attribute somewhere. Check whether you use a language + for which hyphenation is supported. Supported languages can be deduced + from the files in the hyph directory of the FOP source distribution. +

+ + + + + Embedding FOP. Using FOP in a servlet + + How do I use FOP in a servlet? + +

Look at the servlet example.

+

+ A rather minimal code snippet to demonstrate the basics: +

+ response.setContentType("application/pdf"); +Driver driver=new Driver( new InputSource("foo.fo"), + response.getOutputStream()); +driver.setRenderer(Driver.RENDER_PDF); +driver.run(); +

+ Caveat: Internet Explorer will not automatically show the PDF. Thats a + well known IEx problem, not with the servlet. You can download the PDF + with IEx and view it later. There are other problems with this code. +

+

+ Please look into Howto embed FOP in a servlet for all + kinds of details. +

+ + + + How do I use FOP in a servlet with an XSLT transformation? + +

+ Use the TraxInputHandler if both the source XML and XSL are read from + files. +

+

+ A demonstration: +

+ response.setContentType("application/pdf"); +XSLTInputHandler input + =new XSLTInputHandler(new File("foo.xml"), new File("foo.xsl")); +Driver driver=new Driver(); +driver.setOutputStream(response.getOutputStream()); +driver.setRenderer(Driver.RENDER_PDF); +driver.render(input.getParser(), input.getInputSource()); +

+ This minimal code snippet has the same problems as the one from the + question above. Please inform yourself about the details. +

+

+ If your source XML is generated on the fly, for example from a + database, a web service, or another servlet, you have to create a + transformer object explicitely and use a SAX event stream to feed the + transformation result into FOP. +

+

+ A demonstration: +

+ response.setContentType("application/pdf"); +Driver driver =new Driver(); +driver.setOutputStream(response.getOutputStream()); +driver.setRenderer(Driver.RENDER_PDF); +Transformer transformer=TransformerFactory.newInstance() + .newTransformer(new StreamSource("foo.xsl")); +transformer.transform(xmlsource, new SAXResult(driver.getContentHandler())); +

+ You don't have to call run() or render() on the driver object. +

+

+ The xmlsource is a placeholder for your actual XML + source. You can supply a new StreamSource( new + StringReader(xmlstring)) if you have to read the XML from a + string. Constructing an XML string and reparse it is not always a good + iea, consider to use a SAXSource if you generate your XML. You can, of + course, supply a DOMSource or whatever you like. You can also use + dynamically generated XSL if you want to. +

+

+ Because you have an explicit transformer object, you can set + parameters for the transformation run too. +

+ + + + How do I pass parameters to the XSLT transformation? + +

+ See the end of the answer for the question above. +

+ + + + How do I use my own fonts when running FOP from a servlet? + +

+ Declare the fonts in the userconfig.xml file as + usual. See loading the user configuration + file for further steps. +

+ + + + How do I set the baseDir property in a servlet environment? + +

+ Use: +

+ org.apache.fop.configuration.Configuration.put("baseDir","/my/base/dir"); +

+ or +

+ org.apache.fop.configuration.Configuration.put("baseDir","C:\my\base\dir"); +

+ See using a user configuration file + for caveats. +

+ + + + How do I use a user configuration file from a servlet? + +

+ Use: +

+ org.apache.fop.apps.Options options = new Options(new File("userconfig.xml")); +

+ No further reference to the options variable is + necessary. It is recommended to load the user configuration file only + once, preferably in the init() method of the servlet. If + you have multiple servlets running FOP, or if you have to change the + configuration often, it is best to place the configuration changing + code and the FOP driver call into a synchronized method, or perhaps a + singleton class, in order to avoid problems in multithreaded + environments. +

+ + + + I keep getting NoClassDefFound and other exceptions. How do I + get FOP working for various servlet engines? + +

+ There are various classpath issues, and possible conflicts with + existing XML/XSLT libraries. Because servlet containers often use + their own classloaders for loading webapps, bugs and security problems + can be bothersome as well. +

+

+ Tomcat comes with detailed instructions for installing FOP and Cocoon, + check the documentation. There are known bugs to be circumvented, in + particular in Tomcat 4.0.3. +

+

+ Websphere 3.5: See next question. +

+ + + + FOP in IBM Websphere 3.5 + +

+ Put a copy of a working parser in some directory where WebSphere can + access it, for example, if /usr/webapps/yourapp/servlets is the + classpath for your servlets, copy the Xerces jar into it (any other + directory would also be fine). Do not add the jar to the servlet + classpath, but add it to the classpath of the application server which + contains your web application. In the WebSphere administration + console, click on the "environment" button in the "general" tab. Fill + CLASSPATH in the "variable name" box and + /usr/webapps/yourapp/servlets/Xerces.jar (or whatever your complete + path is) in the value box, press "OK", then apply the change and + restart the application server. +

+ + + + FOP and multithreading + +

+ FOP is not completely thread safe. At the very least you'll have to + create a Driver object for every thread unless you prefer your threads + being blocked. +

+

+ Even though the relevant methods of the Driver object are + synchronized, there are still problems because FOP uses static + variables for configuration data and loading images. Be sure not + to change the configuration data while there is a Driver object + rendering. It is recommended to setup the configuration only + once while initialising the servlet. If you have to change the + configuration data more often, or if you have several servlets + within the same webapp using FOP, consider implementing a + singleton class encapsulating both the configuration settings + and running FOP in synchronized methods. +

+ + + + + Batik/SVG specific questions + + SVG text rendered in bad quality. How do I put SVG text as text + into PDF? + +

+ The svg text is rendered as shapes, the Acrobat viewer displays it + with bad quality unless you turn on smooth line art in the Acrobat + preferences. The printout is always ok, it's only the screen view + which is of bad quality by default. +

+

+ You can force Batik not to render SVG text by setting the + strokeSVGText property to false. You can do this in the user + configuration file: +

+ + strokeSVGText + false +]]> +

+ In a servlet environment, you can set it directly: +

+ org.apache.fop.configuration.Configuration.put("strokeSVGText", Boolean.FALSE); +

+ See also using a user configuration file + in a servlet. +

+ + + + How do I use FOP with SVG on headless servers? + +

+ Batik uses AWT classes for rendering SVG, which in turn needs an X + server on Unixish systems. If you run a server without X, or if you + can't connect to the X server due to security restrictions or + policies, SVG rendering will fail. +

+

+ There are still several options: +

+
    +
  • + If you are using JDK 1.4, start it with the -Djava.awt.headless=true + command line option. +
    • +
  • + Install a X server which provides an im-memory framebuffer without + actually using a screen device or any display hardware, like Xvfb. +
    • +
  • + Use a toolkit which emulates AWT without the need of an underlying X + server, like PJA. The PJA toolkit is + free and comes with detailed installation instructions. +
    • +
+ + + + FOP does not exit if a SVG is included. + +

+ 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. +

+ + + + Problems with SVG referring to gradients etc. using + "uri(#stuff)" (MalformedURLException or stuff not found) + +

+ This is really a "resolving relative URI" problem with some + twists. The problem is that the #stuff 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: +

+
    +
  • + Put the SVG into a separate file and use it with + fo:external-graphics. +
    • +
  • + 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: + fill="url(file:///c:/refstuff/grad.svg#PurpleToWhite)". +
    • +
  • + Same as above but use a relative URL: + fill="url(grad.svg#PurpleToWhite)". This may be easier + to deploy. +
    • +
  • + Make sure that the reference is valid in the current SVG document. +
    • +
  • + **DOES THIS WORK** + Let the URL refer to some location where the gradient could be + retrieved, for example if the SVG code is embedded in your XSL, + try fill="url(my.xsl#PurpleToWhite)". +
    • +
+

+ 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. +

+

+ 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. +

+

See also MalformedURLException

+ + + + + PDF specific (includes Acrobat peculiarities) + + How do I embed fonts in PDF? + +

+ Provide$$$ +

+ + + + Characters not displayed, or displayed incorrectly, or displayed + as "#" + +

Answers are that fonts must be available on the target platform, and + the selected font must contain glyphs for the desired character. +

+

For example, for most symbols, the symbol font has to be selected + explicitely (actually: is this a feature or a bug?): +

+

<fo:inline font-family="Symbol">&#x2205;</fo:inline>

+

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.

+

(Still applicable in 0.20.3?)

+ + + + PDF encryption, PDF protection (read-only) + +

use some other tool to postprocess the PDF (itext, or something?)

+ + + + Watermarks + +

Answer: see 3.3, or use a a region overlapping the flowing text and put + an image there: +

+

> From: Trevor_Campbell@kaz.com.au + Use the region-before. Make it large enough to contain your image and then + include a block (and if required an absolutely positioned block-container) + with your image in the static-content for the region-before. + Could use some code here... +

+ + + + PDF prints contorted + +

Check paper size in Acrobat settings and "fit to page" (or something)

+ + + + Controlling Acrobat bookmark display + +

Not possible with FOP. Postprocess the PDF.

+ + + + PDF (more precise: Acrobat Reader) and IEx + +

see #later

+ + + + + IEx specific stuff + + The FOP servlet is called multiple times. + +

+ This is a problem of Internet Explorer requesting the content several + times. Some suggestions: +

+
    +
  • + Use a URL ending in .pdf, like + http://myserver/servlet/stuff.pdf. 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 + .pdf, if necessary append a dummy parameter, like + http://myserver/servlet/stuff.pdf?par1=a&par2=b&d=.pdf. The + effect may depend on IEx version. +
    • +
  • + Give IEx the opportunity to cache. In particular, ensure the server + does not set any headers causing IEx not to cache the content. This + may be a real problem if the document is sent over HTTPS. Consult + your server manual. +
    • +
  • + Cache in the server. Including a parameter in the URL which has a + timestamp as the value may help you to decide whether a request is + repeated. IEx is reported to retrieve a document up to three times, + but never more often. +
    • +
+ + + + How do I print PDF directly from the browser? + +

+ It depends whether you mean "printing to a printer under control of the + server" or "printing on the client's printer". +

+

+ 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 + and send it to the server. +

+

+ 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. +

+

+ See also http://marc.theaimsgroup.com/?l=fop-dev&m=101065988325115&w=2 +

+ + + + + More general questions regarding XSLT and XSLFO and basic XML + + (FO) How do I vertically center an image or a table (or + whatever)? + +

+ Use display-align="center". FOP implements this for block containers + and table cell. A small self-contained document centering an image on + a page: +

+ + + + + + + + + + + + + + + + + + + + + + + +]]> + + + + (FO) How to get page numbers printed on the "outer side" of the + page (for books, obviously)? + +

+ That's about different static content on odd/even pages. +

+ + + + (FO) How do I get a special header on the first page? + +

+ You can insert it into the flow instead of the static content. + Alternatively, use a page master referring to different page masters + for the first page and the rest. It is quite similar to the odd/even + page mechanism. A code sample: +

+ + + + + + + + + + + + + + + + + + + + + First page. + + + Other page. + + + + + + + +]]> + + + + (FO) Different static content for odd/even pages + +

+ There are examples in the FO distribution and in the XSL FAQ FO + section http://www.dpawson.co.uk/xsl/sect3/index.html +

+

+ Define a page master with alternating pages masters for odd and even + pages, specify appropriate regions in these page masters, and be sure + to give them different names. You use these names to put different + static content in these regions. A self contained document + demonstrating this: +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +]]> + + + + (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? + +

+ A blank page can be forced by a break-before="page-even" + or similar properties, or by a force-page-count="end-on-odd" on a page + sequence, which ensures a new chapter or something starts on the + preferred page. +

+

+ You can define a conditional page master with a page master specific + for blank pages. This allows you to specify static content for blank + pages (by definition, a page is blank if no content from a flow is + rendered on the page). You can omit your normal headers and footers, + and use for example an extended header to print the "..left blank" + statement. +

+ + + + + + + + + + + + + + + + + + + + + Normal footer + + + + Intentionally left blank. + + + + + +]]> + + + + (FO) How to get Euro sign/checkbox/some other stuff + +

+ Try to look it up in the Unicode reference at the Unicode Consortium, in + particular search the reference by + name. Use XML + character references to put the character into your source + XML, XSLT or FO. +

+

+ Watch out for font traps, see #, change font temporarily using + fo:inline if necessary. +

+

+ Alternative: Use an embedded graphic: GIF, PNG, SVG, whatever. +

+ + + + (FO) How do I keep linebreaks/hard spaces? How do I get + preformatted text displayed as expected. + +

+ The specification provides some properties for this: white + space collapsing and line + feed treatment. In FOP, use white-space-collapse="false" on an + enclosing block. This will also preserve line breaks (which is + actually a bug, expect this to be changed). +

+ + + + (FO) How do I print the total number of pages, like in "page 1 + of 12" + +

+ (XSL FAQ) +

+

+ Put an empty block with an id at the end of the flow: +

+ + ... + + ]]> +

+ Get the number of the last page as follows: +

+ ]]> +

+ This does not work for all problems, for example if you have multiple + page sequences, an initial page number different from 1, or if you + force a certain page count, thereby producing blank pages at the end. +

+

+ There is no reliable way to get the real total page count with FO + mechanisms, you can only get page numbers. +

+

+ The FOP library provides a method to get the total page count after a + FO document has been rendered. You can implement your own wrapper to + do a dummy rendering, inquire the total page count and the perform the + real rendering, passing the total page count to the XSLT processor to + splice it into the generated FO. A sample code: +

+ +

+ Declare and use the parameter "page-count" in your XSLT. Be aware you + may run into convergence problems: replacing the "#" placeholder from + the first run by the actual page count may change it. +

+ + + + (FO) The header overlaps body content. The body extends into + footer. + +

+ Contrary to popular opinion, the regions on a page may overlap. + Defining a certain body region does not automatically constrain other + regions, this has to be done explicitely. +

+

+ If you have a header region with an extent of 20mm, you should define + a margin for the body region of at least 20mm too, otherwise the + header content may overwrite some stuff in the body region. This + applies similarly to the extent of the after region and the bottom + margin of the body region. +

+

+ The overlap effect can be used creatively for some purposes. +

+ + + + (FO) How do I get lines in the document, as separators, side + bars or folding marks? + +

+ Several possibilities: +

+
    +
  • + Use fo:leader (look up the details in the XSLFO + specification, or use a book). For horizontal lines only. +
    • +
  • + Use a solid border on a suitable fo:block. Horizontal and vertical + lines only. +
    • +
  • + Insert a graphic. GIF, PNG SVG, whatever. +
    • +
+ + + + (XML) Complaints about &nbsp;. How do I get a non-breaking + space in FO? + +

+ Use &#160; everywhere. In your own XML, you could also use a DTD + which declares the entity. +

+ + + + (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? + +

+ Don't use names as in HTML, use numbers (unless you have a DTD which + declares the entities). For predefined HTML entities and their Unicode + codepoints see Character entity + references in HTML 4 +

+ + + + (XML) There are complaints about illegal characters and entities + in the input. + +

+ Make sure ampersands in text and attributes are written as &amp;, + "<" is written as &lt; and ">" as &gt;. It's not necessary + everywhere but do it just to be sure. +

+

+ The XML parser should give the proper line and possibly column for + offending characters. +

+

+ Refer to the XML specification or to a good tutorial for + details of the XML file format. +

+ + + + (XML) There are complaints about illegal bytes or characters in + the input. There are odd characters in the result. + +

+ Usually, this is a character encoding problem. See XSL FAQ. Many software + 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. +

+ + + + + General suggestions. How to solve problems + + Where to post bugs + +

+ See docs. See also "where to post + questions". +

+ + + + Where to post questions. + +

+ Decide where to post: +

+
    +
  • + 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 bugzilla. If still not found, + post to fop-dev. +
    • +
  • + Something doesn't work with FOP but works with another formatter + (AntennaHouse, PassiveTex). Check whether this is already mentioned + in the release notes, the FOP limitations document or the FAQ. Post + to fop-dev or open a bug on bugzilla. +
    • +
  • + 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. +
    • +
  • + XSLT specific stuff sould go to the XSL + list. This includes problems with the language and XSLT + How-Tos. +
    • +
  • + 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. +
    • +
  • + Problems with servlet containers should be asked on the vendor + specific lists for these software packets. +
    • +
  • + More general questions regarding Java, including deployment, Java + APIs, classpath issues and property definitions should be redirected + to some Java specific list. +
    • +
+ + + + diff --git a/src/documentation/sitemap.xmap b/src/documentation/sitemap.xmap index a77988406..06da4d18d 100644 --- a/src/documentation/sitemap.xmap +++ b/src/documentation/sitemap.xmap @@ -229,6 +229,18 @@ + + + + + + + + + + + +