Skip to main content

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"/>
&#160;
<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.