FOP: Building from Source Code

Do You Need To Build?

FOP distributions are either pre-compiled binary or source. If you are using a binary distribution, it is already built and there is no need to build it again. See the Download Instructions for information about whether a binary or source distribution is best for your needs.

Set Up Your Environment -

JDK

- Building FOP requires a minimum Java Development Kit (JDK) of 1.3. + Building FOP requires a minimum Java Development Kit (JDK/SDK) of 1.3 + (A Java Runtime Environment ist not sufficient)

CLASSPATH

There is no generally no need to setup a classpath. All libraries needed to compile FOP are included in the source distribution and are referenced by the build script. You will only need to adjust the classpath if you build FOP in some other way. See the build scripts (build.bat for Windows, and build.sh for Unix) for details.

JAVA_HOME

Ant, which is used by the build script, requires that the environment variable JAVA_HOME point to your local JDK root directory. This is true even if you use JDK 1.2 or above, which normally don't need this setting.

Run the "build" Script

Build FOP by executing the "build" script, which is located in the FOP root directory. The Windows batch file is build.bat, and the Unix shell script is build.sh. @@ -59,8 +60,8 @@ To obtain a complete list of useful build targets:

To clean the build directory first:

build.sh clean package

- Troubleshooting +

+ Troubleshooting

If you have problems building FOP, please try the following:

Run the build with the target of "clean", then rerun the build.

- font-family lists are not suppported, use a single font-family name + font-family lists are not supported, use a single font-family name

@@ -299,8 +299,12 @@ want it to.

- - + + Only start, end, center and justify are supported + + + Only start, end, center and justify are supported +

diff --git a/src/documentation/content/xdocs/configuration.xml b/src/documentation/content/xdocs/configuration.xml index 804e50406..a8d8576eb 100644 --- a/src/documentation/content/xdocs/configuration.xml +++ b/src/documentation/content/xdocs/configuration.xml @@ -4,62 +4,83 @@

- Configuration + FOP: Configuration

- How to configure FOP -

In the directory xml-fop/conf you will find two configuration files. One of them, - config.xml, is only intended for FOP developers, who want to add new default values - to some FOP feature. Don't change this file. For user configuration there is a file called - userconfig.xml. It contains templates for all settings a user can change. Most of them are - commented out. Uncomment the entry you want to set and change the value according to - your wishes. Please regard any comments which specify the value range. And, well, the - configuration files are xml files, so keep them at least well-formed. ;-) -

The file userconfig.xml is not read automatically, but the user must specify its use on - the command line. See Running FOP - or Embedding FOP for details. -

+ Configuration File Basics +

The FOP configuration file is an XML file containing a variety of settings that are useful for controlling FOP's behavior, and for helping it find resources that you wish it to use.

The easiest way to get started using a FOP configuration file is to copy the sample found at {fop-dir}/conf/userconfig.xml to a location of your choice, and then to edit it according to your needs. +It contains templates for the various configuration options, most of which are commented out. Remove the comments and change the settings for entries that you wish to use. +Be sure to follow any instructions, including comments which specify the value range. +Also, since the configuration file is XML, be sure to keep it well-formed.

+ Do not change {fop-dir}/conf/config.xml or use it as the basis for your configuration file. It has an entirely different purpose. +

+ Creating Entries +

The general structure of the configuration file is a series of <entry> tags, each containing a <key> and a <value>. (Fonts use a different format). Here is an example:

+ + strokeSVGText + false +]]> +

+ Making Configuration Available to FOP +

After creating your configuration file, you must tell FOP how to find it:

If running FOP from the command-line, see the "-c" command-line option in Running FOP.
If running FOP as an embedded application, see FOP: Embedding, Using a Configuration File.

See Setting the Configuration Programmatically for instructions on how to do so in an embedded environment.

- Setting up hyphenation -

FOP comes already with some hyphenation pattern. If you need a hyphenation pattern - which isn't included in the distribution, do the following: -

-Get the TeX hyphenation pattern file and turn it into an xml file which -conforms to the hyphenation.dtd in the subdirectory /src/hyph. -
-Name this new file following this schema: languageCode_countryCode.xml. If -you don't need a country code, leave it out, e.g the file name for an American -english hyphenation pattern would look like this: en_US.xml. For an Italian -file: it.xml. Language and country codes must be the same as in xsl:fo, that -is follow -ISO 639 -and -ISO 3166 -respectively. NOTE: The ISO 639/ISO 3166 convention is that language names are -written in lower case, while country codes are written in upper case. -
-If you have build your new hyphenation pattern file successfully there are -two ways to make it accessible to FOP. -
- -Put this new file into the directory /src/hyph and rebuild FOP. The file will -be picked up and added to the fop.jar. -
- -Put the file into a directory of your choice and specify this directory -in the userconfig.xml in the entry <hyphenation-dir>. -
-

+ Summary of Key-Value Configuration Options + + + + + + + + + + + + + + + + + + + + + + + + + + +

Option (key)	Data Type (for the value)	Default Value
baseDir	URL	For command-line, the directory containing the input FO or XML file. For embedded, the current working directory.
fontBaseDir	URL	value of baseDir
hyphenation-dir	URL	None. This is for custom hyphenation patterns.
strokeSVGText	Boolean	True

+ Detail for Key-Value Configuration Options +

The sections below provide detailed information for configuration options that are not self-explanatory. The parenthetical information after each key name indicates (Data Type, Default).

+ hyphenation-dir (URL, none) +

Use this entry to indicate a directory containing custom hyphenation files (if any). +See FOP: Hyphenation for more information on creating and modifying hyphenation within FOP.

+ strokeSVGText (boolean, True) +

In some cases, some text in SVG documents is converted to graphical shapes instead of retaining its character as text. To force all text to be rendered as text, set strokeSVGText = false. For a discussion of this issue, see FOP: Graphics, Placing SVG Text into PDF.

+ strokeSVGText is currently only effective in the PDF renderer. +

+ Fonts +

Font configuration information is included in the FOP configuration file, but is documented at FOP: Fonts. Note especially the section entitled Register Fonts with FOP.

diff --git a/src/documentation/content/xdocs/dev/api-doc.xml b/src/documentation/content/xdocs/dev/api-doc.xml index f47472a05..a52551901 100644 --- a/src/documentation/content/xdocs/dev/api-doc.xml +++ b/src/documentation/content/xdocs/dev/api-doc.xml @@ -15,7 +15,7 @@

Javadocs for Maintenance Branch

Javadocs for Trunk (Redesign)

- If the links return an "Object not found!" message or otherwise do not work properly, it is probably because of a build error. Please raise a question on the fop-user mailing list so that any problems can be fixed before the next build. + If the links return an "Object not found!" message or otherwise do not work properly, it is probably because of a build error. Please raise a question on the fop-user mailing list so that any problems can be fixed before the next build.

Building them Yourself diff --git a/src/documentation/content/xdocs/dev/book.xml b/src/documentation/content/xdocs/dev/book.xml index 19a0f1e16..7d423b287 100644 --- a/src/documentation/content/xdocs/dev/book.xml +++ b/src/documentation/content/xdocs/dev/book.xml @@ -11,7 +11,8 @@ - + +

diff --git a/src/documentation/content/xdocs/dev/doc.xml b/src/documentation/content/xdocs/dev/doc.xml index c58ea80f4..1b2f55f01 100644 --- a/src/documentation/content/xdocs/dev/doc.xml +++ b/src/documentation/content/xdocs/dev/doc.xml @@ -19,6 +19,22 @@ The major exception to this rule is the design doc, which currently exclusively Maintenance branch releases either copy the trunk content to the maintenance branch or use the trunk content directly for doc builds.

Basic documents are stored in XML files, and use DTDs provided by Apache Forrest.

+ Design Principles +

These principles are not written in stone, but reflect the current philosophy, and are documented here primarily to help achieve consistency. These principles should be changed if better or more practical ones are found, but they should probably be discussed and changed by common consent.

+ Where +

To the extent possible, keep user content separate from developer content, primarily so the user doesn't have to filter out technical information.
To the extent possible, try to document a topic exactly once, in the place the user is most likely to look for it, then link to that from other locations as appropriate. This is somewhat contrary to the principle above, which should be applied as a higher priority.

+ When +

The documentation and the product are in a constant state of change, and there is some difficulty in deciding what product state the website content should reflect. The current thinking is that the website should reflect the current state of the repository code branch from which releases are made. Features or other documentation that applies to unreleased code should be marked in such a way within the content that the user can determine whether and how it applies to the version they are using. For example, "Feature xyz is first available in Release n.nn.n".

Other approaches were considered, but all seemed to have significantly higher costs both to the users and the developers. From the user's standpoint, the choice is either that they potentially have to look multiple places to get the information they need (which was rejected), or they have to filter out an occasional feature that is in code available subsequent to their release (which was accepted).

Website

diff --git a/src/documentation/content/xdocs/dev/extensions.xml b/src/documentation/content/xdocs/dev/extensions.xml index a188d4ad9..561ec256c 100644 --- a/src/documentation/content/xdocs/dev/extensions.xml +++ b/src/documentation/content/xdocs/dev/extensions.xml @@ -38,7 +38,7 @@ They are loaded by FOP when parsing starts to validate input. correct name space. The examples for SVG and pdfoutline.fo show how this can be done. The pdf documents on the FOP site use this extension. -See also Examples for more examples. +See also Examples for more examples.

