From 100b4d202eb56f74bbfbac30785d25612a54e69b Mon Sep 17 00:00:00 2001 From: William Victor Mote Date: Mon, 24 Mar 2003 23:05:10 +0000 Subject: [PATCH] Move developer FAQs to the Developer FAQ document. git-svn-id: https://svn.apache.org/repos/asf/xmlgraphics/fop/trunk@196131 13f79535-47bb-0310-9956-ffa450edef68 --- src/documentation/content/xdocs/dev/faq.xml | 1416 +------------------ src/documentation/content/xdocs/faq.xml | 12 +- 2 files changed, 12 insertions(+), 1416 deletions(-) diff --git a/src/documentation/content/xdocs/dev/faq.xml b/src/documentation/content/xdocs/dev/faq.xml index 16c3b2f19..d4c68e297 100644 --- a/src/documentation/content/xdocs/dev/faq.xml +++ b/src/documentation/content/xdocs/dev/faq.xml @@ -2,1418 +2,24 @@ - - - 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. -

- - - - 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 a base url. For - the command line FOP application, the base is the directory of the - input file, either the FO file or the XML source. If FOP is used - embedded in a servlet you will need to set the base url on - the user agent. -

-

- 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 base URL in a servlet environment? - -

- Use: -

-

- You need to use the FOUserAgent that contains a base url. -

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

- See the Fonts page for information - about embedding fonts. -

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

Answers are that fonts must be available for the output format, and - the selected font must contain glyphs for the desired character. - PDF has a set of defined fonts, other fonts can be embedded following the -instructions. -To find out if the characters you need are in the core fonts then -(todo - find a glyph font table for the fonts). -

-

For example, for most symbols, the symbol font has to be selected - explicitely (in future it should be possible to specify a list of fonts -where it will select the font for the specified character): -

-

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

- - - - 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? + + + Documentation + + How do I get the javadocs for FOP? -

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

+

Currently, the only way to get FOP javadocs is to + Download the source code and then Build + FOP using the ant build task "javadocs".

 - More general questions regarding XSLT and XSLFO and basic XML + Further Help - (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. + I don't see my question addressed here. Are there other FAQs? -

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

Yes. See also the FOP General FAQs.

 diff --git a/src/documentation/content/xdocs/faq.xml b/src/documentation/content/xdocs/faq.xml index 3bf567e7d..9fd96ee01 100644 --- a/src/documentation/content/xdocs/faq.xml +++ b/src/documentation/content/xdocs/faq.xml @@ -1647,17 +1647,6 @@ class rendtest { - - General Developer Questions - - How do I get the javadocs for FOP? - -

Currently, the only way to get FOP javadocs is to - Download the source code and then Build - FOP using the ant build task "javadocs".

- - - General suggestions. How to solve problems. @@ -1674,6 +1663,7 @@ class rendtest { should I post them?
    +
  • If your question is a development-related question, please see the Developer FAQs.
  • If you have a runtime exception or other runtime problem:
      -- 2.39.5