Bugs

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

Website

diff --git a/src/documentation/content/xdocs/dev/index.xml b/src/documentation/content/xdocs/dev/index.xml index 51d03d989..717584bdb 100644 --- a/src/documentation/content/xdocs/dev/index.xml +++ b/src/documentation/content/xdocs/dev/index.xml @@ -64,7 +64,7 @@ internally will be kept.

Subscribe to the fop-dev Mailing List

Use this forum to discuss topics related to FOP development, including patch submissions, bug reports, and design issues. Please do not use it for XML support, XSLT support, XSL-FO support, or even FOP support. -Appropriate mailing lists for these topics can be found on the FOP Mailing List page. +Resources for these and other topics can be found on the FOP User Resources page.

@@ -80,7 +80,7 @@ The Apache Mailing List archive

Before posting questions to any list, see "General Information".

See Apache XML Mailing Lists for detailed subscription information. diff --git a/src/documentation/content/xdocs/dev/pdf.xml b/src/documentation/content/xdocs/dev/pdf.xml new file mode 100644 index 000000000..de718f5f4 --- /dev/null +++ b/src/documentation/content/xdocs/dev/pdf.xml @@ -0,0 +1,21 @@ + + + + + + +

+ PDF (Developer Information) +

+ +

+ Resources +

Acrobat/PDF Technical Notes

+ + + + diff --git a/src/documentation/content/xdocs/dev/ps.xml b/src/documentation/content/xdocs/dev/ps.xml new file mode 100644 index 000000000..7013699e5 --- /dev/null +++ b/src/documentation/content/xdocs/dev/ps.xml @@ -0,0 +1,21 @@ + + + + + + +

+ Postscript (Developer Information) +

+ +

+ Resources +

Postscript Technical Notes

+ + + + diff --git a/src/documentation/content/xdocs/download.xml b/src/documentation/content/xdocs/download.xml index 345034736..765155e75 100644 --- a/src/documentation/content/xdocs/download.xml +++ b/src/documentation/content/xdocs/download.xml @@ -3,33 +3,39 @@ "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/schema/dtd/document-v11.dtd"> -

- Download -

- - -

- Downloading FOP -

You can download the latest release version from the distribution directory.

The file contains also the documentation (including some example fo files) and the source.

If you want to work with the latest and nicest code, you can use the cvs version. See the section - on AnonCVS in the xml.apache.org documentation for details. - Sometimes people have difficulties to access the cvs server; in this case you can download - a snapshot from the cvs files here. - In both cases you have to build FOP yourself - see Compiling Fop for details. -

- - Important: Currently, releases of FOP are coming out of the - "fop-0_20_2-maintain" branch. The "MAIN" branch is currently - under development. See Development Docs - for more information. - -

To run FOP from the command line, see Running FOP.

If you are interested in embedding FOP in a Java application of your own, see - Embedding FOP. -

+ FOP: Downloading A Distribution +

+ +

+ Binary or Source? +

Most FOP users will want to download the latest binary distribution, which is ready to run "out of the box." +However, a source distribution will be preferable if you fall into one of the following categories:

You wish to modify FOP.
You wish to use a version more recent than the latest release. For example, if you have read on the user mailing list that a bug has been fixed or a feature added that you are eager to try, you might download a source distribution from the CVS repository so that you don't have to wait for the next release.
You wish to build a local copy of the API documentation (javadocs).

+ Binary Download +

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

+ Source Download +

You must first determine which of the two main development branches you wish to download, "maintenance" or "redesign". +See Development Introduction for more details on the choices, and for the CVS tags to use when downloading the "maintenance" branch.

There are three ways to obtain a source distribution. Please note that they are listed from least current to most current:

Download a released version from the FOP Distribution directory. Source distributions include "-src" in their names. Please note that official releases currently are only made from the "maintenance" branch.
Download a CVS snapshot from the cvs files here. These snapshots are built approximately every six hours, and have the GMT of their creation time embedded in their names. Please note that CVS snapshots are made only for the "redesign" branch.
Download directly from the CVS repository. +Anyone can do this using the Anonymous CVS Server. By default, the CVS code is up-to-the-minute, the same code that the developers are modifying. See the CVS section of Developer Tools for more information on using CVS.

With any source distribution, you will need to Build FOP from the source files.

+ \ No newline at end of file diff --git a/src/documentation/content/xdocs/embedding.xml b/src/documentation/content/xdocs/embedding.xml index 4e96241b2..a71431e0c 100644 --- a/src/documentation/content/xdocs/embedding.xml +++ b/src/documentation/content/xdocs/embedding.xml @@ -7,15 +7,16 @@

Embedding FOP - Notes about embedding FOP in your Java application + How to Embed FOP in a Java application

- Embedding FOP -

Overview -

Instantiate org.apache.fop.apps.Driver. Once this class is +

Review Running FOP for important information that applies to embedded applications as well as command-line use, such as options and performance. +

To embed FOP in your application, instantiate org.apache.fop.apps.Driver. + Once this class is instantiated, methods are called to set the Renderer to use and the OutputStream to use to output the results of the @@ -26,7 +27,7 @@ enables runtime determination of Renderer and ElementMapping(s).

Basics

The simplest way to use Driver is to instantiate it with the InputSource and OutputStream, then set the renderer desired and @@ -36,9 +37,9 @@

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 @@ -149,30 +149,29 @@ issues should be fixed in the upcoming JDK 1.4

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.

- Hints -

- XML/XSL/DOM Inputs -

-You may want to supply you input to FOP from different data sources. -For example you may have a DOM and XSL stylesheet or you may want to -set variables in the stylesheet. The page here: - -http://xml.apache.org/xalan-j/usagepatterns.html describes -how you can do these things. -

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

-You can use the content handler from the driver to create a SAXResult. -The transformer then can fire SAX events on the content handler which -will in turn create the rendered output. -

-Examples showing this can be found at the bott +See the Examples for some variations on input.

+ Hints +

Object reuse

If FOP is going to be used multiple times within your application @@ -186,7 +185,7 @@ 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 @@ -199,31 +198,149 @@ pages of each document.

- Using FOP in a servlet -

-In the directory xml-fop/examples/servlet you can find a working example how -to use FOP in a servlet. After building the servlet you can drop the fop.war -into the webapps directory of Tomcat, then go to a URL like this: +

+ 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 browsers have problems handling the PDF result sent back to - the browser. IE is particularly bad and different versions behave - differently. Having a ".pdf" on the end of the URL may help. - + + 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 +

+ If both the source XML and XSL are read from files, use the TraxInputHandler: +

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

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

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

+ Because you have an explicit transformer object, you can also use it to explicitly set parameters for the transformation run. +

+ Using a Configuration File +

+ To access an external configuration: +

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

+ No further reference to the options variable is necessary. +

+ See Multithreading FOP for issues related to changing configuration in a multithreaded environment. +

+ Setting the Configuration Programmatically +

+ If you wish to set configuration options from within your embedded application, use the Configuration.put method. Here is an example that sets the "baseDir" configuration in a Unix environment: +

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

+ Here is another that sets baseDir in a Windows environment: +

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

+ See Multithreading FOP for issues related to changing configuration in a multithreaded environment. +

+ Multithreading FOP +

+ FOP is not currently completely thread safe. +Although the relevant methods of the Driver object are synchronized, FOP uses static +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. +
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. +

Examples

The directory "xml-fop/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.

ExampleFO2PDF.java

This example demonstrates the basic usage pattern to transform an XSL-FO @@ -231,7 +348,7 @@ file to PDF using FOP.

ExampleXML2FO.java

This example has nothing to do with FOP. It is there to show you how an XML @@ -241,7 +358,7 @@ classpath (ex. Xalan).

ExampleXML2PDF.java

This example demonstrates how you can convert an arbitrary XML file to PDF @@ -259,7 +376,7 @@ strongly discourage you to do this if it isn't absolutely necessary. The performance is significantly higher with SAX.

ExampleObj2XML.java

This example is a preparatory example for the next one. It's an example that @@ -290,7 +407,7 @@ used. For more detailed information see other resources on JAXP (ex. An older JAXP tutorial).

ExampleObj2PDF.java

The last example here combines the previous and the third to demonstrate @@ -301,7 +418,7 @@ using FOP as before.

Final notes

These examples should give you an idea of what's possible. It should be easy diff --git a/src/documentation/content/xdocs/extensions.xml b/src/documentation/content/xdocs/extensions.xml index a4d4b9739..167f1577c 100644 --- a/src/documentation/content/xdocs/extensions.xml +++ b/src/documentation/content/xdocs/extensions.xml @@ -4,29 +4,21 @@

- Extensions + Standard FOP Extensions

-Sometimes it is desirable to have extensions to XSL-FO in order to support -some feature of the output format which isn't covered by the XSL-FO -specification. -

- Default Extensions -

-These extension are available by default. They are automatically loaded -and you only need to provide the correct namespace for your embedded -XML markup. -

By "extension", we mean any data that can be placed in the input XML document that is not addressed by the XSL-FO standard. +By having a mechanism for supporting extensions, FOP is able to add features that are not covered in the specification.

The extensions documented here are included with FOP, and are automatically available to you. If you wish to add an extension of your own to FOP, please see the Developers' Extension Page.

+ All extensions required the correct use of an appropriate namespace in your input document. +

SVG

-Please see the SVG page for more details. +Please see the SVG documentation for more details.

- Bookmarks +

+ PDF Bookmarks

To use this standard FOP extension, you need to add a namespace entry for http://xml.apache.org/fop/extensions on the root element. @@ -53,39 +45,12 @@ property, but it isn't supported currently. See the pdfoutline.fo file in examples/fo/basic for a more complete example.