Put your jar file in the classpath

Run FOP using your XSL-FO file as input.

diff --git a/src/documentation/content/xdocs/dev/index.xml b/src/documentation/content/xdocs/dev/index.xml index 1868faf55..f3ff4f3e7 100644 --- a/src/documentation/content/xdocs/dev/index.xml +++ b/src/documentation/content/xdocs/dev/index.xml @@ -18,7 +18,7 @@ This certainly includes programmers, but may also include those contributing to

The oldest is the one that releases are currently generated from, and is also called the "maintenance branch". Because of limitations in its design, the FOP committers decided to freeze new development on this branch, and are providing only bug fixes. This branch is tagged as "fop-0_20_2-maintain" in the CVS repository.
The main development line is the future of FOP. It was spawned from the "maintenance" branch, but had to quickly be "broken" so that the needed redesign could be dropped into place. It is currently not as mature as the "maintenance" branch, but has far greater long-term prospects. It is also known as the "root" or "trunk" or "redesign".
The "Alt Design" is exactly that: an alternative design approach. Because its efforts are largely complementary and parallel to the main development branch, and because it is expected to be merged at some point into the trunk, it is documented separately. The authors of this effort are currently in the process of merging their work into the trunk.
The "Alt Design" is exactly that: an alternative design approach. Because its efforts are largely complementary and parallel to the main development branch, and because it is expected to be merged at some point into the trunk, it is documented separately. The authors of this effort are currently in the process of merging their work into the trunk.

Please note that patches for enhancements to the maintenance branch will generally not be considered. Bug fixes are welcome there, but new developers are strongly encouraged to apply their efforts to the trunk development line.

Because there is a fair amount of common information between the maintenance and trunk development lines, we attempt to document them together, highlighting differences only where needed.

@@ -57,7 +57,7 @@ This certainly includes programmers, but may also include those contributing to

Understand FOP's Design -

The design for FOP is specified under the Design section. This is where the information on how FOP is developed and designed +

The design for FOP is specified under the Design section. This is where the information on how FOP is developed and designed internally will be kept.

diff --git a/src/documentation/content/xdocs/download.xml b/src/documentation/content/xdocs/download.xml index 765155e75..0e0e0a635 100644 --- a/src/documentation/content/xdocs/download.xml +++ b/src/documentation/content/xdocs/download.xml @@ -20,7 +20,11 @@ However, a source distribution will be preferable if you fall into one of the fo

Binary Download

Binary distributions include "-bin" in their names, and can be downloaded from the FOP Distribution directory. -

+ We're in the process of moving the download location. Please download the + latest release candidate from a + mirror. +

Source Download @@ -38,4 +42,4 @@ Anyone can do this using the - \ No newline at end of file + diff --git a/src/documentation/content/xdocs/embedding.xml b/src/documentation/content/xdocs/embedding.xml index 65bf1a129..d957ee24b 100644 --- a/src/documentation/content/xdocs/embedding.xml +++ b/src/documentation/content/xdocs/embedding.xml @@ -36,231 +36,178 @@

Here is an example use of Driver which outputs PDF:

+Driver driver = new Driver(new InputSource(args[0]), + new FileOutputStream(args[1])); +driver.setRenderer(Driver.RENDER_PDF); +driver.run();]]>

In the example above, args[0] contains the path to an XSL-FO file, while args[1] contains a path for the target PDF file.

You also need to set up logging. Global logging for all FOP - processes is managed by MessageHandler. Per-instance logging - is handled by Driver. You want to set both using an implementation - of org.apache.avalon.framework.logger.Logger. See - below for more information. -

+ Logging +

+ You also need to set up logging. Global logging for all FOP + processes is managed by MessageHandler. Per-instance logging + is handled by Driver. You want to set both using an implementation + of org.apache.avalon.framework.logger.Logger. See + below for more information. +

+ Call setLogger(Logger) always immediately after + instantiating the Driver object. See here: +

+import org.apache.avalon.framework.logger.Logger; +import org.apache.avalon.framework.logger.ConsoleLogger; -

To setup the user config file you can do the following -

+/*..*/ + +Driver driver = new Driver(); +Logger logger = new ConsoleLogger(ConsoleLogger.LEVEL_INFO); +MessageHandler.setScreenLogger(logger); +driver.setLogger(logger);]]> +

+ +

+ Processing XSL-FO +

+ Once the Driver is set up, one of the render() methods + is called. Depending on whether DOM or an InputSource is being used, the + invocation of the method is either render(Document) or + render(Parser, InputSource) respectively. +

+ Another possibility may be used to build the FO Tree: You can + call getContentHandler() and fire the SAX events yourself. + + You don't have to call run() or render() on the + Driver object if you use getContentHandler(). +

Here is an example use of Driver:

- - This is all you need to do, it sets up a static configuration class. - +Driver driver = new Driver(); +//Setup logging here: driver.setLogger(... +driver.setRenderer(Driver.RENDER_PDF); +driver.setInputSource(new FileInputSource(args[0])); +driver.setOutputStream(new FileOutputStream(args[1])); +driver.run();]]> +

Once the Driver is set up, the render method - is called. Depending on whether DOM or SAX is being used, the - invocation of the method is either render(Document) or - render(Parser, InputSource) respectively. -

- Another possibility may be used to build the FO Tree. You can - call getContentHandler() and fire the SAX events yourself. - -

Once the FO Tree is built, the format() and render() methods may be - called in that order. -

Here is an example use of Driver:

- -

You can also specify an xml and xsl file for the input. -

Here is an example use of Driver with the XSLTInputHandler:

- -

Have a look at the classes CommandLineStarter or FopServlet for complete - examples. Also, have a look at the examples at the bottom of this page. -

+ Processing XSL-FO generated from XML+XSLT +

+ If you want to process XSL-FO generated from XML using XSLT we recommend + using standard JAXP to do the XSLT part and piping the generated SAX + events directly through to FOP. Here's how this would look like: +

+ If your XSL-FO files contain SVG then Batik will be used. When Batik is -initialised it uses certain classes in java.awt that -intialises the java AWT classes. This means that a daemon thread -is created by the JVM and on Unix it will need to connect to a -DISPLAY. -The thread means that the Java application will not automatically quit -when finished, you will need to call System.exit(). These -issues should be fixed in the upcoming JDK 1.4 +//Setup Transformer +Source xsltSrc = new StreamSource(xslFile); +TransformerFactory transformerFactory = TransformerFactory.newInstance(); +Transformer transformer = transformerFactory.newTransformer(xsltSrc); +//Start the transformation and rendering process +transformer.transform(src, res);]]> + There's no need to call run() or render(). +

+ This may look complicated at first, but it's really just the combination of an + XSL transformation and a FOP run. It's also easy to comment out the FOP part + for debugging purposes, for example when you're tracking down a bug in your + stylesheet. You can easily write the XSL-FO output from the XSL transformation + to a file to check if that part generates the expected output. +

+ For fully working examples of the above and hints to some interesting + possibilities, see the examples section below. +

Controlling logging -

FOP uses Jakarta Avalon's - Logger - interface to do logging. See the Jakarta Avalon project for more information.

Per default FOP uses the ConsoleLogger which logs to System.out. If you want to do logging using a - logging framework (such as LogKit, Log4J or JDK 1.4 Logging) you can set a - different Logger implementation on the Driver object. Here's an example how you would use LogKit:

+ FOP uses the + Logger package + from Apache Avalon Framework to do logging. See the + Apache Avalon Framework + for more information. +

+ Per default FOP uses the ConsoleLogger which logs to System.out. If you want to do logging using a + logging framework (such as LogKit, Log4J or JDK 1.4 Logging) you can set a + different Logger implementation on the Driver object. Here's an example how you would use LogKit: +

The LogKitLogger class implements the Logger interface so all logging calls are being redirected to LogKit. - More information on Jakarta LogKit can be found here.

Similar implementations exist for Log4J (org.apache.avalon.framework.logger.Log4JLogger) and - JDK 1.4 logging (org.apache.avalon.framework.logger.Jdk14Logger).

If you want FOP to be totally silent you can also set an org.apache.avalon.framework.logger.NullLogger instance.

If you want to use yet another logging facility you simply have to create a class that implements org.apache.avalon.framework.logging.Logger - and set it on the Driver object. See the existing implementations in Avalon Framework for examples.

- Input Sources -

The input XSL-FO document is always handled internally as SAX (see the Parsing Design Document for the rationale). -However, the input itself can be provided in a variety of ways to FOP, which normalizes the input (if necessary) into SAX events:

