Getting Started with Ibex
Although primarily intended for use as a part of a larger application, the Ibex installation includes command line programs which creates PDF files from XML, XSLT and XSL-FO files. We will use this program to demonstrate the basics of PDF creation with Ibex. The command line tool installed from the Ibex.CommandLine package as described above. Throughout this manual an XML file which uses the XSL formatting objects vocabulary is referred to as an FO file or just the FO.
Ibex command line program usage
To create a PDF file from a FO file specify the names of the FO and PDF files on the command line. For example to create hello.pdf from hello.fo you do this:
ibex hello.fo hello.pdf
If the names of the input and output files are the same (ignoring the extensions) you can abbreviate this to:
ibex hello.fo
and if the file extension of the input file is "fo" or "xml" you can abbreviate even further to:
ibex hello
Error logging
Any informational or error messages will be logged to the console. To send any error messages to a file as well, use the -logfile option. For example, to log errors to the file ibex.log the command becomes:
ibex -logfile ibex.log hello.fo hello.pdf
An example without XSLT translation
The Ibex command line program will create a PDF file from either (a) an FO file or (b) an XML file with an XSLT stylesheet. This section shows how to create a PDF file from an FO file. This example uses the FO file hello.fo shown in Figure 3-1.
<?xml version="1.0" encoding="UTF-8"?>
<root xmlns="http://www.w3.org/1999/XSL/Format">
<layout-master-set>
<simple-page-master master-name="page">
<region-body margin="2.5cm" region-name="body"/>
</simple-page-master>
</layout-master-set>
<page-sequence master-reference="page">
<flow flow-name="body">
<block>Hello World</block>
</flow>
</page-sequence>
</root>
Figure 3-1: Hello World FO
Each of the elements and attributes used in the file is explained later in the manual. For now we just want to get started with using the Ibex command line program. Using the command
ibex hello
creates the file hello.pdf containing the text "Hello World".
An example with XSLT translation
The Ibex command line program will create a PDF file from either (a) an FO file or (b) an XML file with an XSLT stylesheet. This section shows how to create a PDF file from an XML data file with an XSLT stylesheet.
Using Ibex without having Ibex do the XSLT transformation to create the FO is useful if you have created the FO using another tool or if you just want to manually change some FO to experiment with layout.
In practice XSLT is almost always part of the PDF creation process because XSL-FO lacks some simple features such
as being able to sequentially number headings. The designers of XSL-FO presumed that XSLT would be used and so did not duplicate features already in XSLT.
Ibex gives you the flexibility of having Ibex do the XSLT translation or having some other tool do it.
Internally Ibex uses the XSLT translation classes provided by
.Net. The XSLT classes in .Net 6 are significantly faster and use memory more
efficiently than in early versions. For this reason we recommend using the latest available versions of .Net.
In this example we will translate some XML with an XSLT stylesheet and produce a PDF from the result of the translation. We have some weather forecast data in the file weather.xml. This file contains the XML shown in Figure 3-2.
<?xml version="1.0" encoding="UTF-8"?>
<forecast>
<city name="Wellington" temp="20"/>
</forecast>
Figure 3-2: Weather Forecast Data
We also have an XSLT stylesheet weather.xsl which contains the XSL shown in Figure 3-3.
<?xml version="1.0" encoding="utf-8"?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:fo="http://www.w3.org/1999/XSL/Format">
<xsl:strip-space elements="*"/>
<xsl:template match="forecast">
<root xmlns="http://www.w3.org/1999/XSL/Format">
<layout-master-set>
<simple-page-master master-name="page-layout">
<region-body margin="2.5cm" region-name="body"/>
</simple-page-master>
</layout-master-set>
<page-sequence master-reference="page-layout">
<flow flow-name="body">
<xsl:apply-templates select="city"/>
</flow>
</page-sequence>
</root>
</xsl:template>
<xsl:template match="city">
<fo:block>
<xsl:value-of select="@name"/>
<xsl:value-of select="@temp"/>
</fo:block>
</xsl:template>
</xsl:stylesheet>
Figure 3-3: Weather Forecast Stylesheet
This template outputs the fo:root, fo:layout-master-set and fo:page-sequence elements. Then for each city record in the data outputs a fo:block element using the template shown in Figure 3-4.
<xsl:template match="city">
<block>
<xsl:value-of select="@name"/>
 
<xsl:value-of select="@temp"/>
</block>
</xsl:template>
Figure 3-4: weather-data-xsl-subset
We can translate and format this example using the command:
ibex -xsl weather.xsl weather.xml weather.pdf
The result of this translation is the file weather.pdf
Required skills
To use Ibex you need know how to edit XSL stylesheets. Some familiarity with XSLT is required, although in depth knowledge is not. The Ibex website contains examples of using XSLT for common document related functions such as creating a table of contents.
Familiarity with XSL-FO is not required. This manual contains enough information to enable you to produce complex documents using Ibex.