Continued-label (for table-header/-footer

Please see examples/fo/basic/contlabel.fo

- Adding Your Own -

-To add your own extension you need to do the following things. -

-Write code that implements your extension functionality. The easiest place to -start is by looking at the code in org.apache.fop.extension. -
-Create a jar file with your classes, it must also include the following file -"/META-INF/services/org.apache.fop.fo.ElementMapping". In this file you need -to put the fully qualified classname of your element mappings class. This -class must implement the "org.apache.fop.fo.ElementMapping" interface. -
-Create your XSL-FO file with the extra XML data embedded in the file with the -correct name space. The examples for SVG and pdfoutline.fo show how this can -be done. -
-Put your jar file in the classpath and then run fop over the XSL-FO file. -

diff --git a/src/documentation/content/xdocs/faq.xml b/src/documentation/content/xdocs/faq.xml index 4c3682376..5559dda05 100644 --- a/src/documentation/content/xdocs/faq.xml +++ b/src/documentation/content/xdocs/faq.xml @@ -3,9 +3,9 @@ "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/schema/dtd/faq-v11.dtd"> - + General questions - + What is FOP?

@@ -19,7 +19,7 @@

- + What can I do with FOP?

@@ -36,7 +36,7 @@

- + What does "FOP" stand for?

@@ -45,7 +45,7 @@

- + How does FOP interact with other Apache Projects?

@@ -61,7 +61,7 @@

- + What is XSL?

@@ -73,8 +73,8 @@

- - What is XSLFO? + + What is XSL-FO?

XSLFO is an XML vocabulary that is used to specify a pagination and @@ -110,44 +110,18 @@

- + How can I contribute?

- There is always plenty of things to do. See - getting involved. + There are numerous ways that you can help. They are outlined in the Developer's Introduction.

- - Common stumbling blocks - - Why does FOP insert a blank page between my page sequences? - -

- This is because spec conformance has been improved. -

- The force-page-count - property controls how a FO processor pads page sequences in - order to get certain page counts or last page numbers. The default is - "auto". With this setting, if the next page sequence - begins with an odd page number because you set the - initial-page-number, and the current page sequence also ends with an - odd page number, the processor inserts a blank page to keep odd and - even page numbers alternating (similar for the case the current page - sequence ends with an even page number and the next page sequence - starts with an even page number. -

- If you don't want to have this blank page, use - force-page-count="no-force". -

- - - + + Problems running FOP + I get the error: [ERROR]: 'master-reference' for 'fo:page-sequence'matches no 'simple-page-master' or 'page-sequence-master' @@ -168,26 +142,7 @@

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

- The Jimi image library, which is by default used for processing - images in PNG and other formats, was removed from the distribution - for licensing reasons. You have to download - and install it by yourself. -

- Extract the file "JimiProClasses.zip" from the archive you've downloaded, rename it to "jimi-1.0.jar" and move it to FOP's lib directory. -

- An alternative to Jimi is to use Sun's JAI. It is much faster, but - not available for all platforms. -

- - - + I get a NoClassDefFound exception.

@@ -212,7 +167,7 @@

- + I get a NoSuchMethodException or a NoSuchFieldException exception. @@ -228,77 +183,15 @@

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

- Increase memory settings of the JVM, see for example the - -Xmx option. 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. -
- Avoid forward references, that is page number citations to pages to - places on pages which follow the citation. 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 additional memory allocated for other purposes - could be freed after the page sequence has been rendered. -
- Break down large tables. 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 use markers to change them. -

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

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

- + I get a MalformedURLException. @@ -333,7 +226,7 @@ - + I get an "[ERROR]: null", or a NullPointerException.

@@ -365,7 +258,13 @@

- + + FOP returns the message "[ERROR] object|property - 'x' is not implemented yet." When will it be implemented? + +

See the article "Review FOP's Standards Compliance".

+ + + FOP hangs. FOP does not exit.

@@ -405,7 +304,7 @@

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

@@ -426,7 +325,7 @@ - + FOP does not find my fonts.

@@ -442,7 +341,69 @@

- + + + Problems with FOP output + + Why does FOP insert a blank page between my page sequences? + +

+ This is because spec conformance has been improved. +

+ The force-page-count + property controls how a FO processor pads page sequences in + order to get certain page counts or last page numbers. The default is + "auto". With this setting, if the next page sequence + begins with an odd page number because you set the + initial-page-number, and the current page sequence also ends with an + odd page number, the processor inserts a blank page to keep odd and + even page numbers alternating (similar for the case the current page + sequence ends with an even page number and the next page sequence + starts with an even page number. +

+ If you don't want to have this blank page, use + force-page-count="no-force". +

+ + + + Why is my graphic not rendered? + +

Most commonly, the external file is not being found by FOP. +Check the following:

Empty or wrong baseDir setting.
Spelling errors in the file name (including using the wrong case).
Security Problems (i.e. image was not delivered because FOP is not allowed to read the file). +This is especially a problem if the external file is retrieved over HTTP. +Possible issues include security settings on the server, server configuration, and missing cookies or other authorization information. +Any easy way to check this is to cut&paste the source URL from the fo:external-graphic into the Location field of a browser on the machine where the FOP process will be running.

Other possibilities:

The image format is not supported or not supported completely. See FOP Graphics Formats for a list of supported formats and related issues.
The graphic may be too large to fit into the intended space.
There may be something (static content) that is obscuring the graphic. (This is very rare). +

+ + + + My graphical images do not work properly. + +

See FOP Graphics Formats for a list of supported formats and related issues.

+ + + + Why is my graphic rendered at a different resolution than it was created? + +

See Graphics Resolution.

+ + + Keep-with-next, keep-with-previous, keep-together don't work. @@ -477,7 +438,7 @@ ]]> - + My tables are missing, or missing their content.

@@ -493,7 +454,7 @@

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

- + Page numbers are not properly right aligned.

@@ -540,43 +501,7 @@

- - A graphic is not displayed. - -

- The most common reason is that the file is not found because of an - empty or wrong baseDir setting, spelling errors in the file name, in - particular using the wrong case, or, if the image is retrieved over - HTTP, the image was not delivered because of security settings in the - server, missing cookies or other authorization information, or - because of server misconfigurations. One way to check this is to - cut&paste the source URL from the fo:external-graphic into the - Location field of a browser on the machine where the FOP - process will be running. -

- Several other 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). -

- - - - + Hyphenation does not work.

@@ -587,120 +512,48 @@ - + 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 Embedding FOP - for all kinds of details. + See Using FOP in a Servlet.

- + 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 idea, 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. + See Using FOP in a Servlet with XSLT Transformation.

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

- See the end of the answer for the question above. + See Using FOP in a Servlet with XSLT Transformation.

- + 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. + Declare the fonts in the userconfig.xml file as usual. +See loading the user configuration file for further details.

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

- Use: -

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

- or -

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

- See using a user configuration file - for caveats. + See Setting the Configuration Programmatically.

@@ -708,144 +561,41 @@ transformer.transform(xmlsource, new SAXResult(driver.getContentHandler()));How do I use a user configuration file from a servlet?

- Use: -

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

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

- + 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. + See Servlet Engines.

- + Can FOP be used in multithreaded environments?

- 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. + See Multithreading FOP.

- - Batik/SVG specific questions - - SVG text rendered in bad quality. How do I put SVG text as text - into PDF? + + SVG specific questions + + The rendering of SVG text in my PDF is of poor quality. +Can I control this? -

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

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

- - strokeSVGText - false -]]> -

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

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

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

- This does not work for other renderers. -

See Placing SVG Text into PDF.

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

See FOP: Graphics (Batik).

@@ -858,7 +608,7 @@ transformer.transform(xmlsource, new SAXResult(driver.getContentHandler())); - + I have problems with SVG referring to gradients etc. using "uri(#stuff)". I get a MalformedURLException. @@ -905,10 +655,16 @@ transformer.transform(xmlsource, new SAXResult(driver.getContentHandler()));See also MalformedURLException

+ + Why is my SVG rendered at a size different from that specified in my fo:external-graphic element? + +

See SVG Scaling.

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

@@ -917,7 +673,7 @@ transformer.transform(xmlsource, new SAXResult(driver.getContentHandler())); - + Some characters are not displayed, or displayed incorrectly, or displayed as “#”. @@ -943,25 +699,10 @@ transformer.transform(xmlsource, new SAXResult(driver.getContentHandler()));∅]]> - + What tools are available for post-processing my PDF document? -

- The most popular one that we are aware of is iText, which has tools - for adding security features, document properties, watermarks, and - many other features to PDF files. FOP and iText can be integrated - into one Java application, see sample code for encryption. - The bad news is that iText swallows PDF bookmarks. -
- You can use Adobe Acrobat (the full version, not the Reader) to - process the file manually or with scripting that it supports. -

See PDF Post-processing.

@@ -969,97 +710,25 @@ transformer.transform(xmlsource, new SAXResult(driver.getContentHandler()));

- FOP does not currently support this feature. Possible workarounds - include those mentioned in the PDF - Post-Processing FAQ. + See PDF Encryption. + See also PDF Post-processing.

- Some sample code for encrypting a FOP generated PDF with iText to - get you started: -

- -

- Check the iText tutorial and documentation for setting access flags, - password, encryption strength and other parameters. -

- - - + + + How do I add document properties (title, author, etc.) to my PDF document? -

FOP does not currently support this feature. Possible workarounds - include those mentioned in the PDF - Post-Processing FAQ.

See PDF Post-processing.

- + How do I add watermarks to my PDF document? -