SAX Events through SAX Handler: FOTreeBuilder is the SAX Handler which is obtained through getContentHandler on Driver.
DOM (which is converted into SAX Events): The conversion of a DOM tree is done via the render(Document) method on Driver.
Data Source (which is parsed and converted into SAX Events): The Driver can take an InputSource as input. -This can use a Stream, String etc.
XML+XSLT Transformation (which is transformed using an XSLT Processor and the result is fired as SAX Events: XSLTInputHandler is used as an InputSource in the render(XMLReader, InputSource) method on Driver.

There are a variety of upstream data manipulations possible. -For example, you may have a DOM and an XSL stylesheet; or you may want to -set variables in the stylesheet. -Interface documentation and some cookbook solutions to these situations are provided in Xalan Basic Usage Patterns.

-See the Examples for some variations on input. -

- Hints -

- Object reuse -

-If FOP is going to be used multiple times within your application -it may be useful to reuse certain objects to save time. -

-The renderers and the driver can both be reused. A renderer is reusable -once the previous render has been completed. The driver is reuseable -after the rendering is complete and the reset method is called. -You will need to setup the driver again with a new OutputStream, -IntputStream and renderer. -

- Getting information on the rendering process -

-To get the number of pages that were rendered by FOP you can call -Driver.getResults(). This returns a FormattingResults object -where you can lookup the number of pages produced. It also gives you the -page-sequences that were produced along with their id attribute and their -number of pages. This is particularly useful if you render multiple -documents (each enclosed by a page-sequence) and have to know the number of -pages of each document. -

- Using FOP in a Servlet -

- Here is a 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(); -

-There are numerous problems with the code snippet above. -Its purpose is only to demonstrate the basic concepts. -See xml-fop/examples/servlet for a working example of FOP used in a servlet. -After building the servlet, drop the fop.war into the webapps directory of Tomcat. -Then access a URL as follows: -

http://localhost:8080/fop/fop?fo=/home/path/to/fofile.fo

http://localhost:8080/fop/fop?xml=/home/path/to/xmlfile.xml&xsl=/home/path/to/xslfile.xsl

The source code for the servlet can be found under xml-fop/examples/servlet/src/FopServlet.java.

- - Some versions of Internet Explorer will not automatically show the PDF. -This is well-known to be a limitation of Internet Explorer, and is not a problem with the servlet. -However, Internet Explorer can still be used to download the PDF so that it can be viewed later. Also, appending ".pdf" to the end of the URL may help. - -

- Using FOP in a Servlet with an XSLT Transformation +driver.setLogger(new org.apache.avalon.framework.logger.LogKitLogger(log));]]>

- If both the source XML and XSL are read from files, use the TraxInputHandler: + The LogKitLogger class implements the Logger interface so all logging calls are being redirected to LogKit. + More information on Jakarta LogKit can be found here.

- 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 code snippet has the same problems as the one from the section above. + Similar implementations exist for Log4J (org.apache.avalon.framework.logger.Log4JLogger) and + JDK 1.4 logging (org.apache.avalon.framework.logger.Jdk14Logger).

- If your source XML is generated on the fly (for example from a database, a web service, or another servlet), create a transformer object explicitly, and use a SAX event stream to feed the transformation result into FOP: + If you want FOP to be totally silent you can also set an org.apache.avalon.framework.logger.NullLogger instance.

- 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. + If you want to use yet another logging facility you simply have to create a class that + implements org.apache.avalon.framework.logging.Logger and set it on the Driver object. + See the existing implementations in Avalon Framework for examples.

+ Input Sources

- The xmlsource is a placeholder for your actual XML source. -If you have to read the XML from a string, supply a new StreamSource(new StringReader(xmlstring)). -Constructing and reparsing an XML string is generally less desirable than using a SAXSource if you generate your XML. -You can alternatively supply a DOMSource as well. -You may also use dynamically generated XSL if you like. + The input XSL-FO document is always handled internally as SAX (see the + Parsing Design Document for the rationale). + However, the input itself can be provided in a variety of ways to FOP, + which normalizes the input (if necessary) into SAX events:

SAX Events through SAX Handler: FOTreeBuilder is the SAX Handler which is obtained through getContentHandler on Driver.
DOM (which is converted into SAX Events): The conversion of a DOM tree is done via the render(Document) method on Driver.
Data Source (which is parsed and converted into SAX Events): The Driver can take an InputSource as input. +This can use a Stream, String etc.
XML+XSLT Transformation (which is transformed using an XSLT Processor and the result is fired as SAX Events: XSLTInputHandler is used as an InputSource in the render(XMLReader, InputSource) method on Driver.

- Because you have an explicit transformer object, you can also use it to explicitly set parameters for the transformation run. + There are a variety of upstream data manipulations possible. + For example, you may have a DOM and an XSL stylesheet; or you may want to + set variables in the stylesheet. Interface documentation and some cookbook + solutions to these situations are provided in + Xalan Basic Usage Patterns. +

+ See the Examples for some variations on input.

@@ -268,9 +215,19 @@ You may also use dynamically generated XSL if you like.

To access an external configuration:

- org.apache.fop.apps.Options options = new Options(new File("userconfig.xml")); + + + This is all you need to do, it sets up a static configuration class. +

No further reference to the options variable is necessary. + The "options = " is actually not even necessary.

See Multithreading FOP for issues related to changing configuration in a multithreaded environment. @@ -290,6 +247,82 @@ You may also use dynamically generated XSL if you like. See Multithreading FOP for issues related to changing configuration in a multithreaded environment.

+ Hints +

+ Object reuse +

+If FOP is going to be used multiple times within your application +it may be useful to reuse certain objects to save time. +

+The renderers and the driver can both be reused. A renderer is reusable +once the previous render has been completed. The driver is reuseable +after the rendering is complete and the reset() method is called. +You will need to setup the driver again with a new OutputStream, +IntputStream and renderer. +

+ AWT issues +

+ If your XSL-FO files contain SVG then Batik will be used. When Batik is + initialised it uses certain classes in java.awt that + intialises the java AWT classes. This means that a daemon thread + is created by the JVM and on Unix it will need to connect to a + DISPLAY. +

+ The thread means that the Java application may not automatically quit + when finished, you will need to call System.exit(). These + issues should be fixed in the upcoming JDK 1.4. +

+ If you run into trouble running FOP on a head-less server, please see the + notes on Batik. +

+ Getting information on the rendering process +

+To get the number of pages that were rendered by FOP you can call +Driver.getResults(). This returns a FormattingResults object +where you can lookup the number of pages produced. It also gives you the +page-sequences that were produced along with their id attribute and their +number of pages. This is particularly useful if you render multiple +documents (each enclosed by a page-sequence) and have to know the number of +pages of each document. +

+ Improving performance +

+ There are several options to consider: +

+ Whenever possible, try to use SAX to couple the individual components involved + (parser, XSL transformer, SQL datasource etc.). +
+ Depending on the target OutputStream (in case of an FileOutputStream, but not + for a ByteArrayOutputStream, for example) it may improve performance considerably + if you buffer the OutputStream using a BufferedOutputStream: + driver.setOutputStream(new java.io.BufferedOutputStream(out)); +
+ Make sure you properly close the OutputStream when FOP is finished. +
+ Cache the stylesheet. If you use the same stylesheet multiple times + you can setup a JAXP Templates object and reuse it each time you do + the XSL transformation. +
+ Use an XSLT compiler like XSLTC that comes with Xalan-J. +

Multithreading FOP

@@ -299,44 +332,26 @@ variables for configuration data and loading images. Here are some tips to mitigate these problems:

To avoid having your threads blocked, create a Driver object for each thread.
If possible, do not change the configuration data while there is a Driver object rendering. -Setup the configuration only once, preferably in the init() method of the servlet. +
+ To avoid having your threads blocked, create a Driver object for each thread.
If you must change the configuration data more often, or if you have multiple servlets within the same webapp using FOP, consider implementing a singleton class to encapsulate the configuration settings and to run FOP in synchronized methods. +
+ If possible, do not change the configuration data while there is a Driver object rendering. + Setup the configuration only once, preferably in the init() method of the servlet. +
+ If you must change the configuration data more often, or if you have multiple + servlets within the same webapp using FOP, consider implementing a singleton + class to encapsulate the configuration settings and to run FOP in synchronized methods.

- Servlet Engines -

- When using a servlet engine, there are potential CLASSPATH issues, and potential conflicts with existing XML/XSLT libraries. -Servlet containers also often use their own classloaders for loading webapps, which can cause bugs and security problems. -

- Tomcat -

- Check Tomcat's documentation for detailed instructions about installing FOP and Cocoon. -There are known bugs that must be addressed, particularly for Tomcat 4.0.3. -

- 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. -In the "variable name" box, enter "CLASSPATH". -In the "value" box, enter the correct path to the parser jar file (/usr/webapps/yourapp/servlets/Xerces.jar in our example here). -Press "OK", then apply the change and restart the application server. -

There is also a known issue with fonts being jumbled between threads when using the AWT renderer (which is used by the -awt and -print output options). +In general, you cannot safely run multiple threads through the AWT renderer.

Examples

-The directory "xml-fop/examples/embedding" contains several working examples. +The directory "{fop-fir}/examples/embedding" contains several working examples. In contrast of the examples above the examples here primarily use JAXP for XML access. This may be easier to understand for people familiar with JAXP.

diff --git a/src/documentation/content/xdocs/examples.xml b/src/documentation/content/xdocs/examples.xml index e0e6aed0b..321e563e6 100644 --- a/src/documentation/content/xdocs/examples.xml +++ b/src/documentation/content/xdocs/examples.xml @@ -7,6 +7,11 @@ Examples +

+ Example Documents Using FOP +

+ These examples have been rendered using FOP: +

@@ -20,10 +25,7 @@

Generated examples
fonts.fo.pdf

- -

- Examples in the distribution -

Examples for the use of XSL-FO can be found in the FOP distribution in +

Other basic examples on the use of XSL-FO can be found in the FOP distribution in the subdirectory xml-fop/examples/fo. You can start transformation of all fo files into pdf files by starting xml-fop/examples/fo/runtests (only source distribution). The resulting test files can be found in xml-fop/examples/fo/tests @@ -57,18 +59,66 @@

readme.fo - uses an old version of FOP documentation for a longer example

- -

Look also into the directory examples/fo/svg. There you find some very extensive SVG examples. -

In the directory examples/fo/pagination you find a suite of examples showing the use - of XSL-FO pagination. -

Also, in the directory examples/fo/pagination you will find a suite of examples showing the use + of XSL-FO pagination. +

Developers will find the first steps to a test suite for all implemented formatting objects and properties in xml-fop/test/xml/.

+ Images Examples +

+Embedding images in FO: +

+ + + + + + + + + + + + + + + + + + + + + + +

Images in FO
description	fo file	pdf result
align in larger viewport	align.fo	align.fo.pdf
align in smaller viewport	align2.fo	align2.fo.pdf
scaling image	size.fo	size.fo.pdf

Look also into the directory examples/fo/svg. There you find some very extensive SVG examples. +

+ Instream Foreign Object Examples +

+Instream Foreign Object images in FO, there are more on the +SVG Page: +

+ + + + + + + + + + + + +

Embedding instream-foreign-object
description	fo file	pdf result
embedding svg in viewport	embed.fo	embed.fo.pdf

diff --git a/src/documentation/content/xdocs/faq.xml b/src/documentation/content/xdocs/faq.xml index 5559dda05..7064e3417 100644 --- a/src/documentation/content/xdocs/faq.xml +++ b/src/documentation/content/xdocs/faq.xml @@ -138,22 +138,21 @@ definitions.

- See also release notes. + Update your FO documents and style sheets.

I get a NoClassDefFound exception. -

- This is typically a problem with your classpath.

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. + Use the fop.bat or fop.sh command file from the FOP + distribution. If you have a FOP version older than 0.20.5, + ensure the directory where FOP and these files have been + installed is the current working directory.
If this doesn't help, check whether still all the jar files @@ -162,8 +161,11 @@

- If you run FOP embedded in your servlet, web application or other - Java application, check the classpath of the application. + If you run FOP embedded in your servlet, web application or + other Java application, check the classpath of the + application. Check the also the information pertaining servlet engines + for further hints.

@@ -248,7 +250,7 @@

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

@@ -307,22 +309,7 @@ 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. -

- +

The src attribute of the fo:external-graphics element requires a URI, not a file name. See External Resources for more information about specifying URIs.

@@ -330,7 +317,7 @@

Did you get: «Failed to read font metrics file C:\foo\arial.xml - : File "C:\foo\arial.xml" not found²? The value for the + : 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.

@@ -339,11 +326,51 @@ directory you expect. Currently FOP does not use the baseDir for resolving relative URLs pointing to font metric files.

+ Try also setting the fontBaseDir configuration. (FIXME: add + link to congfiguration page) +

Problems with FOP output + + Leaders don't work anymore in 0.20.5. Instead of + filling the line, only three dots or a short ruler is + output. + +

+ Leaders still work, in fact they work better than ever + before. You'll just have to add text-align="justify" and/or + text-align-last="justify" to the block with the leader. Be + sure you haven't accidentally overridden the + leader-length.maximum="100%" default value. +

+ Earlier versions of FOP used to expand a leader to fill the + rest of the line unconditionally, anything following it, + like page numbers in a TOC, was actually shifted beyong the + right margin. +

+ The new implementation uses leader-length.optimum to + determine where to break the line, and expands the leader + only further if the line should be filled, as indicated by + the text-aling and text-align-last properties. +

+ Actually due to the fuzzyness of the specification both the + old and the new method are conformant (although adding text + after the expanded leader in the old variant never was). +

+ If you want to have a longer ruler or space in a + non-justified line, you have to increase the + leader-length.optimum property. +

+ + Why does FOP insert a blank page between my page sequences? @@ -488,27 +515,38 @@ Any easy way to check this is to cut&paste the source URL from the fo:extern 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. + 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.

- 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. + The most recent FOP releases should have this problem + fixed. Check whether you can upgrade.

- + 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. + Set the language attribute somewhere and explicitly enable hyphenation. + Check whether you use a language for which hyphenation is supported. + Supported languages can be deduced from the files in the {fop-dir}/src/hyph + directory of the FOP source distribution. If you want to use a language + FOP currently doesn't hyphenate, please see the + Configuration page. +

+ Set the language (on fo:page-sequence, fo:block or fo:character): +

+ ]]> +

