Tutorial introduction and preparation
The XSL Formatting Objects specification, an official recommendation of the W3C that is commonly known as XSL-FO, defines a number of XML tags that describe how something should be rendered. Although XSL-FO contains elements that describe how to render text in nonprint formats such as spoken text, this tutorial introduces how to create portable document format (PDF) files -- the most common use of XSL-FO.
The tutorial provides a brief overview of the XSL-FO document structure, as well as the elements that define page sizes, fonts, and margins. It also explains the basics of text and graphic formatting and demonstrates the fundamentals of converting a formatting object file to PDF. Downloadable code samples make it easy to adapt samples to experiment on your own.
When you've completed this introductory tutorial, you'll understand what XSL-FO is and how it works. You'll be able to adapt the basic samples provided to create simple FO documents of your own. You'll be ready move on to the second tutorial in this series to find out how to control text formatting in detail and how to convert HTML elements to formatting objects. Then you will be able to create your own XML applications that use formatting objects to generate high-quality printable documents.
This tutorial assumes that you already comprehend the Extensible Markup Language (XML) and how to work with it and its related technologies, such as XML Stylesheet Language-Transformation (XSLT). You don't need to know anything about XSL-FO yet, but to work with formatting objects, you need a little experience working with XSLT.
The tools used for the examples are written in the Java code, but you don't have to understand the Java language to use them.
Figure 1. FOP project logo
Although you can use other XSL-FO rendering engines, this tutorial is written for the Apache XML Project's FOP (Formatting Objects to PDF) translator. The examples in this tutorial work with FOP Version 0.20.4, which was released on July 5, 2002. If you try them with other versions of FOP, they may or may not work. The XSL-FO spec became an official recommendation of the W3C on 15 October 2001; the FOP tool supports most of the final spec.
We use the FOP tool at developerWorks for two reasons:
- It's written in the Java language, and so it runs on all the platforms that we care about.
- It's a no-cost, open-source product, and so anyone can afford it.
If you want to immerse yourself in XSL-FO, you can go directly to the source for the the spec at the W3C's site (see Resources). Be aware that this is one of the longest documents at the W3C (roughly 400 pages), although most of it is reference information for the many elements and attributes in the XSL-FO tag set. The reference sections -- particularly appendixes B, C, and D -- are very useful for looking up property names and values. Remember, as of this writing, FOP does not completely support the XSL-FO spec. Certain property names and values defined by the spec might not be supported by the tool, or they might be supported with slightly different names and values.
To go through the exercises in this tutorial, you'll need to have a Java Developer's Kit (JDK) Version 1.3 or later, as well as the FOP package from the Apache XML Project. You can get the FOP package. Download the latest version and unzip it.
Once you have the JDK and FOP installed, you need to set the classpath.
If you want to follow the examples in the tutorial without remembering to adapt them, put the FOP package at
c:\fop-0.20.4rc and then set the classpath like this (except all on one line, of course; I've broken the line only to fit within the text column here):
set classpath=.;c:\fop-0.20.4rc\build\fop.jar;c:\fop-0.20.4rc\ lib\avalon-framework-cvs-20020315.jar;c:\fop-0.20.4rc\lib\bati k.jar;c:\fop-0.20.4rc\lib\xalan-2.3.1.jar;c:\fop-0.20.4rc\lib\ xercesImpl-2.0.1.jar;c:\fop-0.20.4rc\lib\xml-apis.jar;
If you unzip the FOP package somewhere else, you'll need to change the command accordingly. If you're running Linux, use the command
export classpath=/usr/bin/fop-0.20.4rc/build/fop.jar:/usr/bin/fop-... and so on.