FOP does not currently support this feature. Possible - workarounds:

- Use a background image for the body region. -
- See the PDF Post-Processing - FAQ. -
- (submitted by Trevor_Campbell@kaz.com.au) Place an image in a - region that overlaps the flowing text. For example, make - region-before large enough to contain your image. Then include a - block (if necessary, use an absolutely positioned block-container) - containing the watermark image in the static-content for the - region-before. Note that the image will be drawn on top of the - normal content. -

See PDF Watermarks.

- + The PDF is printed contorted!

@@ -1071,7 +740,7 @@ transformer.transform(xmlsource, new SAXResult(driver.getContentHandler())); - + How do I control the Acrobat bookmark display?

@@ -1082,9 +751,9 @@ transformer.transform(xmlsource, new SAXResult(driver.getContentHandler())); - + IEx specific stuff - + The FOP servlet is called multiple times!

@@ -1116,7 +785,7 @@ transformer.transform(xmlsource, new SAXResult(driver.getContentHandler())); - + How do I print PDF directly from the browser?

@@ -1140,89 +809,31 @@ transformer.transform(xmlsource, new SAXResult(driver.getContentHandler())); - - More general questions regarding XSLT and XSLFO and basic XML - + + General questions regarding XSLT, XSLFO, and basic XML + (FO) How do I vertically center an image or a table (or whatever)?

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

- - - - - - - - - - - - - - - - - - - - - - - -]]> - - - + See XSL-FO Vertical Centering. +

+ + + (FO) How do I center a table horizontally?

- You can add a column left and right wich pad the table so that the visible part is centered. -

- - - - - - - - - - - - - - - - - - foo - - - - - - - -]]> -

- If your table is more complicated, or if defining borders on individual cells becomes too much work, use the code above and nest your table within the moddle cell. -

- - - + See XSL-FO Horizontal Centering (Tables). +

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

- Place different static content on odd and even - pages. + See Recto/Verso Static Content Differences.

@@ -1231,462 +842,161 @@ transformer.transform(xmlsource, new SAXResult(driver.getContentHandler()));

- There are examples in the FO distribution and in the XSL FAQ FO - section. -

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

- - - - - - - - - - - - - - - - - - - - -

- - -

- - - - - - -]]> - - - + See Recto/Verso Static Content Differences. +

+ + + (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. - - - - - - - -]]> - - - + See Making the First Page Special. +

+ + + (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. - - - - - -]]> - - - + See Blank Pages. +

+ + + (FO) How do I print an Euro sign, a checkbox or other some other special symbols?

- Try to look the character 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. -

- For example, the following will result in an Euro sign: -

- -

- The selected font family must have a glyph for the character you want - to show. This is actually a somewhat tricky issue, especially for - symbol characters. -

- Some environments provide also a character table utility (like Win2K - or WinXP), which can also help you to get an idea what glyphs are - available in a certain font. -

- Alternative: Use an embedded graphic: GIF, PNG, SVG, whatever. + See Special Characters.

- + (FO) How do I keep linebreaks and 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). + See Preformatting Content.

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

- This is an 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: + See Total Document Pages.

- -

- 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 the 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. + See Aligning Regions.

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

- Several possibilities: + See Drawing Lines.

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

- + (FO) How do I validate my FO document?

- RenderX has provided an - Unofficial - DTD for FO Documents. This document may be helpful in - validating general FO issues. -

- FOP also maintains an Unofficial - FOP Schema in the FOP CVS Repository. This document can be - used either to validate against the FO standard, or against the - actual FOP implementation. See the notes near the beginning of the - document for instructions on how to use it. + See Validating XSL-FO.

- - (XML) There are complaints about  . How - do I get a non-breaking space in FO? + + (XML) How do I get a non-breaking space in FO? There are complaints about  .

- Use   everywhere. In your own XML, you could also use a DTD - which declares the entity. + See XML Special Characters.

- - (XML) There are complaints about undefined entities, for example - about ü which used to work in HTML. How do I enter - special characters like in HTML? + + (XML) How do I enter special characters in XML? There are complaints about undefined entities, such as ü, which work 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 + See XML Special Characters.

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

- Make sure ampersands in text and attributes are written as &, - "<" is written as < and ">" as >. 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. + See XML Entity Characters.

- + (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. + See XML Encoding Issues.

- - 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. - - Where to post bugs. + + I think I have found a bug in FOP. What should I do?

- See documentation. See also - "where to post - questions". + See the Bugs page for information about + bugs already reported and how to report new ones.

- Where to post questions. + I have questions that are not addressed in this FAQ. Where + should I post them? -

- Decide where to post: -

If your question is a development-related question, please see the Developer FAQs.
- 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, try to get local help first. Check bugzilla. If still not found, - post to fop-dev. + If you have a runtime exception or other runtime problem: +
- + double-check the Runtime FAQs. +
- + ClassNotFoundException, NoSuchMethodException and + NoSuchFieldException problems are almost always a problem with + the local environment. Try to get local help first. +
- + Check Reported Issues + to see if this is a known problem. +
- If none of the above apply, post a question to the fop-dev + mailing list. +
- 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. + In the case where something works properly with another formatter, + (AntennaHouse, PassiveTex, etc.) but doesn't work with FOP, please + check the Release Notes, the + FOP Standards Compliance document, + and the remaining FAQ in this document. If not found there, look at the + list of Bugs Already Reported. + If not found there, please post a question on the fop-user mailing list + or Open a New Bug.
Question about how to use FOP, how to perform certain tasks with FOP diff --git a/src/documentation/content/xdocs/fo.xml b/src/documentation/content/xdocs/fo.xml index 30af578c2..b0a8fdbd6 100644 --- a/src/documentation/content/xdocs/fo.xml +++ b/src/documentation/content/xdocs/fo.xml @@ -421,20 +421,6 @@ 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. -

- - - - - - - -]]> -

diff --git a/src/documentation/content/xdocs/fonts.xml b/src/documentation/content/xdocs/fonts.xml index 478b08a69..5ef9ff8d3 100644 --- a/src/documentation/content/xdocs/fonts.xml +++ b/src/documentation/content/xdocs/fonts.xml @@ -11,7 +11,16 @@ -

+ 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. @@ -27,12 +36,12 @@ The font is simply embedded into the PDF file, it is not converted.

- Adding additional Type 1 fonts +

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

@@ -61,7 +70,7 @@ java -cp build/fop.jar:lib/avalon-framework.jar:lib/xml-apis.jar: appear to have no visible influence.

Edit conf/userconfig.xml and add entries for the font @@ -92,13 +101,13 @@ java -cp build/fop.jar:lib/avalon-framework.jar:lib/xml-apis.jar:

- Adding additional TrueType +

+ 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 @@ -113,10 +122,10 @@ java -cp build/fop.jar:lib/avalon-framework.jar:lib/xml-apis.jar: 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 C:\myfonts\cmr10.ttf ttfcm.xml + C:\myfonts\cmr10.ttf ttfcm.xml

TrueType collections

TrueType collections (.ttc files) contains more than one @@ -141,7 +150,7 @@ java -cp build\fop.jar;lib\avalon-framework.jar;lib\xml-apis.jar;

Similiar to Type 1 fonts. @@ -153,16 +162,34 @@ java -cp build\fop.jar;lib\avalon-framework.jar;lib\xml-apis.jar;

Embedding fonts

- Font embedding is enabled in the userconfig.xml file and controlled over the embed-file attribute. - If you don't specify the embed-file attribute the fonts doesn't get embedded but only referenced. + 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. +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.

- - Remember to start fop with -c conf/userconfig.xml on the command line. -

+ + 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. + diff --git a/src/documentation/content/xdocs/gethelp.xml b/src/documentation/content/xdocs/gethelp.xml index b7587e61f..2c6342816 100644 --- a/src/documentation/content/xdocs/gethelp.xml +++ b/src/documentation/content/xdocs/gethelp.xml @@ -1,50 +1,83 @@ - - - -

- How to Get Help - Solving problems -

- - -

- How to get Help -

- Have a look at the documentation pages on this site. You can find information on how to run FOP, - how to embed it, how to add custom fonts etc. -
- Consult the FAQ to see if your question has already been answered before. -
- If you have a question concerning XSL:FO that is not related to FOP directly, please consult the various - resources on the net. See Resources for some interesting links. -
- Before you post your questions to one of the mailing lists, please search the mailing list archives, since it's - possible that your question has already been answered but it may not have found its way into the FAQ. You'll - find links to the mailing list archive in the Resources. -
- If you still can't solve your problem subscribe to FOP's user mailing list and post your question there. Please - don't forget to supply the version you're using, detailed error messages etc. This makes it easier to help you. - The instructions on how to subscribe can be found in the Resources -
-You should probably read ESR's -"How to Ask Questions the Smart Way" -

- - Please don't use Bugzilla to post questions and please ask on the user mailing list first, if you think you've - found a bug. - -

- +

+ Getting Help + Checklist for Finding Appropriate Resources +

+ +

The FOP developer community is eager to help you maximize the usefulness of FOP. +However, to make wise use of its limited resources, support must be primarily self-service. +Go through the following checklist sequentially to determine what kind of help you need, +and where to get it:

+ Understand Underlying Technologies +

If you have a questions about XML, XSLT, or XSL-FO that are not directly related to FOP, please consult resources that are appropriate for those questions. +FOP is an implementation of these technologies, and when you use FOP, there is a presumption that you have a working understanding of them. +We have included several useful links on our Resources page that may help you get started. +

+ Review FOP's Standards Compliance +