+ Enable hyphenation on a block:

+ ]]> @@ -678,17 +716,28 @@ Can I control this? displayed as “#”.

- There are a few fonts supplied with Acrobat Reader. If you use other - fonts, the font must be available on the machine where the PDF is - viewed or it must have been embedded in the PDF file. See - embedding fonts. + This usually means the selected font doesn't have a glyph + for the character. +

+ The standard text fonts supplied with Acrobat Reader have + mostly glyphs for characters from the ISO Latin 1 character + set. For a variety of reasons, even those are not completely + guaranteed to work, for example you can't use the fi + ligature from the standard serif font. Check the overview for the default + PDF fonts.

- Furthermore, if you select a certain font family, the font must - contain glyphs for the desired character. There is an overview available for the - default PDF fonts. For most symbols, it is better to select the symbol - font explicitely, for example in order to get the symbol for the + If you use your own fonts, the font must have a glyph for + the desired character. Furthermore the font must be + available on the machine where the PDF is viewed or it must + have been embedded in the PDF file. See embedding fonts. +

+ For most symbols, it is better to select the symbol font + explicitely, for example in order to get the symbol for the mathematical empty set, write:

∅]]> @@ -758,31 +807,9 @@ Can I control this?

This is a problem of Internet Explorer requesting the content several - times. Some suggestions: + times. Please see the notes on Internet Explorer + for more information.

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

@@ -937,7 +964,7 @@ Can I control this? in the input.

- See XML Entity Characters. + See Using HTML Character Names.

diff --git a/src/documentation/content/xdocs/fo.xml b/src/documentation/content/xdocs/fo.xml index b0a8fdbd6..40f92eb25 100644 --- a/src/documentation/content/xdocs/fo.xml +++ b/src/documentation/content/xdocs/fo.xml @@ -12,7 +12,8 @@

FOP uses XSL-FO as input. It is the responsibility of the user to make sure that the XSL-FO submitted to FOP is correct. -The tutorial items presented here are not comprehensive, but are of the FAQ variety. +The tutorial items presented here are not comprehensive, but are of the FAQ variety. Another +good FAQ is Dave Pawson's XSL FAQ.

@@ -325,7 +326,7 @@ To accomplish this, place 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 in certain situations: multiple page sequences, an initial page number other than 1, or forcing a certain page count, thereby producing blank pages at the end.

@@ -421,6 +422,28 @@ This document can be used either to validate against the FO standard, or against See the notes near the beginning of the document for instructions on how to use it.

+ Producing landscape pages +

+ Pages in landscape format can easily be produced by exchanging the page-height and page-width values of a simple-page-master element. +

+ + + + + + + +]]> +

+ External Resources +

Resources needed by an XSL-FO file that are external to it (graphics, for example), are defined in the XSL-FO standard as being of type "uri-specification". This is defined in the standard at Section 5.11 Property Datatypes, which includes a link to the URI standard itself. Refer to the XSL-FO and URI standards themselves for more detailed instructions.

URIs may be either absolute or relative to a base URI. (See FOP: Configuration for information on setting the base URI for a FOP session). Here is an example referencing an external-graphic that is relative to the base URI:

+ ]]> +

Here is an example referencing an external-graphic that is an absolute URI on a local filesystem:

+ ]]> +

diff --git a/src/documentation/content/xdocs/fonts.xml b/src/documentation/content/xdocs/fonts.xml index 5ef9ff8d3..f2ec00952 100644 --- a/src/documentation/content/xdocs/fonts.xml +++ b/src/documentation/content/xdocs/fonts.xml @@ -1,195 +1,191 @@ -

- Fonts + FOP: Fonts - +

- -

- Important -

The information on this page applies primarily to the PDF renderer. The PostScript renderer - also supports custom fonts but doesn't support font embedding, yet. This page does - not apply to the AWT, PCL, MIF and other renderers.

The AWT renderer relies upon AWT to provide the available fonts. And it's the printer - driver of your operating system that decides if a font is embedded when using the AWT - renderer.

- Status -

FOP (building PDF files) normally supports only the base 14 font package defined in the Adobe PDF specification. - That includes the following fonts: Helvetica, Times, Courier, Symbol and ZapfDingbats. -

Font support in FOP can be extended by the addition of font metric files (written in XML) created from Adobe - Type 1 fonts and TrueType fonts. No other font types (Type 3, etc.) are supported at this time. - More information about font types can be found at - the - Adobe font types. There is also lots more font information - on this Adobe Font Technote. -

- - The font is simply embedded into the PDF file, it is not converted. - -

- Adding Type 1 fonts -

As mentioned above you need an XML file containing font metrics to be able to use an additional font. FOP - contains a tool that can generate such a font metrics file from a PFM file, which normally comes with the font file. -

- Generating a font metrics file -

Run the class org.apache.fop.fonts.apps.PFMReader to generate the XML file. -

Windows:

