XMLmind FO Converter XMLmind XSL-FO Converter v4.2p1 - User's Guide Jean-Yves Belmonte, Pixware <xfc-support@xmlmind.com> February 22, 2008 Table of Contents Introduction PAGEREF d0e45 0 Features PAGEREF d0e74 0 Features PAGEREF d0e77 0 Limitations PAGEREF d0e141 0 Installation PAGEREF d0e179 0 System requirements PAGEREF d0e182 0 Installation PAGEREF d0e215 0 Contents of the distribution PAGEREF d0e288 0 Command-line executables PAGEREF d0e523 0 Java ™ version PAGEREF d0e526 0 .NET version PAGEREF d0e678 0 Implementation notes PAGEREF d0e802 0 Page references PAGEREF d0e805 0 Leaders PAGEREF d0e864 0 Special characters PAGEREF d0e901 0 Multiple page layouts PAGEREF d0e922 0 Expressions PAGEREF d0e947 0 XSL-FO extension for Office Open XML PAGEREF d0e974 0 What it is PAGEREF d0e977 0 How it works PAGEREF d0e985 0 Reference Material PAGEREF d0e1147 0 XSL Utility PAGEREF d0e1641 0 Modification history PAGEREF d0e1704 0 Notice PAGEREF d0e2530 0 Introduction XMLmind XSL-FO Converter (XFC for short) is a software component designed to convert XSL Formatting Objects (XSL-FO) to various formats compatible with popular word processors. Currently supported formats are RTF, WML, Office Open XML and OpenDocument. The RTF output conforms to version 1.6 of the specification and is compatible with MS-Word 2000+. The WML output is compatible with MS-Word 2003+, while the Office Open XML output is compatible with MS-Word 2007 only. The OpenDocument output is compatible with OpenOffice 2.0.2+. All formats preserve the structure of the original document and most of the presentation information (font attributes, indentation, etc). XMLmind XSL-FO Converter is available in two versions, targeted at the Java ™ Platform and the .NET Framework respectively. Each version comes in two forms: Personal Edition Personal Edition is intended for individuals. It may be freely used by natural persons for their personal activities. (See file license.txt for conditions of use.) Personal Edition comes in binary form, i.e. it does not provide access to the converter API. Both the Java and .NET versions provide command-line executables, and the Java version also offers a graphical user interface. Personal Edition is available for download [ http://www.xmlmind.com/foconverter/download.shtml ] at no charge. Professional Edition Professional Edition is required for corporate or otherwise professional use. In addition to the command-line executables and graphical user interface, it provides access to the converter API, therefore allowing seamless integration of XFC into a Java or .NET application. Features Features XFC preserves the structure of source documents, as well as most of the presentation information. Below is a list of key features of XFC. Paragraph attributes Most paragraph attributes (e.g. indentation) are supported. Vertical spacing is handled reasonably in most cases. Font attributes Most font attributes (family, size, weight, etc) are supported. Lists Both bulleted and numbered lists are supported. XFC tries to infer the numbering style from the label of the first list item. If the numbering style cannot be recognized list items are output as plain paragraphs. Nested lists are supported. Tables XFC supports both the fixed and automatic table layout, as well as the two border models defined in the W3C recommendation. The implementation of the collapsing border model does not strictly conforms to the CSS2 specification, but should give the expected result in most cases. Images Image support is achieved through the use of external converter classes. XFC comes with a simple converter class that supports the GIF, JPEG and PNG formats. Image scaling is supported. Headers and footers static-content elements associated with the before and after regions are converted to page headers and footers respectively. Page references Page references ( page-number-citation elements) are supported. Hypertext links Both internal and external links are supported. For a complete list of supported objects/properties, see the conformance statement [ http://www.xmlmind.com/foconverter/conformance.html ] . In addition, XFC supports an XSL-FO extension to generate structured document tags (SDTs) in an Office Open XML document. This extension makes it possible to produce simple forms that can be loaded and filled in MS-Word 2007. Limitations Though XFC implements the greater part of the W3C recommendation, it does not support all XSL-FO features. Below is a list of the current major limitations of XFC. The leader element is only partly supported. The instream-foreign-object element is not supported. The float and marker elements are not supported. The writing-mode property is not supported (value lr-tb is assumed). The conformance level of XFC may be improved in future versions, however it must be stressed that a full conformance cannot be achieved due to the own limitations of its output formats. Installation System requirements Java ™ version XFC only requires a Java runtime 1.3 or above. All additional libraries ( JAXP [ http://java.sun.com/xml/jaxp ] , SAX2 [ http://www.saxproject.org ] , and XP for JAXP [ http://www.xmlmind.com/xpforjaxp.html ] ) are included in the distribution for convenience. .NET version XFC requires the .NET Framework Redistributable Package (version 1.1 or 2.0) and the Microsoft Visual J# Redistributable Package (same version) to be installed on the host machine. These packages are available for download [ http://msdn.microsoft.com/netframework/downloads/updates/default.aspx ] on the MSDN [ http://msdn.microsoft.com/ ] site. Installation Unix The installation procedure on a Unix system is outlined below. Unpack the distribution: $ gunzip -c xfc-42p1.tgz | tar xvf - The above command will create directory xfc-42p1 in the current directory. Add XFC installation directory (referred to as $XFC_HOME ) to your PATH variable, or create symbolic links to $XFC_HOME/fo2rtf , $XFC_HOME/fo2wml , $XFC_HOME/fo2docx and $XFC_HOME/fo2odt in a directory already in your PATH variable (e.g. /usr/local/bin , assuming you have the required privileges): $ cd /usr/local/bin $ ln -s $XFC_HOME/fo2rtf fo2rtf $ ln -s $XFC_HOME/fo2wml fo2wml $ ln -s $XFC_HOME/fo2docx fo2docx $ ln -s $XFC_HOME/fo2odt fo2odt XFC may then be invoked with one of the following commands: $ fo2rtf <fo-file> <rtf-file> $ fo2wml <fo-file> <wml-file> $ fo2docx <fo-file> <docx-file> $ fo2odt <fo-file> <odt-file> You may try to convert one of the sample files in the samples directory to check the installation. Windows The installation procedure on a Windows platform is outlined below. Unpack the distribution. The Windows distribution comes in the form of a setup program ( setup.exe ). Run this program and follow the instructions to perform the installation. Add XFC installation directory to your PATH variable. XFC may then be invoked with one of the following commands: C:\> fo2rtf <fo-file> <rtf-file> C:\> fo2wml <fo-file> <wml-file> C:\> fo2docx <fo-file> <docx-file> C:\> fo2odt <fo-file> <odt-file> You may try to convert one of the sample files in the samples directory to check the installation. Contents of the distribution Java ™ version docs/apidoc/ Contains the API documentation. docs/docbook-xsl/, docs/slides-xsl Contains Norman Walsh's DocBook and Slides XSL stylesheets documentation. docs/userguide/ Contains this document in HTML and PDF formats. docs/xslutility/ Contains XSL Utility user's guide in HTML format. fo2docx Unix script to convert an XSL-FO file to Open XML. fo2docx.bat Windows script to convert an XSL-FO file to Open XML. fo2odt Unix script to convert an XSL-FO file to OpenDocument. fo2odt.bat Windows script to convert an XSL-FO file to OpenDocument. fo2rtf Unix script to convert an XSL-FO file to RTF. fo2rtf.bat Windows script to convert an XSL-FO file to RTF. fo2wml Unix script to convert an XSL-FO file to WML. fo2wml.bat Windows script to convert an XSL-FO file to WML. java/ Contains the Java source tree (Professional Edition, Developer and Site License only). lib/ Contains the additional Java libraries needed to run XFC, as well as general and copyright information regarding these libraries. license.txt XFC license agreement (Personal Edition). license_dev.txt, license_site.txt, license_srv.txt XFC license agreements (Professional Edition). samples/ Contains XSL-FO sample files. (Most of these files are simple test cases which are part of the XFC test suite.) xfc.jar XFC and XSL Utility binary class library. (Note: the Personal Edition library is obfuscated to prevent access to the converter API.) xslu/config/ Contains the XML catalog, DTDs and XSL stylesheets bundled with XSL Utility. xslu/lib/ Contains the additional Java libraries needed to run XSL Utility, as well as general and copyright information regarding these libraries. xslu/samples/ Contains XML (DocBook) sample files. xslutility Unix script to run XSL Utility (graphical user interface). xslutility.bat Windows script to run XSL Utility (graphical user interface). xslutil Unix script to run XSL Utility (command-line executable). xslutil.bat Windows script to run XSL Utility (command-line executable). .NET version cs/ Contains the C# source code (Professional Edition, Developer and Site License only). docs/apidoc/ Contains the API documentation. docs/userguide/ Contains this document in HTML and PDF formats. fo2docx.exe Command-line executable to convert an XSL-FO file to Open XML. fo2odt.exe Command-line executable to convert an XSL-FO file to OpenDocument. fo2rtf.exe Command-line executable to convert an XSL-FO file to RTF. fo2wml.exe Command-line executable to convert an XSL-FO file to WML. license.txt XFC license agreement (Personal Edition). license_dev.txt, license_site.txt, license_srv.txt XFC license agreements (Professional Edition).