FOP is a work in progress, and does not yet fully comply with the W3C XSL-FO standard. +The developers track which standard requirements have been implemented, and have documented these capabilities on the Compliance page. +If this document appears to be in error, continue down this checklist so that either the document or the software can be corrected. +Otherwise, please do not submit mailing list questions or bug reports regarding features documented in the standard. +Please especially do not submit questions asking when a particular feature will be implemented. +There are too many unknowns to make even a reasonable estimate. +The only sure way to get a feature implemented is to pitch in and help.

+ Read the Documentation +

Review the documentation pages on this site. +There is information about how to run FOP, how to embed it, how to add custom fonts etc.

+ Check the FAQs +

Consult the Frequently Asked Questions (FAQ) to see if your question has already been answered.

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

+ Look for an Existing Issue Report +

See Reported Issues for instructions on how to use the list of open issues. Review these open issues to see if any match your concerns. +If so, please do not post a mailing list question or report another issue, as these will only slow the development team down.

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

+ Enter an Issue Report +

If, and only if, you have followed all of the above steps, and believe that there is a bug or needed feature that you would like to report, please enter an issue in Bugzilla. Never use Bugzilla to post questions, only to enter issues that have already been asked on the user mailing list.

See Reporting New Issues for detailed instructions on how to enter an issue. +

+ Find Out How <em>You</em> Can Help +

As stated above, the FOP development team is a limited resource. Most make their livings doing things other than writing and supporting FOP. Perhaps you need a feature from the XSL-FO standard to be implemented right away, or a bug fixed, or a new output format, or .... If so, there are several ways that you can help:

Become a FOP developer.
Fund a developer (or part of one). There is usually at least one FOP developer who would be glad to devote more time to FOP development if funding were in place.
Help out on the user mailing list. Users giving good answers to other users allows developers to focus more on development and less on support.

+ - diff --git a/src/documentation/content/xdocs/graphics.xml b/src/documentation/content/xdocs/graphics.xml index 83739703f..655f42594 100644 --- a/src/documentation/content/xdocs/graphics.xml +++ b/src/documentation/content/xdocs/graphics.xml @@ -20,7 +20,12 @@ BMP (Microsoft Windows Bitmap) bitmap - FOP native + JIMI or JAI + + + CUR + unknown + JIMI EPS (Encapsulated PostScript) @@ -32,25 +37,75 @@ 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) 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 - TIFF (Tag Image Format File) + TGA (Targa) + bitmap + JIMI + + + TIFF (Tag Image Format File) + bitmap + JIMI or JAI + + + XBM (X BitMap) bitmap - 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). + JIMI + + + XPM (X PixMap) + bitmap + JIMI

@@ -66,15 +121,14 @@ 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 {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. +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.

JAI - 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, install JAI, then copy the jai_core.jar and the jai_codec.jar files to {fop-install-dir}/lib. +To use it, simply install JAI. 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.

@@ -222,10 +276,6 @@ into a raster graphic are not drawn properly in PDF. The image is opaque.

- TIFF -

TIFF images with JPEG or CCITT content are passed through by FOP natively. Other TIFF subformats are handled by JAI.

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:

@@ -237,20 +287,5 @@ 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/implemented.xml b/src/documentation/content/xdocs/implemented.xml deleted file mode 100644 index a3a700724..000000000 --- a/src/documentation/content/xdocs/implemented.xml +++ /dev/null @@ -1,256 +0,0 @@ - - - - -

-Implemented -

- -

- Features -

- What's Implemented? -

The following formatting objects and properties of the XSL-FO 1.0 - W3C Recommandation are implemented. Please have also a look at the - section on limitations. -

- 1) Formatting Objects -

This section follows the table "B Formatting Object Summary" in the xsl:fo specification. At the - end of each sub-section you find listed what is not implemented.

- -

- B.1 Declaration and Pagination and Layout Formatting Objects -

root
page-sequence
page-sequence-master
single-page-master-reference
repeatable-page-master-reference
repeatable-page-master-alternatives
conditional-page-master-reference
layout-master-set
simple-page-master
region-body
region-before
region-after
region-start
region-end
flow
static-content

Not implemented: declarations, color-profile, title

- -

- B.2 Block Formatting Objects -

block
block-container (limited)

- -

- B.3 Inline Formatting Objects -

character
external-graphic
inline
instream-foreign-object
leader
page-number
page-number-citation, see limitations

Not implemented: bidi-override, initial-property-set, inline-container

- -

- B.4 Table Formatting Objects -

table
table-body
table-cell
table-column
table-footer
table-header
table-row

Not implemented: table-and-caption, table-caption

- -

- B.5 List Formatting Objects -

list-block
list-item
list-item-body
list-item-label

- -

- B.6 Link and Multi Formatting Objects -

basic-link (internal and external)

Not implemented: multi-switch, multi-case, multi-toggle, - multi-properties, multi-property-set

- -

- B.7 Out-of-line Formatting Objects -

footnote
footnote-body

Not implemented: float

- -

- B.8 Other Formatting Objects -

wrapper
marker, retrieve marker

- -

- 2) Properties -

Property values can be computed. Compound properties are also understood by Fop.

background-color
background-image
blank-or-not-blank
border-after-color
border-after-style
border-after-width
border-before-color
border-before-style
border-before-width
border-bottom
border-bottom-color
border-bottom-style
border-bottom-width
border-color (only one value allowed)
border-end-color
border-end-style
border-end-width
border-left
border-left-color
border-left-style
border-left-width
border-right
border-right-color
border-right-style
border-right-width
border-start-color
border-start-style
border-start-width
border-style
border-top
border-top-color
border-top-style
border-top-width
border-width
bottom
break-after
break-before
character
color
column-count
column-gap
column-width
country
end-indent
extent
external-destination
flow-name
font-family
font-size
font-style
font-weight
height
hyphenate
hyphenation-character
hyphenation-push-character-count
hyphenation-remain-character-count
id
initial-page-number
internal-destination
keep-with-next (broken)
language
leader-alignment (not value "page")
leader-length (see limitations)
leader-pattern (not value "use-content")
leader-pattern-width
left
letter-spacing
line-height
margin (only on pages and regions)
margin-bottom (only on pages and regions)
margin-left (only on pages and regions)
margin-right (only on pages and regions)
margin-top (only on pages and regions)
master-name
master-reference
maximum-repeats
number-columns-spanned
odd-or-even
padding (only one value allowed)
padding-after
padding-before
padding-bottom
padding-end
padding-left
padding-right
padding-start
padding-top
page-height
page-position
page-width
position (allowed values: "static" (default),"relative", "absolute", fixed )
provisional-distance-between-starts
provisional-label-separation
ref-id
region-name
right
rule-style
rule-thickness
space-after.optimum
space-before.optimum
span
src
start-indent
table-omit-footer-at-break
table-omit-header-at-break
text-align
text-align-last
text-decoration
text-indent
top
white-space-collapse
width
wrap-option

All other properties are not implemented.

- -

- 3)SVG Support -

-FOP uses Batik directly for its SVG support. Therefore FOP supports the same -elements and properties as are supported by Batik. As FOP is designed for -rendering to a static medium then only static SVG is rendered. -

-Due to some limitations in PDF some SVG images, particularly ones with effects -or transparency, may not come out correctly. The images should still be renderedcorrectly for the AWT and Print renderers. -

- - - diff --git a/src/documentation/content/xdocs/index.xml b/src/documentation/content/xdocs/index.xml index e19aa2ddf..e1f0ebc2e 100644 --- a/src/documentation/content/xdocs/index.xml +++ b/src/documentation/content/xdocs/index.xml @@ -7,67 +7,42 @@ FOP -

Introduction

FOP (Formatting Objects Processor) is the world's first print formatter driven by XSL formatting - objects and the world's first output independent formatter. It is a - Java application that reads a formatting object tree and then + objects (XSL-FO) and the world's first output independent formatter. It is a + Java application that reads a formatting object (FO) tree and renders the resulting pages to a specified output. Output formats - currently supported are PDF, PCL, PS, SVG, XML (area tree representation), + currently supported include PDF, PCL, PS, SVG, XML (area tree representation), Print, AWT, MIF and TXT. The primary output target is PDF.

- - The PDF files on this site are created using current CVS. -

The latest version of FOP is 0.20.5 and it supports the +

The latest version of FOP (0.20.5) is a partial implementation of the XSL-FO Version 1.0 W3C Recommendation. - You can download - FOP including a precompiled version, the source code and many example files to - get you started. Pointers to introductions into xsl:fo can be found in the - resources section. Please be aware, that - FOP is at the moment not a full implementation of the basic conformance level - of the xsl:fo standard. You can find a list of supported flow objects and properties - in the section Features and in section - Limitations in what way this support is - limited. + Support for each of the standard's objects and properties is detailed in FOP Compliance. + Download options include a precompiled version, source code, and many example files to get you started. Resources include links to XSL-FO introductions and many other useful references. A checklist for Getting Help will guide you toward maximizing the usefulness of FOP.

FOP is part of Apache's XML project. The homepage of FOP is - http://xml.apache.org/fop. - Here you can find information about using and developing with FOP. +

FOP is proud to be part of Apache's XML project.

Users can subscribe to fop-user@xml.apache.org by sending an email - to fop-user-subscribe@xml.apache.org - this is where user specific topics are discussed. -

- Formatting +

+ Demonstration

-This image is a demonstration of a two page document. The xml data on the left -is formatted into the two pages on the right. The document contains static areasthat appear on every page, an external graphic in this case an svg document. -There is a footnote on the first page and a table that goes across both pages. +This image is a demonstration of a real two page document. The xml data on the left +is formatted into the two pages on the right. The document contains static areas that appear on every page, an external graphic, a footnote on the first page, and a table that goes across both pages.