- -java -cp build\fop.jar;lib\avalon-framework.jar;lib\xml-apis.jar; - lib\xercesImpl.jar;lib\xalan.jar - org.apache.fop.fonts.apps.PFMReader pfm-file xml-file - -

Unix:

- -java -cp build/fop.jar:lib/avalon-framework.jar:lib/xml-apis.jar: - lib/xercesImpl.jar:lib/xalan.jar - org.apache.fop.fonts.apps.PFMReader pfm-file xml-file - - - The classpath in the above example has been simplified for readibity. - You will have to adjust the classpath to the names of the actual JAR files in the lib directory. - avalon-framework.jar is necessary only for versions 0.20.5 or later. - xml-apis.jar, xercesImpl.jar and xalan.jar are not necessary for JDK version 1.4 or later. - - The tool will construct some values (FontBBox, StemV and ItalicAngle) based on assumptions and - calculations which are only an approximation to the real values. FontBBox and Italic Angle can be found in - the human-readable part of the PFB file or in the AFM file. The PFMReader tool does not yet interpret PFB or AFM files, so if you want - to be correct, you may have to adjust the values in the XML file manually. The constructed values however - appear to have no visible influence. - + +

+ Summary +

The following table summarizes the font capabilites of the various FOP renderers:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Renderer	Base-14	AWT/OS	Custom	Custom Embedding
PDF	yes	no	yes	yes
PostScript	yes	no	yes	no
PCL	yes (modified)	no	no	no
TXT	yes (used for layout but not for output)	no	yes (used for layout but not for output)	no
AWT	if available from OS	yes	no	n/a (display only)
Print	if available from OS	yes	no	controlled by OS printer driver
RTF	n/a (font metrics not needed)	n/a	n/a	n/a
MIF	n/a (font metrics not needed)	n/a	n/a	n/a
SVG	if available from OS	yes	no	no
XML	yes	no	yes	n/a

- Register the fonts within FOP -

- Edit conf/userconfig.xml and add entries for the font - if the fonts section, - ie: -

- - -]]> - - Starting from FOP version 0.20.5 you can use URLs for the paths to the font files. Relative URLs are resolved - relative to the fontBaseDir property (or baseDir) if available. - - - Make sure you specify the PFB file in the embed-file attribute - and not the PFM you used to generate the XML font metrics file. - - - If you do not want the font embedded in the PDF then remove the - "embed-file" attribute. The PDF will then contain text using - the font with the font metrics and to view it properly the - font will need to be installed where it is being viewed. - - - Cocoon users will need to setup the config, see FOPSerializer - for more information. - +

+ Base-14 Fonts +

The Adobe PDF Specification specifies a set of 14 fonts that must be available to every PDF reader: Helvetica (normal, bold, italic, bold italic), Times (normal, bold, italic, bold italic), Courier (normal, bold, italic, bold italic), Symbol and ZapfDingbats.

- Adding TrueType Fonts -

Adding TrueType fonts is almost identical to the process of - adding Type 1 fonts. The main difference is in the first - step.

- -

- Generating a font metrics file -

As mentioned above you need an XML file containing font - metrics to be able to use an additional font. FOP contains - a tool that can generate such a font metrics file from - your TrueType font file. -

- Create metrics for the fontfile (we assume the file has - the name cmr10.ttf and exists in c:\myfonts\): -

- -java -cp build\fop.jar;lib\avalon-framework.jar;lib\xml-apis.jar; +

+ AWT/Operating System Fonts +

The AWT family of renderers (AWT, Print, SVG), use the Java AWT libraries for font metric information. Through operating system registration, the AWT libraries know what fonts are available on the system, and the font metrics for each one.

+ Custom Fonts +

Support for custom fonts is added by creating font metric files (written in XML) from the actual font files, and registering them with FOP. Currently only Type 1 and TrueType fonts can be added. +More information about fonts can be found at:

Adobe font types
Adobe Font Technote +

+ Type 1 Font Metrics +

FOP includes PFMReader, which reads the PFM file that normally comes with a Type 1 font, and generates an appropriate font metrics file for it. +To use it, run the class org.apache.fop.fonts.apps.PFMReader:

Windows:

+ java -cp build\fop.jar;lib\avalon-framework.jar;lib\xml-apis.jar; + lib\xercesImpl.jar;lib\xalan.jar + org.apache.fop.fonts.apps.PFMReader pfm-file xml-file +

Unix:

+ java -cp build/fop.jar:lib/avalon-framework.jar:lib/xml-apis.jar: + lib/xercesImpl.jar:lib/xalan.jar + org.apache.fop.fonts.apps.PFMReader pfm-file xml-file + The classpath in the above example has been simplified for readibity. +You will have to adjust the classpath to the names of the actual JAR files in the lib directory. +avalon-framework.jar is necessary only for versions 0.20.5 or later. +xml-apis.jar, xercesImpl.jar and xalan.jar are not necessary for JDK version 1.4 or later. + The tool will construct some values (FontBBox, StemV and ItalicAngle) based on assumptions and calculations which are only an approximation to the real values. +FontBBox and Italic Angle can be found in the human-readable part of the PFB file or in the AFM file. +The PFMReader tool does not yet interpret PFB or AFM files, so if you want to be correct, you may have to adjust the values in the XML file manually. +The constructed values however appear to have no visible influence. +

+ TrueType Font Metrics +

FOP includes TTFReader, which reads the TTF file and generates an appropriate font metrics file for it. +Use it in a similar manner to PFMReader. +For example, to create such a metcis file in Windows from the TrueType font at c:\myfonts\cmr10.ttf:

+ java -cp build\fop.jar;lib\avalon-framework.jar;lib\xml-apis.jar; lib\xercesImpl.jar;lib\xalan.jar org.apache.fop.fonts.apps.TTFReader - C:\myfonts\cmr10.ttf ttfcm.xml - -

- TrueType collections -

- TrueType collections (.ttc files) contains more than one - font. To create metrics for a ttc file you must specify - the font in the collection with the -ttcname option to - TTFReader. -

- To get a list of the fonts in a collection, just start the - TTFReader as if it were a normal TrueType file (without - the -ttcname option). It will then display all the font - names and exit with an Exception... -

- Example on generating metrics for a .ttc file: -

- -java -cp build\fop.jar;lib\avalon-framework.jar;lib\xml-apis.jar; + C:\myfonts\cmr10.ttf ttfcm.xml +

+ TrueType Collections Font Metrics +

TrueType collections (.ttc files) contain more than one font. +To create metrics files for these fonts, you must specify which font in the collection should be generated, by using the "-ttcname" option with the TTFReader.

To get a list of the fonts in a collection, just start the TTFReader as if it were a normal TrueType file (without the -ttcname option). +It will display all of the font names and exit with an Exception.

Here is an example of generating a metrics file for a .ttc file:

+ java -cp build\fop.jar;lib\avalon-framework.jar;lib\xml-apis.jar; lib\xercesImpl.jar;lib\xalan.jar org.apache.fop.fonts.apps.TTFReader -ttcname "MS Mincho" - msmincho.ttc msminch.xml - -

- -

- Register the fonts within FOP -

- Similiar to Type 1 fonts. -

- - + msmincho.ttc msminch.xml +

+ Register Fonts with FOP +

You must tell FOP how to find and use the font metrics files by registering them in the FOP Configuration. Add entries for your custom fonts, regardless of font type, to the configuration file in a manner similar to the following:

+ + ]]> + Review the documentation for FOP Configuration for instructions on making the FOP configuration available to FOP when it runs. Otherwise, FOP has no way of finding your custom font information. +

Starting with FOP version 0.20.5 you can use URLs for the paths to the font files. +Relative URLs are resolved relative to the fontBaseDir property (or baseDir) if available. See FOP: Configuration for more information.
The "kerning" and "embed-file" attributes are optional. Kerning is currently not used at all. If embedding is off, the output will position the text correctly (from the metrics file), but it will not be displayed or printed correctly unless the viewer has the applicable font available to their local system.
When setting the embed-file attribute for Type 1 fonts, be sure to specify the PFB (actual font data), not PFM (font metrics) file that you used to generate the XML font metrics file.

+ Cocoon users will need to setup the config, see FOPSerializer for more information.

- -

- Embedding fonts -

- Font embedding is enabled in the userconfig.xml file and controlled by the embed-file attribute. - If you don't specify the embed-file attribute the font will not be embedded, but will only be referenced. -

- When FOP embeds a font, it scrambles its fontname by inserting a prefix that ensures that the fontname will not match the fontname of an installed font. -This is helpful with older versions of Acrobat Reader that preferred installed fonts over embedded fonts. -

- When embedding PostScript fonts, the entire font is always embedded. -

- When embedding TrueType fonts (ttf) or TrueType Collections (ttc), a new font, containing only the glyphs used, is created from the original font and embedded in the pdf. +

+ Embedding + The PostScript renderer does not yet support font embedding. + The font is simply embedded into the PDF file, it is not converted. +

Font embedding is enabled in the userconfig.xml file and controlled by the embed-file attribute. +If you don't specify the embed-file attribute the font will not be embedded, but will only be referenced.

When FOP embeds a font, it scrambles its fontname by inserting a prefix that ensures that the fontname will not match the fontname of an installed font. +This is helpful with older versions of Acrobat Reader that preferred installed fonts over embedded fonts.

When embedding PostScript fonts, the entire font is always embedded.

