Using Ibex

This chapter describes how to call the Ibex API and how to use the accompanying command line program.

Ibex command line program

Although primarily intended to be used as a part of a larger application, Ibex ships with a command line program which can be used to create PDF files from FO files. Installation of this command line program is described here.

To create a PDF file from an FO file specify the file names on the command line. For instance to create hello.pdf from hello.fo, you do this:

> ibex hello.fo hello.pdf

XSLT translation

The command line program will accept XML data and an XSLT stylesheet as inputs. The XML will be translated to FO by the stylesheet and the results then formatted to PDF. The command line syntax is:

> ibex -xsl xsl-file xml-file pdf-file

So to create a PDF file from the files book.xml and book.xsl, the command is:

> ibex -xsl book.xsl book.xml book.pdf

XSLT parameters can be passed to the stylesheet by adding them as name-value pairs to the command line. For instance, if we want to define the parameter called "age" to the value "30" we use a command like this:

> ibex -xsl book.xsl book.xml hello.pdf "age=30"

The use of the double quotes around the name-value pair is necessary on some operating systems to force them to come through as a single parameter to the Ibex program.

Logging from the command line

Any informational or error messages will be logged to the console. To send error messages to a file as well, use the -logfile option. For example to log errors to the file ibex.log, you would do this:

> ibex -logfile ibex.log hello.fo hello.pdf

Listing available fonts

You can also list the fonts which are available (based on what fonts are installed on your system) by using the -fonts option like this:

> ibex -fonts

The list of fonts is produced as a FO file to the standard output. This can be redirected to a file and then used as input to Ibex to create a PDF file containing a table which looks like this:

The list of fonts can be limited to fonts whose name contains a specified string by passing the string on the command line. For instance if we wanted to see what versions of "arial" are installed, we can use the command:

> ibex -fonts arial

The Ibex API

A PDF document is generated using the FODocument object which is in the ibex4 namespace.

First you create a new FODocument object and then calling the generate() method on that object. The generate() method has various versions which take different parameters depending on whether the input is from files or streams and whether XSLT translation should occur.

The FODocument object is not thread safe. A new FODcoument should be created for each PDF file to be created. Ibex does support creating multiple PDF files concurrently on multiple threads, as long as each PDF file is associated with a unique FODocument instance. Example C# code to convert the file "manual.fo" to "manual.pdf" the code is shown in Figure 5-1.

using System;
using ibex4;
public class Simple {
	static void Main( string[] args ) {
		FODocument doc = new FODocument();
		gen.generate( "manual.fo", "manual.pdf" );
	}
}

Figure 5-1: C# code to create a PDF from an FO file

Generating to File

public void generate( string fo_file_name, string pdf_file_name )

This will read the FO contained in the file named in pdf_file_name and create the PDF file named in pdf_file_name.

Generating using streams

public void generate( Stream fo_stream, Stream pdf_stream )

public void generate( Stream fo_stream, Stream pdf_stream, bool close_stream )

This will read the FO from the System.IO.Stream called fo_stream and create the PDF file into the System.IO.Stream pdf_stream. These streams can be anything derived from System.IO.Stream, such as System.IO.FileStream or System.IO.MemoryStream.

If close_stream is true the PDF stream will be closed after the PDF file is generated, if false it will not. By default the stream is closed. Not closing the stream is useful if you are generating to a MemoryStream object as the bytes cannot be read from the MemoryStream if it has been closed.

Generating a PDF from XML and XSL

These methods take XML, an XSLT stylesheet, and a stream to write the resulting PDF file to.

public void generate( Stream xml_stream, Stream xsl_stream, Stream pdf_stream )

public void generate( Stream xml_stream, Stream xsl_stream, Stream pdf_stream, bool closeStream )

Ibex uses the .NET XSLT processor to transform the XML using the specified stylesheet and passes the resulting FO to the PDF creation routines. XSLT transformation is faster or more efficient in .NET 2.0 and later and we recommend using this version or later if possible.

Generate a PDF from XML and XSL with parameters

These methods are similar to the ones in the previous section but take an additional hashtable which (if not null) should contain name-value pairs which are then passed as arguments to the XSLT translation process.

public void generate( Stream xml_stream, Stream xsl_stream, Stream pdf_stream,
bool close_stream, Hashtable params )