-The advantage of XSL is the ability to take an XML document and to format -the information into a page layout. The XML document can be generated -in any way, the most common would be to use XSLT. FOP takes the XML -and formats the data into pages. The pages are then rendered to the -requested output. -

-This is a real document. The image was created by rendering the document -to the svg renderer then putting the rendered pages into an svg document -along with the xml. -

+FOP uses the standard XSL-FO file format as input, lays the content out into pages, then renders it to the requested output. +One great advantage to using XSL-FO as input is that XSL-FO is itself an XML file, which means that it can be conveniently created from a variety of sources. +The most common method is to convert semantic XML to XSL-FO, using an XSLT transformation.

FOP Objectives -

The goals of the Apache XML FOP Project are to deliver an XSL FO->PDF formatter that is compliant to at least the Basic +

The goals of the Apache XML FOP Project are to deliver an XSL-FO to PDF formatter that is compliant to at least the Basic conformance level described in the W3C Recommendation from 15 October 2001, and that complies with the 11 March 1999 Portable Document Format Specification (Version 1.3) from Adobe Systems.

@@ -77,10 +52,11 @@ along with the xml. Project will attempt to use the latest version of evolving specifications.

To reach this aim currently the layout system is being redesigned to -better handle the formatting of all different types of formatting objects. -

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. + diff --git a/src/documentation/content/xdocs/involved.xml b/src/documentation/content/xdocs/involved.xml deleted file mode 100644 index bd90a7d89..000000000 --- a/src/documentation/content/xdocs/involved.xml +++ /dev/null @@ -1,90 +0,0 @@ - - - - -

- Getting Involved - How to Get Involved in FOP -

- - -

- Getting involved -

-There are many different levels where people can get involved. The -development of FOP and the related plans and tasks are discussed on -the dev mailing list. Users can help or get issues resolved by -contributing information and examples to the developers. -

- -

- Get familiar with the Fop related standards -

-At the moment Fop is mainly a tool to render XSL:FO files to pdf. -Therefore if you want to contribute to Fop you should become -familiar with these standards. You can find links under -Resources. -

- 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 -internally will be kept. -

- -

- Subscribe to the fop developers list -

You can subscribe to fop-dev@xml.apache.org by sending an email - to fop-dev-subscribe@xml.apache.org

Sending bug reports and feature requests to the list is a welcome and important contribution to - developing Fop.

Read also the archive - of the discussion list fop-dev to get an idea of the issues being discussed.

- Look at the developer's code using cvs -

Between releases the newest code can be accessed via cvs. To do this you need to install a cvs - client on your computer, if it is not already there. An explanation how to connect to the - Fop source repository can be found at http://xml.apache.org/cvs.html. - An introduction into cvs and the cvs manual can be found in the - reference library.

All changes to the code repository are sent to a special mailing list. After a cvs commit the diffs are automatically sent to this list. You can subscribe - to fop-cvs@xml.apache.org by sending an email to - fop-cvs-subscribe@xml.apache.org. If you want to contribute to the development of Fop you should subscribe, - because it is important that you follow changes being made.

- Contributing code, tests and documentation -

If you want to contribute code (p.e. a bugfix), a test or documentation (p.e. an additional example), please do the following:

1) Make sure your code doesn't break the existing one and that Fop still compiles.

2) Create a file which shows the differences to the existing code.

3) Send this file as an Attachment to fop-dev@xml.apache.org.

One of the committers will test your code and commit it to the code repository.

If you have a test or useful bug test you should read this page.

BTW: The Apache project knows different roles for contributors, namely 'users', 'developers', 'committers' and the 'Project - Management Committee' (An explanation of these roles can be found here).

- -

- Coding Conventions -

As mentioned in Apache XML Project Guidelines, - all Java Language source code in the repository must be written in conformance to the - Code Conventions - for the Java Programming Language as published by Sun. Additionally we agreed on 4 - spaces (no tabs) for indenting.

If you don't like those conventions, just use your own standards while developing and reformat the source before - committing with a tool like astyle (Artistic Style). -

- -

- - - diff --git a/src/documentation/content/xdocs/limitations.xml b/src/documentation/content/xdocs/limitations.xml deleted file mode 100644 index 4772555d0..000000000 --- a/src/documentation/content/xdocs/limitations.xml +++ /dev/null @@ -1,79 +0,0 @@ - - - - -

- Limitations -

- - -

- Limitations -

FOP implements the fo objects and properties listed - in features, sometimes it does so only in a limited way. -

- -

- fo:leader -

leader-length.minimum is not used at all

- -

- page-number-citation -

Only works for table of contents without any problems. The case where the page number doesn't - fit on a line isn't handled, and any text on the same line and after the page-number might not - appear exactly where you want it to. -

- -

- Padding -

Padding works in conjunction with indents and spaces. It is only implemented - for blocks. At the moment padding can't be used to make extra space (indents+spaces - must be used), but only to control how much the background-color extends beyond - the content rectangle. -

- Tables -

There two limitations for tables: 1) FOP needs you to explicitly specify column widths - 2) Cells have to contain block-level FOs. They can't contain straight character data. -

A working basic example of a table looks like this:

- - - - - - - text - - - text - - - - - text - - - text - - - - - text - - - text - - - -]]> -

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

+ 18 February 2003 - FOP 0.20.5 Release Candidate 2 available +

+ See the full text of the announcement. +

+ 2 February 2003 - New XML PMC +

+ Jeremias Maerki and Peter B. West are now representing FOP on the XML PMC. +

28 January 2003 - FOP logo contest

We are looking for a new logo. FOP logo @@ -44,7 +57,7 @@

Welcome Oleg Tkachenko!

- 7 Jul 2002 FOP 0.20.4 released + 7 July 2002 FOP 0.20.4 released

Changes since 0.20.3 include:

@@ -58,7 +71,7 @@ The following JARs have been updated: Xerces to version 2.0.1, Xalan to version 2.3.1 and Batik to version 1.5beta2.

Fop has been compiled with Jimi support

FOP has been compiled with Jimi support

Logging has been changed from LogKit to Avalon's Logger Interface @@ -82,7 +95,7 @@

- 13 Jun 2002 FOP 0.20.4 Release Candidate available + 13 June 2002 FOP 0.20.4 Release Candidate available

See the full text of the Welcome Jeremias Maerki, Joerg Pietschmann and Peter B. West!

- 11 March 2002 - Fop 0.20.3 released + 11 March 2002 - FOP 0.20.3 released

This is a maintenance release, the first version which supports the XSL-FO Recommendation syntax. See the diff --git a/src/documentation/content/xdocs/output.xml b/src/documentation/content/xdocs/output.xml index 69a01863c..3ba4a509a 100644 --- a/src/documentation/content/xdocs/output.xml +++ b/src/documentation/content/xdocs/output.xml @@ -5,8 +5,7 @@

- Output - Notes about Output Formats: Renderers + FOP Output Options @@ -14,54 +13,34 @@

- Output Formats

-FOP supports a number of different output formats. This is achieved by -using different renderers that create the output. +FOP supports multiple output formats by using a different renderer for each format. +The renderers do not all have the same set of capabilities, sometimes because of the output format itself, sometimes because some renderers get more development attention than others.

+ General Information +

+ Fonts

-Here we will explain some information for uses to be able to understand -what the renderers are doing and what difference there may be between -different renderers. +Most FOP renderers use a FOP-specific system for font registration. +However, the AWT and print renderers use the java awt package, which gets its font information from the operating system registration. +This can result in several differences, including actually using different fonts, and having different font metrics for the same font. +The net effect is that the layout of a given FO document can be quite different between renderers that do not use the same font information.

- Common Information -

-Each renderer is given an area tree to render to its output format. -The area tree is simply a representation of the pages and the placement -of text and graphical objects on those pages. -

-The renderer will be given each page as it is ready and an output stream -to write the data out. The renderer is responsible for managing the -output format and associated data and flow. -

-Fonts and Layout - some formats (eg. PDF and AWT) rely on different -font information. The fonts for these outputs have different sizes -for the same point size. This means that the layout can be quite -different for the same FO document. -

-DPI - This is an important issue when creating output for printing. -The dpi is used to convert measurements into points. For example 1in -= 2.54cm = 72 points. It is also used when determining the size of -images and the rendering of certain graphics in the output. Currently -FOP uses a value of 72dpi. +

+ Output to a Printer or Other Device +

+The most obvious way to print your document is to use the FOP print renderer, which uses the Java API (AWT). +However, you can also send output from the Postscript renderer directly to a Postscript device, or output from the PCL renderer directly to a PCL device.

-You may want to send your output directly to a printer. The print -renderer can use the Java API to print the document. You might also be -able to send the output stream directly to a printer. If your printer -supports postscript you could send the postscript to the printer. If -you have a printer that supports PCL you could stream the PCL document -to your printer. -On Windows, you can use: +Here are Windows command-line examples for Postscript and PCL:

- + +

-On UNIX: +Here is some Java code to accomplish the task in UNIX:

@@ -69,10 +48,11 @@ out = proc.getOutputStream();]]> Set the OutputStream (out) to the PCLRenderer and it happily sends the PCL to the UNIX printer queue.

PDF -

PDF is the best supported output format. It is also the most accurate with text and layout. This creates a PDF document that is streamed out as each page is rendered. This means that the internal page index @@ -80,8 +60,10 @@ information is stored near the end of the document. The PDF version supported is 1.3 which is currently the most popular version for Acrobat Reader (4.0), PDF versions are forwards/backwards compatible. -