When embedding TrueType fonts (ttf) or TrueType Collections (ttc), a new font, containing only the glyphs used, is created from the original font and embedded in the pdf. Currently, this embedded font contains only the minimum data needed to be embedded in a pdf document, and does not contain any codepage information. The PDF document contains indexes to the glyphs in the font instead of to encoded characters. -While the document will be displayed correctly, the net effect of this is that searching, indexing, and cut-and-paste will not work properly. -

- One workaround for this behavior is to use the -ansi option when generating metrics with TTFReader. +While the document will be displayed correctly, the net effect of this is that searching, indexing, and cut-and-paste will not work properly.

One workaround for this behavior is to use the -ansi option when generating metrics with TTFReader. This will cause the whole font to be embedded in the pdf document. -Characters will be WinAnsi encoded (as specified in the PDF spec), so you lose the ability to use characters from other character sets. -

- - Be sure to start FOP with the option to find the config file ("-c conf/userconfig.xml" from the command line). Otherwise, it has no way of finding your custom font information. - - +Characters will be WinAnsi encoded (as specified in the PDF spec), so you lose the ability to use characters from other character sets.

+ - diff --git a/src/documentation/content/xdocs/gethelp.xml b/src/documentation/content/xdocs/gethelp.xml index 2c6342816..f9fa1ce35 100644 --- a/src/documentation/content/xdocs/gethelp.xml +++ b/src/documentation/content/xdocs/gethelp.xml @@ -40,7 +40,7 @@ There is information about how to run FOP, how to embed it, how to add custom fo

Review FOP User Mailing List Archive

It is possible that your question has already been answered but has not yet found its way into the FAQ. -Links to the FOP User mailing list archives are on the Resources page. +Links to the FOP User mailing list archives are on the Mailing List page.

@@ -50,19 +50,7 @@ If so, please do not post a mailing list question or report another issue, as th

Submit Question to FOP User Mailing List -

Subscription information is on the Resources page.
Review General Mailing List Information before submitting your question.
State the version of FOP you're using.
Include detailed error messages, if there are any.
Provide FO code instead of XSLT snippets or DocBook source. -See Running Xalan for how to produce FO from your XML+XSLT.
Provide the shortest possible complete, self-contained FO code that demonstrates the problem. -Include images only if they are an integral part of the question. -Filter out any confidential material.
Include only those portions of stack traces that will be helpful in finding the problem.
Instead of attaching large PDF files or screen shots, include a small B&W GIF, JPG or PNG of the area of interest.

See FOP User Mailing List for details.

Enter an Issue Report diff --git a/src/documentation/content/xdocs/graphics.xml b/src/documentation/content/xdocs/graphics.xml index 655f42594..1c8adfa69 100644 --- a/src/documentation/content/xdocs/graphics.xml +++ b/src/documentation/content/xdocs/graphics.xml @@ -18,94 +18,39 @@ Support Thru - BMP (Microsoft Windows Bitmap) + BMP (Microsoft Windows Bitmap) bitmap - JIMI or JAI - - - CUR - unknown - JIMI + FOP native EPS (Encapsulated PostScript) metafile (both bitmap and vector), probably most frequently used for vector drawings - FOP native (limited support) + FOP native (limited support, see restrictions below) GIF (Graphics Interchange Format) bitmap FOP native - - FPX - unknown - JAI - - - ICO (Sun Icon) - bitmap - JIMI - JPEG (Joint Photographic Experts Group) bitmap FOP native - PCX (PC Paintbrush) - bitmap - JIMI - - - PICT (Macintosh PICT) - metafile - JIMI - - - PNG (Portable Network Graphic) + PNG (Portable Network Graphic) bitmap JIMI or JAI - - PNM (Portable aNyMap Utilities, part of the Portable Bitmap Utilies, aka pbmplus. PNM is a superset encompassing PBM or Portable Bitmap, PGM or Portable Grayscale, and PPM or Portable Pixmap.) - bitmap - JAI - - - PSD (Adobe Photoshop) - bitmap - JIMI - - - RAS (Sunraster) - bitmap - JIMI - SVG (Scalable Vector Graphics) vector (with embedded bitmaps) Batik - TGA (Targa) + TIFF (Tag Image Format File) bitmap - JIMI - - - TIFF (Tag Image Format File) - bitmap - JIMI or JAI - - - XBM (X BitMap) - bitmap - JIMI - - - XPM (X PixMap) - bitmap - JIMI + FOP native or JAI, depending on the subformat. See TIFF for more details.(JIMI also supports TIFF, but this has not been implemented within FOP).

@@ -121,14 +66,15 @@ JIMI

Because of licensing issues, the JIMI image library is not included in the FOP distribution. First, download and install it. -Then, copy the file "JimiProClasses.zip" from the archive to xml-fop/lib/jimi-1.0.jar. Please note that FOP binary distributions are compiled with JIMI support, so there is no need for you to build FOP to add the support. If jimi-1.0.jar is installed in the right place, it will automatically be used by FOP, otherwise it will not. +Then, copy the file "JimiProClasses.zip" from the archive to {fop-install-dir}/lib/jimi-1.0.jar. Please note that FOP binary distributions are compiled with JIMI support, so there is no need for you to build FOP to add the support. If jimi-1.0.jar is installed in the right place, it will automatically be used by FOP, otherwise it will not.

- JAI + JAI (Java Advanced Imaging API) + JAI support is available for Release 0.20.5 and later. The comments in this section do not apply to releases earlier than 0.20.5.

FOP has been compiled with JAI support, but JAI is not included in the FOP distribution. -To use it, simply install JAI. +To use it, install JAI, then copy the jai_core.jar and the jai_codec.jar files to {fop-install-dir}/lib. JAI is much faster than JIMI, but is not available for all platforms. See What platforms are supported? on the JAI FAQ page for more details.

@@ -149,19 +95,41 @@ If you run a server without X, or if you can't connect to the X server due to se

+ BMP +

FOP native support for BMP images is limited to the RGB color-space.

EPS

FOP provides support for two output targets:

PostScript (full support).
PDF (partial support). FOP embeds the EPS file into the PDF, but currently does not do so completely correctly. PostScript devices (including ghostscript) will render the EPS correctly, but Acrobat Reader will not currently display it.
+ PDF (partial support). Due to the lack of a built-in PostScript interpreter, FOP + can only embed the EPS file into the PDF. Acrobat Reader will not currently display + the EPS (it doesn't have a PostScript interpreter, either) but it will be shown + correctly when you print the PDF on a PostScript-capable printer. PostScript devices + (including GhostScript) will render the EPS correctly. +

+ Other output targets can't be supported at the moment because + FOP lacks a PostScript interpreter. +

JPEG -

Not all variants of JPEG are supported, especially those containing unusual color lookup tables and color profiles. If you have trouble with a JPEG image in FOP, try opening it with an image processing program (such as Photoshop or Gimp) and then saving it. Specifying 24-bit color output may also help. +

FOP native support of JPEG does not include all variants, especially those containing unusual color lookup tables and color profiles. +If you have trouble with a JPEG image in FOP, try opening it with an image processing program (such as Photoshop or Gimp) and then saving it. +Specifying 24-bit color output may also help. +For the PDF and PostScript renderers most JPEG images can be passed through without decompression. +User reports indicate that grayscale, RGB, and CMYK color-spaces are all rendered properly.

+ PNG +

If using JAI for PNG support, only RGB and RGBA color-spaces are supported for FOP rendering.

SVG

@@ -214,23 +182,10 @@ If the text is inserted into the PDF using the inbuilt text commands for PDF it will use a single character.

-It is possible to make sure that all text is drawn into PDF using the -PDF text commands (instead of the graphical shapes), by adding the following to the user config: -

- - strokeSVGText - false -]]> -

In a servlet environment, you can set it directly:

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

For information on using a configuration file in a servlet, see the FAQ on that topic.

Note that this configuration setting works only for the PDF renderer.

-The drawback to forcing text to be rendered as text is that it will be confined to text that is -possible for PDF fonts (including embedded fonts) and implemented with -this workaround. The fonts available are the standard pdf fonts and any -fonts that you have embedded using FOP. The font sizes will be rounded -to an integer value. In future this will be improved. +For PDF output, there is a configuration option to force SVG text to be rendered as text. +The drawback to this approach is that it is effective only for available fonts (including embedded fonts). +Font sizes are rounded to the next integer point size. +This will be improved in the future.

Note that because SVG text can be rendered as either text or a vector graphic, you may need to consider settings in your viewer for both. The Acrobat viewer has both "smooth line art" and "smooth text" settings that may need to be set for SVG images to be displayed nicely on your screen (see Edit / Preferences / Display). @@ -276,6 +231,16 @@ into a raster graphic are not drawn properly in PDF. The image is opaque.

+ TIFF +

FOP-native TIFF support is limited to PDF and PostScript output only. Also, according to user reports, FOP's native support for TIFF is limited to images with the following characteristics (all must be true for successful rendering):

single channel images (i.e., bi-level and grayscale only)
uncompressed images, or images using CCITT T.4, CCITT T.6, or JPEG compression
images using white-is-zero encoding in the TIFF PhotometricInterpretation tag

JAI: Supports RGB and RGBA only for FOP rendering.

Graphics Resolution

Some bitmapped image file formats store a dots-per-inch (dpi) or other resolution value. Since PDF and most output formats do not have a concept of resolution, but only of absolute image units (i.e. pixels) FOP ignores the resolution values as well. Instead, FOP uses the dimensions of the image as specified in the fo:external-graphic element to render the image:

@@ -287,5 +252,20 @@ into a raster graphic are not drawn properly in PDF. The image is opaque.

If you need a higher apparent output resolution for bitmapped images, first make sure that at least one dimension of the image is defined in your XSL-FO input. Apart from that, resolution problems are in the image file itself, and must be corrected there: use or create a higher-resolution image file.

The explanation above describes only the basic default behavior. There are other attributes of the fo:external-graphic element that can affect the behavior described above.

+ Image caching +

+ FOP caches images between runs. The URL is used as a key to identify images which means that when + a particular URL appears again, the image is taken from the cache. If you have a servlet that + generates a different image each time it is called with the same URL you need to use a constantly + changing dummy parameter on the URL to avoid caching. +

+ Currently, the images are not automatically released when an OutOfMemoryError is imminent. The + image cache can grow to a considerable size over time when a lot of different URLs are in use. + Starting with version 0.20.5 you can call org.apache.fop.image.FopImageFactory.resetCache() + to manually empty the cache. Image caching will be improved as part of our redesign effort. +

diff --git a/src/documentation/content/xdocs/index.xml b/src/documentation/content/xdocs/index.xml index e1f0ebc2e..1635327e7 100644 --- a/src/documentation/content/xdocs/index.xml +++ b/src/documentation/content/xdocs/index.xml @@ -55,7 +55,7 @@ The most common method is to convert semantic XML to XSL-FO, using an XSLT trans

The FOP layout system is currently being rewritten to better support the XSL-FO standard.

- The PDF files on this site are created using the latest development version of FOP. + The PDF files on this site are created using FOP. diff --git a/src/documentation/content/xdocs/logocontest.xml b/src/documentation/content/xdocs/logocontest.xml index 4d1e66d75..f1fe190c6 100644 --- a/src/documentation/content/xdocs/logocontest.xml +++ b/src/documentation/content/xdocs/logocontest.xml @@ -3,19 +3,19 @@ "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/schema/dtd/document-v11.dtd">

- Logo contest + Logo Contest

FOP needs new logo and FOP Team decided to hold an open logo contest. We invite all members of +

FOP needs a new logo and so we've decided to hold an open logo contest. We invite all members of the FOP community as well as any other interested parties to participate as contestants or by expressing your opinion through voting. We have set up Web Poll where you can see - contestant logos and vote.

+ contestant logos and vote your favorite.

The rules

The rules are simple:

Everyone can participate as contestant
Everyone can vote, but only FOP Team picks out the winner
Everyone can participate as a contestant
Everyone can vote, but only FOP Team will choose the winner
No reward except for pride
The winner image is donated to Apache, but the authorship is preserved
The final result should be in SVG format

How to participate -

Submit your image or link to it to fop-user mail list. - Vote for a logo you like the most at FOP logo contest Web Poll. +

Submit your image or link to it at the fop-user mail list. + Vote for the logo you like the most at FOP logo contest Web Poll.

Credits -

We would like to thank Ant and - POI teams for ideas how to make a logo contest.

We would like to thank the Ant and + POI teams for their ideas on how to make this logo contest.

diff --git a/src/documentation/content/xdocs/news.xml b/src/documentation/content/xdocs/news.xml index 432eb7b38..9ab6a6dfb 100644 --- a/src/documentation/content/xdocs/news.xml +++ b/src/documentation/content/xdocs/news.xml @@ -7,6 +7,17 @@ News +

+ 29 June 2003 - New Committer +

Welcome Glen Mazza!

+ 23 May 2003 - FOP 0.20.5 Release Candidate 3 available +

+ See the full text of the announcement. +

18 February 2003 - FOP 0.20.5 Release Candidate 2 available

@@ -21,10 +32,10 @@

- 28 January 2003 - FOP logo contest -

We are looking for a new logo. FOP logo - contest is started!

+ 28 January 2003 - FOP logo contest +

We are looking for a new logo. FOP logo + contest is started!

23 December 2002 - Official FOP Wiki

diff --git a/src/documentation/content/xdocs/output.xml b/src/documentation/content/xdocs/output.xml index 3ba4a509a..16296837b 100644 --- a/src/documentation/content/xdocs/output.xml +++ b/src/documentation/content/xdocs/output.xml @@ -277,19 +277,15 @@ Adobe Framemaker. This is currently not fully implemented.

TXT

-Text as you could imagine does not work very well. It is an output format -that you should expect bad results. The main purpose of this is to get -a quick and dirty view of the document and the text inside it. -

-The TXTRenderer is a FOP renderer that produces plain ASCII text output +The text renderer produces plain ASCII text output that attempts to match the output of the PDFRenderer as closely as possible. This was originally developed to accommodate an archive system -that could only accept plain text files. Of course when limited to plain -fixed pitch text the output does not always look very good. +that could only accept plain text files, and is primarily useful for getting +a quick-and-dirty view of the document text. The renderer is very limited, +so do not be surprised if it gives unsatisfactory results.

-The TXTRenderer works with a fixed size page buffer. The size of this +The Text renderer works with a fixed size page buffer. The size of this buffer is controlled with the textCPI and textLPI public variables. The textCPI is the effective horizontal characters per inch to use. The textLPI is the vertical lines per inch to use. From these values @@ -298,6 +294,13 @@ The formatting objects to be rendered are then mapped to this grid. Graphic elements (lines, borders, etc) are assigned a lower priority than text, so text will overwrite any graphic element representations.

Because FOP lays the text onto a grid during layout, there are frequently extra or missing spaces between characters and lines, which is generally unsatisfactory. +Users have reported that the optimal settings to avoid such spacing problems are:

font-family="Courier"
font-size="7.3pt"
line-height="10.5pt"

diff --git a/src/documentation/content/xdocs/pdfencryption.xml b/src/documentation/content/xdocs/pdfencryption.xml index b555fc832..e51dda0b9 100755 --- a/src/documentation/content/xdocs/pdfencryption.xml +++ b/src/documentation/content/xdocs/pdfencryption.xml @@ -7,20 +7,22 @@ PDF encryption. +

Overview + PDF Encryption is available in Release 0.20.5 and later. The comments on this page do not apply to releases earlier than 0.20.5.

FOP supports encryption of PDF output, thanks to Patrick - C. Lankswert. This feature is commonly used to prevent unauthorized - viewing, printing, editing and copying text from the document - annotations. It is also possible to ask the user for a password in order - to view the contents. Note that there already exist third party - applications which can decrypt an encrypted PDF without effort and allow - the aforementioned operations, therefore the degree of protection is - limited. + C. Lankswert. This feature is commonly used to prevent + unauthorized viewing, printing, editing, copying text from the + document and doing annotations. It is also possible to ask the + user for a password in order to view the contents. Note that + there already exist third party applications which can decrypt + an encrypted PDF without effort and allow the aforementioned + operations, therefore the degree of protection is limited.

For further information about features and restrictions regarding PDF @@ -29,19 +31,21 @@

- Usage + Usage (command line)

Encryption is enabled by supplying any of the encryption related options.

- An owner password with the -o option. This password is - actually used as encryption key. Usually it is also used by most tools - to disregard any restriction imposed on the PDF document. + An owner password is set with the -o option. This + password is actually used as encryption key. Many tools for + PDF processing ask for this password to disregard any + restriction imposed on the PDF document.

If no owner password has been supplied but FOP was asked to apply some - restrictions, a random password is used. + restrictions, a random password is used. In this case it is obviously + impossiible to disregard restrictions in PDF processing tools.

A user password, supplied with the -u option, will @@ -56,16 +60,83 @@ text, editing in Adobe Acrobat and making annotations, respectively.

+ Usage (embedded) +

+ When FOP is embedded in another Java application you need to set an + options map on the renderer. These are the supported options: +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Option	Description	Values	Default
ownerPassword	The owner password	String	+
userPassword	The user password	String	+
allowPrint	Allows/disallows printing of the PDF	"TRUE" or "FALSE"	"TRUE"
allowCopyContent	Allows/disallows copy/paste of content	"TRUE" or "FALSE"	"TRUE"
allowEditContent	Allows/disallows editing of content	"TRUE" or "FALSE"	"TRUE"
allowEditAnnotations	Allows/disallows editing of annotations	"TRUE" or "FALSE"	"TRUE"

+ + Encryption is enabled as soon as one of these options is set. + +

+ An example to enable PDF encryption in Java code: +

+ +

Environment

- In order to use PDF encryption, FOP has to be compiled with cryptography - support. Currently, only JCE - is supported. JCE is part of JDK 1.4. For earlier JDKs, it can be - installed separately. The build process automatically senses JCE - presence and installs PDF support if possible, otherwise, a stub is - compiled in. + is supported. JCE is part of JDK 1.4. For earlier JDKs, it can + be installed separately. The build process automatically + detects JCE presence and installs PDF encryption support if + possible, otherwise a stub is compiled in.

Cryptography support must also be present at run time. In particular, a @@ -75,7 +146,7 @@

"Cannot find any provider supporting RC4"

- then you don't have the needed support. + then you don't have the needed infrastructure.

There are several commercial and a few Open Source packages which @@ -112,6 +183,10 @@ providers. For JDK 1.4 this is detailed on Sun's web site. +