- +

Note that FOP does not currently support "tagged pdf".

+ Fonts

PDF has a set of fonts that are always available to all PDF viewers, to quote from the PDF Specification: @@ -93,8 +75,81 @@ Helvetica, and Times), as well as two symbolic fonts (Symbol and ITC Zapf Dingbats). These fonts, or suitable substitute fonts with the same metrics, are guaranteed to be available in all PDF viewer applications."

+ Post-processing +

FOP does not currently support several desirable PDF features: document properties (title, author, etc.), and watermarks. One workaround is to use Adobe Acrobat (the full version, not the Reader) to process the file manually or with scripting that it supports.

Another popular post-processing tool is iText, which has tools for adding security features, document properties, watermarks, and many other features to PDF files. +

+ Caveat: iText swallows PDF bookmarks. +

Here is some sample code that uses iText to encrypt a FOP-generated PDF. (Note that FOP now supports PDF encryption. However the principles for using iText for other PDF features are similar.)

+ +

Check the iText tutorial and documentation for setting access flags, password, encryption strength and other parameters. +

+ Watermarks +

+ In addition to the PDF Post-processing options, consider the following workarounds: +

+ Use a background image for the body region. +
+ (submitted by Trevor_Campbell@kaz.com.au) Place an image in a + region that overlaps the flowing text. For example, make + region-before large enough to contain your image. Then include a + block (if necessary, use an absolutely positioned block-container) + containing the watermark image in the static-content for the + region-before. Note that the image will be drawn on top of the + normal content. +

PCL

This format is for the Hewlett-Packard PCL printers. @@ -108,7 +163,7 @@ in the "HP PCL 5 Printer Language Technical Reference Manual" (copyright 1990). This should allow any device fully supporting PCL 5 to be able to print the output generated by the PCLRenderer.

Limitations

Text or graphics outside the left or top of the printable area are not rendered properly. In general things that should print to the left of the printable area are shifted to the right so that they start at the left edge of the printable area and an error message is generated.

Additional Features

There are some special features that are controlled by some public variables on the PCLRenderer class.

@@ -145,7 +200,7 @@ print the output generated by the PCLRenderer.

PostScript

The PostScript renderer is still in its early stages and therefore still @@ -154,7 +209,7 @@ Images and SVG are not fully supported, yet. Currently, the PostScript renderer generates PostScript Level 3 with most DSC comments. Actually, the only Level 3 feature used is FlateDecode, everthing else is Level 2.

Limitations

Images and SVG may not be display correctly. SVG support is far from being complete. No image transparency is available.

RTF

This is currently not integrated with FOP but it will soon. @@ -175,7 +230,7 @@ attempt to contain as much information from the fo document as possible.

SVG

This format creates an SVG document that has links between the pages. @@ -188,7 +243,7 @@ same way as the AWT viewer, if the svg is view where the fonts are different, such as another platform, then the page will appear wrong.

XML

This is for testing and verification. The XML created is simply @@ -196,14 +251,14 @@ a representation of the internal area tree put into XML. It does not perform any other purpose.

It is possible to directly print the document from the command line. This is done with the same code that renders to the AWT renderer.

AWT

The AWT viewer shows a window with the pages displayed inside a @@ -212,14 +267,14 @@ The fonts used for the formatting and viewing depend on the fonts available to your JRE.

MIF

This format is the Maker Interchange Format which is used by Adobe Framemaker. This is currently not fully implemented.

TXT

Text as you could imagine does not work very well. It is an output format @@ -245,7 +300,6 @@ than text, so text will overwrite any graphic element representations.

diff --git a/src/documentation/content/xdocs/pdfencryption.xml b/src/documentation/content/xdocs/pdfencryption.xml index 48873e85f..b555fc832 100755 --- a/src/documentation/content/xdocs/pdfencryption.xml +++ b/src/documentation/content/xdocs/pdfencryption.xml @@ -12,7 +12,6 @@

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 diff --git a/src/documentation/content/xdocs/relnotes.xml b/src/documentation/content/xdocs/relnotes.xml index bd7bd3913..f60b8dbf3 100644 --- a/src/documentation/content/xdocs/relnotes.xml +++ b/src/documentation/content/xdocs/relnotes.xml @@ -14,11 +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. - We hope to resolve this issue until the final release. + no, pt, ru, sk, tr) have been removed due to licensing reasons. + We hope to resolve this issue before the final release. (English hyphenation is still available as en_GB)
Documentation is done with +
Documentation is now built with Forrest (version 0.3). You need to install Forrest if you want build the docs yourself. (See Using Forrest) @@ -26,19 +26,21 @@
The following JARs have been updated: Xerces to version 2.2.1, Xalan to version 2.4.1 and Batik to version 1.5beta4.
Fop has been compiled with Jimi support this time but you still have to download - Jimi, extract the archive, +
FOP has been compiled with Jimi support, but Jimi is not included in the + FOP distribution. To use it, first download + Jimi, then extract + the archive, then copy JimiProClasses.zip to FOP's lib dir and rename it to jimi-1.0.jar.
Fop has been compiled with - JAI - support. For using JAI you just need to install it. +
FOP has been compiled with JAI support, but JAI is not included in the + FOP distribution. To use it, simply install + JAI.
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 0.20.4 @@ -51,7 +53,7 @@

The following JARs have been updated: Xerces to version 2.0.1, Xalan to version 2.3.1 and Batik to version 1.5beta2.

Fop has been compiled with Jimi support this time +

FOP has been compiled with Jimi support this time but you still have to download Jimi and copy it to lib/ to get PNG support (no need to build FOP yourself though). diff --git a/src/documentation/content/xdocs/resources.xml b/src/documentation/content/xdocs/resources.xml index d83145499..af6c7c40c 100644 --- a/src/documentation/content/xdocs/resources.xml +++ b/src/documentation/content/xdocs/resources.xml @@ -1,7 +1,6 @@ -

@@ -9,171 +8,158 @@ Resources useful for developing and using FOP

- FOP Relevant Specifications and Links -

- Mailing Lists (and archives) -

-For the Apache mailing lists, see -Apache XML Mailing Lists -for detailed subscription information. -

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

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

- FOP Developer Mailing List -

-Use this forum to discuss topics related to FOP development, -including patch submissions, bug reports, and design issues. -

-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. -
-
-To subscribe (digest only): Send email to fop-dev-digest-subscribe@xml.apache.org. -
-To subscribe fully: Send email to fop-dev-subscribe@xml.apache.org. -
-For standard help: Send email to fop-dev-help@xml.apache.org. -
-To unsubscribe: Send email to fop-dev-unsubscribe@xml.apache.org. -

+ Specifications +

+ XSL-FO +

XSL-FO Recommendation (15 October 2001)
Unofficial DTD for the XSL-FO Recommendation provided by N. Grigoriev from RenderX.

+ XSLT +

XSLT Recommendation

+ XML +

XML Recommendation
Simple API for XML (SAX)
Document Object Model (DOM)
Namespaces in XML Recommendation

+ Java +

Java JDK 1.3 Documentation

+ Other +

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

+ Books, Tutorials, Articles +

+ XSL-FO +

[online book] The XML Bible, by Elliotte Rusty Harold. Chapter 18 of XSL Formatting Objects
[online article] Using Formatting Objects with the Slides DTD, by Paul Sandoz.
[online article] Using XSL Formatting Objects, by J. David Eisenberg.
[online reference] XSL FO reference, by Miloslav Nic.
[online book] An introduction to XSL Formatting Objects, by Dave Pawson. See hardcopy version below.
[book] XSL-FO, by Dave Pawson, O'Reilly & Associates, 2002, ISBN 0-596-00355-2. See online version above.
[book] Definitive XSL-FO, by G. Ken Holman, Prentice Hall PTR, 2003, ISBN 0-131-40374-5.
[book] XSL Formatting Objects Developer's Handbook, by Doug Lovell, Sams, 2002, ISBN 0-672-32281-1.
[book] Practical Formatting Using XSLFO, Crane Softwrights Ltd., 2003, ISBN 1-894049-11-X.

+ XSLT +

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

+ XML +

[online book] The XML Bible, by Elliotte Rusty Harold. See hardcopy version below.
[book] The XML Bible, by Elliotte Rusty Harold, John Wiley & Sons, ISBN 0-764-54760-7. See online version above.
[online resource] A great number of additional XML-related books and articles can be found at the O'Reilly XML Site.

+ Java +

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

- XSL:FO Mailing List (at W3C) -

-Use this forum to ask general XSL-FO questions. -

+ Related/Useful Products

-To review the archive: W3C XSL-FO Archives. -
-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. -
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."

- Specifications -

- XSL-FO Recommendation (15 October 2001) -
- A dtd for the XSL-FO Recommendation provided by N. Grigoriev from RenderX -
- Supported SVG Recommendation (04 September 2001) -
- XML Recommendation -
- XSLT Recommendation -
- Portable Document Format (PDF) 1.4 Reference Manual -
- Simple API for XML (SAX) -
- Document Object Model (DOM) -
- Namespaces in XML Recommendation -
- Java JDK 1.3 Documentation -

- Tutorials/Articles -

- Elliotte Rusty Harold: Chapter 18 on xsl:fo from his excellent book XML Bible, Second Edition -
- Paul Sandoz: Using formatting objects with the slides dtd -
- J. David Eisenberg: Using XSL Formatting Objects -
- Miloslav Nic: XSL FO reference -
- Dave Pawson: An introduction to XSL Formatting Objects -

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