+ If you have any experience with Mozilla JSS or any other + cryptography provider, please post it to the fop-user list. +

diff --git a/src/documentation/content/xdocs/relnotes.xml b/src/documentation/content/xdocs/relnotes.xml index d61a7c37f..5d4db2878 100644 --- a/src/documentation/content/xdocs/relnotes.xml +++ b/src/documentation/content/xdocs/relnotes.xml @@ -14,9 +14,11 @@

Important changes since the last release (0.20.4):

Some hyphenation patterns (cs, da, de, de_DR, el, en, en_US, fr, nl, - no, pt, ru, sk, tr) have been removed due to licensing reasons - (en_GB hyphenation has been renamed to en). - We hope to resolve this issue before the final release. + no, sk, tr) have been removed due to licensing reasons + (en_GB hyphenation has been renamed to en). + We're still working on this issue + (see + Wiki for details).
Documentation is now built with Forrest (version 0.4). You need to install Forrest if you want build the docs @@ -39,6 +41,18 @@
Links in PDF won't generate multiple link rectangles anymore. If this causes a problem you can set the system property "links.merge" to "no".
FOP has been compiled with cryptography support. See + PDF encryption for details about installation and usage. +
The behaviour of leader has changed. See + bug #19341, + bug #19465 + and leader.fo (examples). +
+ For a more detailed list of changes, see the CHANGES file in the root of the + FOP distribution. +

diff --git a/src/documentation/content/xdocs/resources.xml b/src/documentation/content/xdocs/resources.xml index af6c7c40c..01707bca5 100644 --- a/src/documentation/content/xdocs/resources.xml +++ b/src/documentation/content/xdocs/resources.xml @@ -4,67 +4,10 @@

- Resources + FOP: Other Resources Resources useful for developing and using FOP

- Mailing Lists and Archives -

- General Information -

Before posting questions to any list, review "How To Ask Questions The Smart Way".

Be sure to set your email client to send plain text email messages to any mailing lists. -Please do not send html or rtf email, as they do not work well with the archive engines. -If you are using Microsoft Outlook, this setting can be found at the "Mail Format" tab of the Tools/Options menu.

For help in understanding email acronyms, see the Lingo2Word Acronym List, or the Keno Internet Services Internet Glossary.

- FOP User Mailing List -

Use this forum to discuss topics of interest to FOP users. -After reviewing the FOP documentation and searching the archives (see below), use this forum to ask questions about how to download, install, configure, and use FOP. -Please do not use this forum for general XSL-FO, XSLT, or PDF questions.

To review the archives, you have several options: -
- The Mailing list ARChives (MARC) at the AIMS group (search).
- The Apache Eyebrowse archive (search, list by date, author, subject, or thread).
- The Apache Mailing List archive (gzip files).
-
Before posting questions to any list, see "General Information".
See Apache XML Mailing Lists for detailed subscription information.
To subscribe (digest only): Send email to fop-user-digest-subscribe@xml.apache.org.
To subscribe fully: Send email to fop-user-subscribe@xml.apache.org.
For standard help: Send email to fop-user-help@xml.apache.org.
To unsubscribe: Send email to fop-user-unsubscribe@xml.apache.org.

- XSL-FO Mailing List (at W3C) -

Use this forum to ask general XSL-FO questions.

To review the archive: W3C XSL-FO Archives.
Before posting questions to any list, see "General Information".
Subscription administration information can be found at W3C Mailing List Administrativia. -After reviewing the instructions there, send your subscribe or unsubscribe request to www-xsl-fo-request@w3.org.

- XSL-FO Mailing List (at YahooGroups) -

Use this forum to ask general XSL-FO questions.

Before posting questions to any list, see "General Information".
The home page for this groups is XSL-FO - discussion of XSL Formatting Objects.

- XSLT List (Mulberry Tech) -

Before posting questions to any list, see "General Information".
Information for using and subscribing can be found at XSL-List -- Open Forum on XSL.

Specifications

@@ -95,11 +38,17 @@ After reviewing the instructions there, send your subscribe or unsubscribe reque

Java JDK 1.3 Documentation

+ PDF +

Portable Document Format (PDF) 1.4 Reference Manual +

Other

Supported SVG Recommendation (04 September 2001)
Portable Document Format (PDF) 1.4 Reference Manual

@@ -125,7 +74,7 @@ After reviewing the instructions there, send your subscribe or unsubscribe reque

[book] XSLT Programmer's Reference, by Michael H. Kay, Wrox Press, ISBN 1-861-00506-7.

[book] XSLT, by Doug Tidwell, O'Reilly & Associates, 2001, ISBN 0-596-00053-7.

[book] XSLT Cookbook, by Sal Mangano, O'Reilly & Associates, 2002, ISBN 0-596-00372-2.

[article] Dave Pawson's XSLT FAQ.

[article] Dave Pawson's XSL FAQ.

[book] XPath and XPointer: Locating Content in XML Documents, by John E. Simpson, O'Reilly & Associates, 2002, ISBN 0-596-00291-2.

[book] XSL Essentials, by Michael Fitzgerald, John Wiley & Sons, 2001, ISBN 0-471-41620-7.

[book] Java and XSLT, by Eric M. Burke, O'Reilly & Associates, 2001, ISBN 0-596-00143-6.

@@ -145,21 +94,63 @@ After reviewing the instructions there, send your subscribe or unsubscribe reque

[online resource] A great number of Java-related books and articles can be found at the O'Reilly Java Site.

+ PDF +

[online resource] Links to the various PDF file format specifications and numerous other documents can be found at Adobe Solutions Network, Acrobat Resources, Acrobat 5.0 SDK Documentation.
[online resource] A list of PDF technical resources can be found at Adobe Solutions Network, Acrobat Resources, Acrobat/PDF Technical Notes
[online resource] A list of Acrobat and PDF developer resources can be found at Adobe Solutions Network, Acrobat Resources, Resources for Developers.

+ PostScript +

[online resource] A list of PostScript-related technical resources can be found at Adobe Solutions Network, PostScript Language Technical Notes
[online resource] Additional PostScript-related developer resources can be found at Adobe Solutions Network, PostScript SDK Archive.

Related/Useful Products -

PJ is an open source product that can be used to modify PDF documents: -http://www.etymon.com/pj/index.html
iText is a library that can edit PDF files, it is possible to do -post processing of the generated PDF files: http://www.lowagie.com/iText/.
html2fo is a converter from html to xsl:fo: http://html2fo.sourceforge.net/.
FOA is a XSL-FO Authoring tool: http://foa.sourceforge.net/.
TIFFRenderer is a renderer for outputting multi-page TIFF: http://www.tkachenko.com/fop/tiffrenderer.html.
AFP Renderer / Batch Assembler for FOP: http://mypage.bluewin.ch/huanderegg/.
The Mogwai Project includes a renderer for FOP that generates output for Okidata dot matrix printers.
[software] The XPath Visualizer. Web site says: "This is a full blown Visual XPath Interpreter for the evaluation of any XPath expression and visual presentation of the resulting nodeset or scalar value."

+ FOP add-ons +

[software] TIFFRenderer is a renderer for outputting multi-page TIFF: http://www.tkachenko.com/fop/tiffrenderer.html (MPL)
[software] AFP Renderer / Batch Assembler for FOP: http://mypage.bluewin.ch/huanderegg/ (open source, license unclear)
[software] The Mogwai Project includes a renderer for FOP that generates output for Okidata dot matrix printers (GPL).
[software] Krysalis Barcode is a barcode generator which can be used with FOP (Apache-style license).

+ PDF post-processors +

[software] iText (MPL and LGPL)
[software] PJ Classic by Etymon (GPL)
[software] PJ Professional by Etymon (commercial)

+ XSL-FO editors +

[software] FOA (Formatting Objects Authoring) (MPL)
[software] FOEditor by Scruffy Software (Shareware)
[software] Scriptura by Inventive Designers (commercial)
[software] XSLfast by jCatalog Software AG (commercial)
[software] XML Report Styler by Rubico (commercial)

+ Other products +

[software] html2fo is a converter from HTML to XSL-FO (GPL).
[software] wh2fo is a converter from Word HTML to XSL-FO (MPL).
[software] RTF2FO is a converter from RTF to XSL-FO by Novosoft (commercial).
[software] The XPath Visualizer. +Web site says: "This is a full blown Visual XPath Interpreter for the evaluation of any XPath expression and visual presentation of the resulting nodeset or scalar value." +Requires Internet Explorer 5+. +(freeware)

diff --git a/src/documentation/content/xdocs/running.xml b/src/documentation/content/xdocs/running.xml index 3105f4271..38416eb07 100644 --- a/src/documentation/content/xdocs/running.xml +++ b/src/documentation/content/xdocs/running.xml @@ -156,6 +156,11 @@ If you don't use table headers and footers, just start a new table every N rows. With headers and footers, consider integrating them as normal table rows, or, if they are used at page breaks, try to put the information into static content. You can then use markers to change them. +

+Clear the image cache. At the moment, images in the cache are not released automatically when an OutOfMemoryError is imminent. +Starting with version 0.20.5 however, you can call org.apache.fop.image.FopImageFactory.resetCache() to empty the +image cache. +

There are currently some bugs which cause FOP to go into a nonterminating loop, which will also often result in a memory overflow. -- 2.39.5