- diff --git a/src/documentation/content/xdocs/running.xml b/src/documentation/content/xdocs/running.xml index 685b7da0e..3105f4271 100644 --- a/src/documentation/content/xdocs/running.xml +++ b/src/documentation/content/xdocs/running.xml @@ -3,83 +3,174 @@ "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/schema/dtd/document-v11.dtd"> -

- Running FOP -

+ Running FOP +

- -

- Installation -

- Overview + +

+ System Requirements

The following software must be installed:

Java 1.2.x or later.
FOP. The FOP distribution includes all libraries that you will need to run a basic FOP installation. These can be found in the xml-fop/lib directory. These libraries include the following:

Apache Xerces-J for XML parsing. You can use other XML parsers which support SAX and DOM.
Apache Xalan, an XSLT processor.
Apache Batik, an SVG library.

Optional Libraries
Java 1.2.x or later Runtime Environment.
FOP. The FOP distribution includes all libraries that you will need to run a basic FOP installation. These can be found in the xml-fop/lib directory. These libraries include the following: +
- Apache Xerces-J for XML parsing. You can use other XML parsers which support SAX and DOM.
- Apache Xalan-J, an XSLT processor.
- Apache Batik, an SVG library.
+

The following sofware is optional, depending on your needs:

Graphics libraries. Support for some graphics formats requires additional packages. See FOP: Graphics Formats for details.
PDF encryption. See FOP: PDF Encryption for details.

In addition, the following system requirements apply:

If you will be using FOP to process SVG, you must do so in a graphical environment. See FOP: Graphics (Batik) for details.

- Instructions -

Basic FOP installation consists of first unzipping the .gz file that is the distribution medium, then unarchiving the resulting .tar file in a directory/folder that is convenient on your system. Please consult your operating system documentation or Zip application software documentation for instructions specific to your site.

+ Installation +

+ Instructions +

+ Problems +

Some Mac OSX users have experienced filename truncation problems using Stuffit to unzip and unarchive their distribution media. This is a legacy of older Mac operating systems, which had a 31-character pathname limit. Several Mac OSX users have recommended that Mac OSX users use the shell command tar -xzf instead.

- Problems -

- -

- Starting FOP as a standalone application -

Review the batch file fop.bat or the shell script fop.sh to see how FOP is invoked.

The standard scripts for starting FOP require that the environment variable JAVA_HOME be set to a path pointing to the appropriate Java installation on your system. Macintosh OSX includes a Java environment as part of its distribution. We are told by Mac OSX users that the path to use in this case is /Library/Java/Home. Caveat: We suspect that, as Apple releases new Java environments and as FOP upgrades the minimum Java requirements, the two will inevitably not match on some systems. Please see Java on Mac OSX FAQ for information as it becomes available.

fop [options] [-fo|-xml] infile [-xsl file] [-awt|-pdf|-mif|-pcl|-ps|-txt|-svg|-at|-print] <outfile>

[OPTIONS]

- - -d debug mode
- -x dump configuration settings
- -q quiet mode
- -c cfg.xml use additional configuration file cfg.xml
- -l lang the language to use for user information
-

[INPUT]

- - infile xsl:fo input file (the same as the next)
- -fo infile xsl:fo input file
- -xml infile xml input file, must be used together with -xsl
- -xsl stylesheet xslt stylesheet
+

+ Starting FOP as a Standalone Application +

The usual and recommended practice for starting FOP from the command line is to run the batch file fop.bat (Windows) or the shell script fop.sh (Unix/Linux). +If you write your own scripts, be sure to review these standard scripts to make sure that you get your environment properly configured.

fop [options] [-fo|-xml] infile [-xsl file] [-awt|-pdf|-mif|-pcl|-ps|-txt|-svg|-at|-print] <outfile>

[OPTIONS]

+ + -d debug mode + -x dump configuration settings + -q quiet mode + -c cfg.xml use additional configuration file cfg.xml + -l lang the language to use for user information + -s (-at output) omit tree below block areas + -txt.encoding (-txt output encoding use the encoding for the output file. + The encoding must be a valid java encoding. + -o [password] pdf file will be encrypted with option owner password + -u [password] pdf file will be encrypted with option user password + -noprint pdf file will be encrypted without printing permission + -nocopy pdf file will be encrypted without copy content permission + -noedit pdf file will be encrypted without edit content permission + -noannotations pdf file will be encrypted without edit annotation permission +

[INPUT]

+ infile XSLFO input file (the same as the next) + -fo infile xsl:fo input file + -xml infile xml input file, must be used together with -xsl + -xsl stylesheet xslt stylesheet -

[OUTPUT]

- - outfile input will be rendered as pdf file into outfile
- -pdf outfile input will be rendered as pdf file (outfile req'd)
- -awt input will be displayed on screen
- -mif outfile input will be rendered as mif file (outfile req'd)
- -pcl outfile input will be rendered as pcl file (outfile req'd)
- -ps outfile input will be rendered as PostScript file (outfile req'd)
- -txt outfile input will be rendered as text file (outfile req'd)
+

[OUTPUT]

+ outfile input will be rendered as pdf file into outfile + -pdf outfile input will be rendered as pdf file (outfile req'd) + -awt input will be displayed on screen + -mif outfile input will be rendered as mif file (outfile req'd) + -pcl outfile input will be rendered as pcl file (outfile req'd) + -ps outfile input will be rendered as PostScript file (outfile req'd) + -txt outfile input will be rendered as text file (outfile req'd) -svg outfile input will be rendered as an svg slides file (outfile req'd) -at outfile representation of area tree as XML (outfile req'd) - -print input file will be rendered and sent to the printer
see options with "-print help"
- -

[Examples]

- - fop foo.fo foo.pdf
- fop -fo foo.fo -pdf foo.pdf (does the same as the previous line)
- fop -xsl foo.xsl -xml foo.xml -pdf foo.pdf
- fop foo.fo -mif foo.mif
- fop foo.fo -print or Fop -print foo.fo
- fop foo.fo -awt
-

- -

- Problems -

If you have problems running FOP, please have a look at the "How to get Help" page.

- - + -print input file will be rendered and sent to the printer + see print specific options with "-print help" +

[Examples]

+ fop foo.fo foo.pdf + fop -fo foo.fo -pdf foo.pdf (does the same as the previous line) + fop -xsl foo.xsl -xml foo.xml -pdf foo.pdf + fop foo.fo -mif foo.mif + fop foo.fo -print or fop -print foo.fo + fop foo.fo -awt +

PDF encryption is only available if FOP was compiled with encryption support and if compatible encryption support is availabe at run time. Currently, only the JCE is supported. Check the Details.

+ Using Xalan to Check XSL-FO Input +

FOP sessions that use -xml and -xsl input instead of -fo input are actually controlling two distinct conversions: Tranforming XML to XSL-FO, then formatting the XSL-FO to PDF (or another FOP output format). +Although FOP controls both of these processes, the first is included merely as a convenience and for performance reasons. +Only the second is part of FOP's core processing. +If a user has a problem running FOP, it is important to determine which of these two processes is causing the problem. +If the problem is in the first process, the user's stylesheet is likely the cause. +The FOP development team does not have resources to help with stylesheet issues, although we have included links to some useful Specifications and Books/Articles. +If the problem is in the second process, FOP may have a bug or an unimplemented feature that does require attention from the FOP development team.

+ The user is always responsible to provide correct XSL-FO code to FOP. +

In the case of using -xml and -xsl input, although the user is responsible for the XSL-FO code that is FOP's input, it is not visible to the user. To make the intermediate FO file visible, the FOP distribution includes xalan.bat (Windows batch file) and xalan.sh (Unix/Linux script), which run only the first (transformation) step, and write the results to a file.

+ When asking for help on the FOP mailing lists, never attach XML and XSL to illustrate the issue. Always run the xalan script and send the resulting XSL-FO file instead. Of course, be sure that the XSL-FO file is correct before sending it. +

+ The scripts are invoked the same way that Xalan is: +

+ xalan -in xmlfile -xsl file -out outfile +

+ Note that there are some subtle differences between the "fop" and "xalan" command lines. +

+ Memory Usage +

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

+If you are running out of memory when using FOP, here are some ideas that may help: +

+Increase memory available to the JVM. See the -Xmx option for more information. + +(Warning: It is usually unwise to increase the memory allocated to the JVM beyond the amount of physical RAM, as this will generally cause significantly slower performance.) + +
+Avoid forward references. +Forward references are references to some later part of a document. +Examples include page number citations which refer to pages which follow the citation, tables of contents at the beginning of a document, and page numbering schemes that include the total number of pages in the document ("page N of TOTAL"). +Forward references cause all subsequent pages to be held in memory until the reference can be resolved, i.e. until the page with the referenced element is encountered. +Forward references may be required by the task, but if you are getting a memory overflow, at least consider the possibility of eliminating them. +A table of contents might be eliminated, relying on PDF bookmarks instead. +Or it might be moved to the end of the document without dimishing its value very much. +Or, in some circumstances, the paper could even be reshuffled after printing. +
+Avoid large images, especially if they are scaled down. +If they need to be scaled, scale them in another application upstream from FOP. +For many image formats, memory consumption is driven mainly by the size of the image file itself, not its dimensions (width*height), so increasing the compression rate may help. +
+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 additional memory allocated for other purposes could be freed after the page sequence has been rendered. +
+Break down large tables. +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. +

+There are currently some bugs which cause FOP to go into a nonterminating loop, which will also often result in a memory overflow. +A characteristic symptom is continuous box overflows in the log. +Most of these loops are triggered by elements that do not fit in the available space, such as big images or an improperly specified width in nested block elements. +The only workaround is to locate such problems and correct them. +

+One of FOP's stated design goals is to be able to process input of arbitrary size. +Addressing this goal is one of the prime motivations behind the FOP Redesign. +

+ Problems +

If you have problems running FOP, please see the "How to get Help" page.

+ diff --git a/src/documentation/content/xdocs/svg.xml b/src/documentation/content/xdocs/svg.xml deleted file mode 100644 index 346e297b4..000000000 --- a/src/documentation/content/xdocs/svg.xml +++ /dev/null @@ -1,136 +0,0 @@ - - - - - - -

- SVG - Embedding SVG in FOP -

- - - -

- SVG in FOP -

- Introduction -

-FOP uses the SVG library from Batik to handle SVG. -This format can be handled as an fo:instream-foreign-object or in a separate -file referenced with fo:external-graphic. Either way the SVG document will be -read in and converted into a DOM in Batik. This DOM will then be used by the renderer to -create the graphical image. -

-The AWT and Print renderers simply use batik to draw the SVG into a graphic. -

-In the case of the PDF renderer there is a PDFGraphics2D class that Batik uses -to render the image into. This class converts the drawing instructions into -PDF markup which is placed into the current PDF document. -

- -

- Converting SVG to a PDF Document -

-It is possible to convert a standalone SVG document directly into a simple page PDF document. -This is possible through the use of Batik's transcoder mechanism.
-java org.apache.batik.apps.rasterizer.Main -m application/pdf document.svg -
-This will output the svg document as "document.pdf" containing a PDF rendering of -the SVG file. -

-It is also possible to specify the width and/or height of the PDF document on the command line with -w and -h or if you are using the transcoder api you can use the transcoding hints. -

-Currently the SVG image is drawn at the SVG document size and simply scaled in PDF to the new size. So the result may not be the best possible. For example if you have any images or effects it will draw them at the original resolution of the svg document. When this is viewed in the pdf it will have an incorrect resolution for the size of the pdf. -

-The size of the pdf file will also remain the same regardless of what size the page is. -

-For more information see Batik for -how transcoders work. -

- -

- Important Notes -

-The svg is inserted into PDF by using PDF commands to draw and fill -lines and curves. This means that the graphical objects created with -this remain as vector graphics. -

-There are a number of SVG things that cannot be converted directly into -PDF. Parts of the graphic such as effects, patterns and images are inserted -into the PDF as a raster graphic. The resolution of this graphic may not -be ideal depending on the FOP dpi (72dpi) and the scaling for that graphic. -This needs to be improved. -

-Another important note is that text is converted and drawn as a -set of shapes by batik. This means that a typical character will -have about 10 curves (each curve consists of at least 20 characters). -This can make the pdf files large and when the pdf is viewed the -viewer does not normally draw those fine curves very well (turning on -Smooth Line Art in the Acrobat preferences will fix this). -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 by adding the following to the user config: -

- - strokeSVGText - false -]]> -

-The drawback from this is that all text 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. -

-Currently transparency is not supported in PDF so many svg images that -contain effects or graphics with transparent areas will not be displayed -correctly. -

- -

- Classes -

-These are the relevant classes, found in the package org.apache.fop.svg : -

PDFGraphics2D -
-used for drawing onto a Graphics2D into an existing pdf document, used -internally to draw the svg. -
PDFDocumentGraphics2D -
-used to create a pdf document and inherits from PDFGraphics2D to do the -rest of the drawing. Used by the transcoder to create a standalone pdf -document from an svg. Can be used independantly the same as any Graphics2D. -
PDFTranscoder -
-used by Batik to transcode an svg document into a standalone pdf, via -PDFDocumentGraphics2D. -

- -

- - - diff --git a/src/documentation/content/xdocs/tabs.xml b/src/documentation/content/xdocs/tabs.xml index b40e054f4..5779f261f 100644 --- a/src/documentation/content/xdocs/tabs.xml +++ b/src/documentation/content/xdocs/tabs.xml @@ -2,11 +2,14 @@ - - - - - + + + + + + + + diff --git a/src/documentation/content/xdocs/testing.xml b/src/documentation/content/xdocs/testing.xml deleted file mode 100644 index 3218de2c4..000000000 --- a/src/documentation/content/xdocs/testing.xml +++ /dev/null @@ -1,108 +0,0 @@ - - - - -

- Testing FOP -

- - -

- Running and Using Tests -

-Testing is an important part of getting FOP to operate correctly and conform to the -necessary standards. -

-A testing system has been set up that works with as a build target when developing -with FOP. A developer can run the tests after making changes to the code, the aim -is to have the tests run to verfiy that nothing working has been broken. -

-To setup the testing the developer must place a reference fop.jar in the -"<cvs_repository>/test/reference/" directory. This jar will be dynamically -loaded to create the reference output. -

- -

- W3C TestSuite -

-The testing is set up so that you can download the testsuite from -http://www.w3.org/Style/XSL/TestSuite/, -unzip the file into the base directory of FOP. -Then you can uncomment the lines in the build.xml file in the test target and itwill run through all the tests in the testsuite distribution. -

- -

- Writing a Test -

-A test belongs to one of a few catagories. A basic test should excercise one -element in a number of situations such as changing a property. This should have -at least one normal value, one border value and one invalid value. If the property -can be of different types then this should also be included. -

-A bug test is a test that is specifically aimed at a problem with FOP. That is, the test -is not excercising the specification but rather a problem with FOP in handling a particular -situation that is not exposed with the other testing. -

-A system test is one that tests the abitlity of FOP to handle a number of different -elements together. -

-A test can consist of a complete fo document or a part of the document such as -some elements that will be placed into the flow of a standard document. -

- -

- Submitting a Test -

-If you have a test which you think would be useful you should supply the -test and a diff to the appropriate test suite xml file. Make sure that the -test works as would be expected against the current build. -

- -

- How Testing Works -

-The tests are stored in the "<cvs_repository>/test" directory. -

-You can run the tests by specifying the build target "test" ie:
-build.sh test -

-This will then compare the current code in the local src directory to a specified -release of FOP. Any differences between the current code and the output from -the reference version will be reported. If the test previously passed then the -test run will have failed. -

-The testing is done by reading a test suite xml file, which corresponds to the -standard testsuite.dtd supplied from w3c. This xml file contains a test xml -file and an xsl file (which may simply copy the file). It also contains information -such as if the test has passed and any comments. -

-For FOP the testing is done by rendering all the testing documents using the -XML renderer. The XML files are then compared to see if there are any differences. -

- -

- SVG Testing -

-The testing of SVG is not part of this testing system. SVG is tested for its rendering -accuracy by using the transcoding mechanism via Batik. So that the only part that needs -testing is how the SVG image is embedded inside the flow of the fo document. -

- - - diff --git a/src/documentation/resources/schema/dtd/compliance-v10.dtd b/src/documentation/resources/schema/dtd/compliance-v10.dtd index f2d59cb8a..1421a0eab 100644 --- a/src/documentation/resources/schema/dtd/compliance-v10.dtd +++ b/src/documentation/resources/schema/dtd/compliance-v10.dtd @@ -1,8 +1,9 @@ - + + @@ -26,6 +29,7 @@ name CDATA #REQUIRED extURL CDATA #IMPLIED citation CDATA #IMPLIED + ref-name CDATA #IMPLIED > diff --git a/src/documentation/sitemap.xmap b/src/documentation/sitemap.xmap index ab029291e..3303c65be 100644 --- a/src/documentation/sitemap.xmap +++ b/src/documentation/sitemap.xmap @@ -1,355 +1,559 @@ - - + + + - - - - - - - - - - - - - - - - false - false - false - - - - - - - - - - - - -//W3C//DTD HTML 4.01 Transitional//EN - ISO-8859-1 - - - - ISO-8859-1 - - - - - - - ISO-8859-1 - - - - - + - + - - - - + - + - - - - - - - - + + + - - - - - - + + + //*[local-name() = 'section'] + title/text() + - + + + + + /site// + /@href + + - + - - - - - - - - - - - - - - - - - - - - - + + false + false + false + + + - - - - - - - + + - - - + + + - + + + -//W3C//DTD HTML 4.01 Transitional//EN + http://www.w3.org/TR/html4/loose.dtd + ISO-8859-1 + - + + ISO-8859-1 + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + -//Netscape Communications//DTD RSS 0.91//EN + http://my.netscape.com/publish/formats/rss-0.91.dtd + ISO-8859-1 + - - - - - - - - + - - - - - - - + + ISO-8859-1 + - - + + + - - - - - - - + + - - + + + + + - + + + - - - - - - - - + + +--> + + + - - - - + + + + - - - - - - - - + + + - - - - - - - - + + + - - - - - - - - - - - - + + + + + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + - - - - - - - - - - - - - - + + + + - - - - - - - - - - - - - - - - - + + + - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + @@ -378,97 +582,190 @@ + + + + + - - - + + + + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + - - - - - - - - - - - - - - - - - - - - + - - - - - - - - - + + + + - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + @@ -479,124 +776,120 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/documentation/skinconf.xml b/src/documentation/skinconf.xml index cc1b1d99d..9cbf6d058 100644 --- a/src/documentation/skinconf.xml +++ b/src/documentation/skinconf.xml @@ -11,9 +11,14 @@ jefft@apache.org - + - + + + @@ -23,6 +28,7 @@ jefft@apache.org + @@ -60,7 +66,7 @@ jefft@apache.org - 1999-2002 + 1999-2003 The Apache Software Foundation. - + + + Created by: FOP 1.0dev + http://xml.apache.org/fop/dev + images/logo.jpg + 138 + 31 -- 2.39.5