Introduction

This manual describes the functionality and use of the Ibex PDF Creator. Ibex is a PDF creation component which can be used from the command line or, more usually, integrated into a larger application. It ships as a .Net assembly so it can be used both in stand-alone applications and in server-based applications using ASP and ASP.Net.

This chapter provides an overview of how Ibex works and the process involved in creating PDF files using Ibex.

The PDF creation process

Ibex creates PDF files which contain data from your application. You provide Ibex with your data in XML format and Ibex creates a PDF file containing that data. The format of the PDF file is specified using an XSL stylesheet which defines the layout of the document using the elements from the XSL Formatting Objects standard.

The XML you provide to Ibex can come from any source. Typically, it is extracted from a database or generated dynamically for each document.

The formatting objects (FO) standard defines elements such as table, row and cell which can be used to lay out your data on a page. It also defines objects for describing the overall shape and layout of the page, including parameters such as page size, number of columns and regions such as headers and footers where content will be placed on the page.

The process of creating a document in FO format is carried out using an XSLT stylesheet. The stylesheet transforms your XML data into standard FO syntax. Ibex then reads that XSL-FO and creates the PDF file. The actual execution of the XSLT translation can be done either by Ibex, which uses the .Net XSL translation objects, or externally to Ibex using any XSLT engine. This enables you to use the XSTL translator of your choice.

Figure 1-1 shows some XML data for creating a page which says "Hello world". The corresponding formatting objects from which the PDF is created are shown in Figure 1-2.

<?xml version="1.0" encoding="UTF-8"?>
<expression>hello world<expression>

Figure 1-1: Simple XML

<?xml version="1.0" encoding="utf-8"?>
<fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format">
  <fo:layout-master-set>
    <fo:simple-page-master master-name="layout" page-width="8.5in" page-height="8in">
      <fo:region-body region-name="body" margin="2.5cm"/>
    </fo:simple-page-master>
  </fo:layout-master-set>
  <fo:page-sequence master-reference="layout">
    <fo:flow flow-name="body">
      <fo:block>Hello world</fo:block>
    </fo:flow>
  </fo:page-sequence>
</fo:root>

Figure 1-2: Example formatting objects for hello world

The process of getting from your data to the formatting objects is carried out using the XSLT stylesheet which you provide.

This approach to PDF creation has a significant advantages:

  • the content and presentation are separated. The format of the PDF file is defined by the XSLT stylesheet which can be created and maintained externally to the application. Changing the stylesheet to alter the report layout does not require rebuilding your application;

  • formatting elements such as report headers and footers can be maintained in a separate stylesheet which is included at runtime into many different reports;

  • the formatting objects standard defines a powerful set of objects for creating page content. It supports single-column and multi-column pages, bookmarks, indexing, page headers and footers, complex page numbering, tables with optionally repeating headers and footers and many other features;

  • formatting objects is a high-level approach which makes changing report layouts simple. For example to change the number of columns on a multi-column page you just need to change the column-count attribute on a single element. To do this using a lower level programmatic API is much more complex.

Terminology

Ibex uses the FO standard which defines formatting objects such as table and table-cell. FO makes a distinction between two types of objects:

  • block-level objects

    broadly speaking these are objects which are formatted vertically down the page. Block level objects are fo:block, fo:block-container, fo:table, fo:table-and-caption, and fo:list-block.

  • inline-level objects

    these are objects whose content is placed on lines within an fo:block object. Commonly used inline level objects are fo:external-graphic, fo:inline, fo:leader, fo:page-number, fo:page-number-citation and fo:basic-link.

About this manual

This manual is split into two main sections. The first covers an introduction to the use of formatting objects and an overview of various formatting objects such as tables and lists. The second is a reference section listing all the available objects and attributes with many examples of their usage.

About Ibex

Ibex is developed entirely in C# and requires the Microsoft dotnet runtime to be installed. Ibex is developed using .Net 6 and Visual Studio 2022. Ibex runs on Windows and Linux.

Installation

Ibex is installed as from nuget.org as two separate components.

Ibex.PDF.Creator

The Ibex.PDF.Creator package contains the library which you will link to your own application. This can be downloaded either using the "Manage Nuget Packages" menu option from within Visual Studio or using the "dotnet add package" command on the command line.

Ibex.CommandLine

The Ibex.CommandLine package is a console application to create PDF files from the command line, for use during testing and development. The Ibex.CommandLine package is a .Net tool. This is installed from a command shell like so:.

> dotnet tool install -g Ibex.CommandLine

An existing installation can be updated using this command:

> dotnet tool update -g Ibex.CommandLine

It can be uninstalled using this command:

> dotnet tool uninstall --global Ibex.CommandLine

The Ibex.CommandLine tool, when it is installed as a dotnet global tool, is accessed using the command "ibex". So for example if we had a file called 'test.fo' this command would created a PDF file from it:

> ibex test.fo

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" 
   xmlns:ibex="http://www.xmlpdf.com/2003/ibex/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 root, layout-master-set and page-sequence elements. Then for each city record in the data outputs a 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.

Introduction to XSL-FO

This chapter provides an overview of formatting objects and provides some suggestions on how to create PDF documents from XML files. We also look at the techniques for using XSLT transformation to create FO files.

Layout of an FO file

A very simple FO file is shown in Figure 4-1:

<?xml version='1.0' encoding='UTF-8'?>
<fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format">
   <fo:layout-master-set>
      <fo:simple-page-master master-name="simple">
         <fo:region-body margin="2.5cm" region-name="body" background-color='#eeeeee'/>
      </fo:simple-page-master>
   </fo:layout-master-set>
   <fo:page-sequence master-reference="simple">
      <fo:flow flow-name="body">
         <fo:block>Hello World</fo:block>
      </fo:flow>
   </fo:page-sequence>
</fo:root>

Figure 4-1: Simple FO file

This file is logically in three parts, namely the root, layout-master-set and page-sequence parts. All FO files share this structure.

The fo:root element

The fo:root element shown in Figure 4-2 contains the whole content of the file and establishes the XSL-FO namespace as the default namespace. This element is the same for all FO files.

<fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format">

Figure 4-2: The root element

Additional namespaces can be added to the fo:root element as shown in Figure 4-3.

<fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format"
            xmlns:ibex="http://www.xmlpdf.com/2003/ibex/Format"
            xmlns:svg="xmlns="http://www.w3.org/2000/svg"
>

Figure 4-3: The root element with additional namespaces

If you want to use SVG diagrams or Ibex extensions you should define the namespaces as shown.

The layout-master-set element

The fo:layout-master-set element show in Figure 4-4 defines the shape and layout of pages in the document. Within the fo:layout-master-set we have a fo:simple-page-master element which in turn contains the fo:region-body element.

The fo:simple-page-master defines the layout of one type of page and is uniquely identified by its master-name attribute. The fo:region-body element defines an area of the page where content will be placed. A page can have more than one region so we give the region a unique name "body" using the region-name attribute. This value is used with fo:flow elements to specify which content goes into which region on the page.

 <fo:layout-master-set>
    <fo:simple-page-master master-name="simple">
       <fo:region-body margin="2.5cm" region-name="body" background-color="#eeeeee"/>
    </fo:simple-page-master>
 </fo:layout-master-set>

Figure 4-4: The master-layout element

A FO file contains one or more fo:simple-page-master elements, each with a unique master-name. In this simple example we have only one. Each fo:simple-page-master element creates a formatting object known as a page master.

The page-sequence element

The fo:page-sequence element shown in Figure 4-5 defines a sequence of pages that will appear in the PDF document. The master-reference attribute is used to tie the content of the fo:page-sequence to a particular page layout, in this case one defined previously using a fo:simple-page-master. When Ibex finds a fo:page-sequence element it looks at the list of known fo:simple-page-master and fo:page-sequence-master elements (we have no fo:page-sequence-master elements in this example) and finds one with a master-name attribute which equals the master-reference attribute on the fo:page-sequence. If Ibex does not find a matching page master the FO file is invalid and Ibex will throw an exception.

<fo:page-sequence master-reference="simple">
  <fo:flow flow-name="body">
     <fo:block>Hello World</fo:block>
  </fo:flow>
</fo:page-sequence>

Figure 4-5: The page-sequence element

Within the fo:page-sequence element we have a fo:flow element. This holds the content which will appear on one or more pages. A page can have multiple regions. To associate content with a region we use the flow-name attribute on the fo:flow element. In order for the content contained in the fo:flow to appear on the page, the flow-name of the fo:flow should match a region-name of one of the regions (in this example the fo:region-body) on the page.

If the flow-name of the fo:flow does not match a region-name of one of the regions on the page the content is not displayed on that page. This is not an error. It is a useful feature and we show how to use it later in this chapter.

Looking at the FO in Figure 4-6, the underlined names must match each other, and the names in italics should match if you want the content to appear.

<fo:layout-master-set>
  <fo:simple-page-master master-name="simple">
     <fo:region-body margin="2.5cm" region-name="body" background-color='#eeeeee'/>
  </fo:simple-page-master>
</fo:layout-master-set>
<fo:page-sequence master-reference="simple">
  <fo:flow flow-name="body">
      <fo:block>Hello World</fo:block>
  </fo:flow>
</fo:page-sequence>

Figure 4-6: Matching master-name and master-reference

Within the fo:flow element we can have one or more "block level" elements. These are elements such as fo:list, fo:block and fo:table which define the content to appear on the page. In this example we have a single fo:block element containing the text "Hello World".

This produces a page like the one shown in Figure 4-7. The region created by the fo:region-body element has a shaded background so you can see how large it is.

image not found:tutorial1.jpg

Figure 4-7: A basic page with a region-body and some text

Adding a page footer region

In our example so far all the text contained in the fo:flow element goes into the body region in the center of the page. To add a page footer we need to define a new region on the page and then define some new content to go into that region.

We define a footer region by adding a fo:region-after element into the existing fo:simple-page-master as shown in Figure 4-8.

<fo:layout-master-set>
   <fo:simple-page-master master-name="simple">
     ...
      <fo:region-after extent='1cm' region-name="footer" background-color='#dddddd'/>
     ...
   </fo:simple-page-master>
</fo:layout-master-set>

Figure 4-8: Simple page master with footer region

The fo:region-after element defines an area on the page which extends the full width of the page. If we had side regions (fo:region-start and fo:region-end) this might change, but in this example we have no side regions.

The height of the region created by the fo:region-after element is defined by the extent attribute. In this example we have extent="1cm", so the region will be 1cm high and end at the bottom of the page.

Even without any content the footer region is still rendered on the page. Our page now looks like the one in Figure 4-9.

image not found:tutorial2.jpg

Figure 4-9: A basic page with a footer region

In its current position on the page the footer region will not print on most printers because they do not print right to the edge of the paper. We can define a margin around the whole page by setting the margin attribute on the fo:simple-page-master element of the fo:page-sequence as shown in Figure 4-10.

<fo:layout-master-set>
  <fo:simple-page-master master-name="simple" margin="2.5cm">
     <fo:region-body margin="2.5cm" region-name="body" background-color="#eeeeee"/>
     <fo:region-after extent="1cm" region-name="footer" background-color="#dddddd"/>
  </fo:simple-page-master>
</fo:layout-master-set>

Figure 4-10: Simple page master with margin added

The area inside the margins of the fo:simple-page-master is called the "content area". The area covered by the regions (defined by the fo:region-body and fo:region-end) is measured from the inside of the page's content area, so when we add margins to the fo:simple-page-master we reduce the size of the regions correspondingly.

Our page now appears as shown in Figure 4-11.

image not found:tutorial3.jpg

Figure 4-11: After adding margins to the simple-page-master

Now that we have some space on the sides of the body region we can remove the side margins from the body by changing the definition from that shown in Figure 4-12 to the one shown in Figure 4-13, resulting in the page layout shown in Figure 4-14.

<fo:region-body margin="2.5cm" region-name="body" background-color="#eeeeee"/>

Figure 4-12: Body with side margins

<fo:region-body margin-top="2.5cm" margin-bottom="2.5cm" region-name="body"  background-color="#eeeeee"/>

Figure 4-13: Body without side margins

image not found:tutorial4.jpg

Figure 4-14: After removing the left and right margins from the region-body

The last thing we need to do to get a working page layout is to make the footer region narrower by adding side regions. The left side region is created with a region-start element and the right side with a region-end element as in Figure 4-15. We can also specify the bottom-margin attribute of the body region so that it ends just where the footer starts, by setting margin-bottom= "1cm" on the fo:region-body element.

<fo:layout-master-set>
  <fo:simple-page-master master-name="simple" margin='2.5cm'>
     <fo:region-body margin="2.5cm" margin-bottom='1cm' region-name="body" background-color='#eeeeee'/>
     <fo:region-after extent='1cm' region-name="footer" background-color='#dddddd'/>
     <fo:region-start extent='2.5cm'/>
     <fo:region-end extent='2.5cm'/>
  </fo:simple-page-master>
</fo:layout-master-set>

Figure 4-15: side regions

By default the side regions take precedence over the top and bottom regions so the top and bottom regions become narrower. This gives us the page layout shown in Figure 4-16, to which we can start adding some content.

image not found:tutorial5.jpg

Figure 4-16: With side regions to reduce the width of the footer

Attribute processing

The FO above also illustrates one of the ways in which XSL-FO handles attributes. We can specify a shorthand attribute such as "margin", which has the effect of setting the specific values margin-left, margin-right, margin-top and margin-bottom, and then override just the specific value we want (for example by setting margin-bottom="1cm"). The order in which the attributes are specified in the FO file has no effect. A more specific setting will always override a more general one. So the two examples in Figure 4-17 and Figure 4-18 produce the same result.

<fo:layout-master-set>
  <fo:simple-page-master master-name="simple">
     <fo:region-body margin="2.5cm" margin-bottom="1cm">
  </fo:simple-page-master>
</fo:layout-master-set>

Figure 4-17: Shorthand and specific attributes

<fo:layout-master-set>
  <fo:simple-page-master master-name="simple">
     <fo:region-body margin-bottom="1cm" margin="2.5cm">
  <fo:/simple-page-master>
<fo:/layout-master-set>

Figure 4-18: Shorthand and specific attributes

Adding content to the footer

While content is added to the body of the page using the flow element, content is added to other regions using the fo:static-content element. The "static" part of the fo:static-content name refers to the fact that the content defined in this element stays within the region specified on this page. It does not flow from one page to the next. If the content exceeds the size of the region it will not flow to the next page.

The content of the fo:static-content is repeated on every page which has a region with a matching flow-name (such as "footer"), and is typically different on every page as the page number changes.

To insert a simple footer with the words "XSL-FO Example" we add a fo:static-content element as shown in Figure 4-19.

<?xml version='1.0' encoding='UTF-8'?>
<fo:root xmlns="http://www.w3.org/1999/XSL/Format">
   <fo:layout-master-set>
      <fo:simple-page-master master-name="simple" 
           margin='2.5cm'>
         <fo:region-body margin="2.5cm" margin-bottom='1cm' region-name="body"  background-color='#eeeeee'/>
         <fo:region-after extent='1cm' region-name="footer" background-color='#dddddd'/>
         <fo:region-start extent='2.5cm'/>
         <fo:region-end extent='2.5cm'/>
      </fo:simple-page-master>
   </fo:layout-master-set>
   <fo:page-sequence master-reference="simple">
      <fo:static-content flow-name="footer">
          <fo:block text-align='center'>XSL-FO Example</fo:block>
      </fo:static-content>
      <fo:flow flow-name="body">
         <fo:block>Hello World</fo:block>
      </flow>
   </fo:page-sequence>
</fo:root>

Figure 4-19: Adding a static-content element

Note that the order of the fo:static-content and fo:flow elements is important. All fo:static-content elements must come before any fo:flow elements.

This FO produces the page shown in Figure 4-20.

image not found:tutorial6.jpg

Figure 4-20: FO with static-content

Note that the flow-name of the fo:static-content element and the region-name of the fo:region-after element must match for the content to appear. This feature makes it possible to have many fo:static-content elements within the same fo:page-sequence, and only those which match regions in the current fo:simple-page-master will be rendered.

Adding the page number to the footer

To insert the current page number into the document use the fo:page-number element inside the fo:static-content element as shown in Figure 4-21.

<?xml version='1.0' encoding='UTF-8'?>
<fo:root xmlns="http://www.w3.org/1999/XSL/Format">
   <fo:layout-master-set>
      <fo:simple-page-master master-name="simple" margin='2.5cm'>
         <fo:region-body margin="2.5cm" margin-bottom='1cm' region-name="body"  background-color='#eeeeee'/>
         <fo:region-after extent='1cm' region-name="footer" background-color='#dddddd'/>
         <fo:region-start extent='2.5cm'/>
         <fo:region-end extent='2.5cm'/>
      </fo:simple-page-master>
   </fo:layout-master-set>
   <fo:page-sequence master-reference="simple">
      <fo:static-content flow-name="footer">
          <fo:block text-align='center'>
          XSL-FO Example, page <fo:page-number/>
          </fo:block>
      </fo:static-content>
      <fo:flow flow-name="body">
         <fo:block>Hello World</fo:block>
      </flow>
   </fo:page-sequence>
</fo:root>

Figure 4-21: Adding a page number

This FO produces the page shown in Figure 4-22.

image not found:tutorial7.jpg

Figure 4-22: Page with page number

Adding the total page count to the footer

Adding the total page count (so we can have "page 3 of 5") is a two step process, based on the use of the "id" attribute which uniquely identifies an FO element. We place a block on the last page with the id of "last-page", and then we use the page-number-citation element to get the number of the page on which that block appears as our total number of pages.

Typically the block with the id of "last-page" is empty so a new page is not created at the end of the document.

The FO for the last block in the document is shown in Figure 4-23, and the FO to retrieve the last page number and put it in the footer is shown in Figure 4-24.

<fo:block id="last-page"/>

Figure 4-23: Block with id for last page

<fo:page-number-citation ref-id="last-page"/>

Figure 4-24: FO to retrieve the page number of the identified block

You can see how the id and ref-id values match. This is how Ibex associates the two elements and knows from which block to retrieve the page number.

So bringing all these elements together we have the FO shown in Figure 4-25.

<?xml version='1.0' encoding='UTF-8'?>
<fo:root xmlns="http://www.w3.org/1999/XSL/Format">
   <fo:layout-master-set>
      <fo:simple-page-master master-name="simple" 
            margin='2.5cm'>
         <fo:region-body margin="2.5cm" margin-bottom='1cm' region-name="body"  background-color='#eeeeee'/>
         <fo:region-after extent='1cm' region-name="footer"background-color='#dddddd'/>
         <fo:region-start extent='2.5cm'/>
         <fo:region-end extent='2.5cm'/>
      </fo:simple-page-master>
   </fo:layout-master-set>
   <fo:page-sequence master-reference="simple">
      <fo:static-content flow-name="footer">
          <fo:block text-align='center'>
          XSL-FO Example, page <fo:page-number/>
          of <fo:page-number-citation ref-id='last-page'/>
          </fo:block>
      </fo:static-content>
      <fo:flow flow-name="body">
         <fo:block>Hello World</fo:block>
         <fo:block id='last-page'/>
      </flow>
   </fo:page-sequence>
</fo:root>

Figure 4-25: Complete FO to display total page count

This FO produces the page shown in Figure 4-26.

image not found:tutorial8.jpg

Figure 4-26: Page with page number and total page count

Adding text content

Text is added to the body region of the page by using the block element. A block element can contain any amount of text and has attributes which define how the text will appear. These attributes are described in more detail later in the manual.

A block can contain text as shown in Figure 4-27.

<fo:flow flow-name="body">
   <fo:block>Hello World</fo:block>
</flow>

Figure 4-27: Text in a block

A block element can also contain other block elements which in turn contain text or more nested elements. Figure 4-28 shows a block which contains another block with a different font, set using the font attribute.

<fo:flow flow-name="body">
     <fo:block>
          Hello World
          <fo:block font-size="16pt">
             this is a nested block
          </fo:block>
     </fo:block>
</flow>

Figure 4-28: Nested blocks

There is no limit to the nesting of block elements.

Using borders and padding

Many FO elements can have a border around the area they create on the page. If the border around an element is the same on all four sides then it can be defined with a single use of the border attribute. The space between a border and the content of the block (in this case the text) is controlled using the padding attribute. Figure 4-29 shows FO for a block with border and padding.

<fo:flow flow-name="body">
  <fo:block background-color='#eeeeee'>
    <fo:block>
         Hello World
    </fo:block>
    <fo:block border='1pt solid red' padding='3pt'>
         Hello World
    </fo:block>
  </fo:block>
</flow>

Figure 4-29: Block with border and padding

This example has two block elements nested inside an outer element, with a background color set on the outer element to highlight the area created by the outer block. The block created from this FO is shown in .

Hello World Hello World

Ibex positions the content of the block (in this case the text) relative to the edge of the region. After positioning the content, the padding and borders are positioned relative to the position of the content. This places the padding and borders outside the content area of the block. The contents of the block are not indented, rather the padding and borders extend outside the block. This is the default behavior of XSL-FO formatters.

If you prefer Cascading Style Sheets (CSS) compatible behavior where adding a border to a block indents its content, you can specify the left-margin and right-margin attributes to force this to happen. Even if the left-margin and right-margin values are zero, CSS type indentation will still occur. The XML for this is shown in Figure 4-30 and the resulting output is shown in .

<fo:flow flow-name="body">
  <fo:block background-color='#eeeeee'>
    <fo:block>
      Hello World
    </fo:block>
    <fo:block border='1pt solid red' padding='3pt' margin-left="0" margin-right="0">
      Hello World
    </fo:block>
  </fo:block>
</flow>

Figure 4-30: Block with margins specified

Hello World Hello World

Creating lists

A list is content divided into two columns. Each item in the list is in two parts, called the label and the body respectively. A list is created with the fo:list-block element. A fo:list-block contains one or more fo:list-item elements, each of which contains exactly one fo:list-item-label element and exactly one fo:list-item-body element.

<fo:list-block 
   margin-left='3cm' margin-right='3cm' padding='3pt' 
   border='.1pt solid blue' 
   provisional-distance-between-starts='0.5cm' 
   provisional-label-separation='0.1cm'>
   <fo:list-item>
       <fo:list-item-label end-indent='label-end()'>
           <fo:block>&#x2022;</fo:block>
       </fo:list-item-label>
       <fo:list-item-body start-indent='body-start()'>
           <fo:block>this is item one</fo:block>
       </fo:list-item-body>
   </fo:list-item>

   <fo:list-item>
       <fo:list-item-label end-indent='label-end()'>
          <fo:block>&#x2022;</fo:block>
       </fo:list-item-label>
       <fo:list-item-body start-indent='body-start()'>
          <fo:block>this is item two</fo:block>
       </fo:list-item-body>
   </fo:list-item>
</fo:list-block>

Figure 4-31: FO for the list-block

A list sets the two columns to widths specified using the attributes of the list-block elements. The provisional-distance-between-starts attribute specifies the distance between the start of the label column and the start of the body column. The provisional-label-separation attribute sets how much of the label column should be left empty to provide a blank space between the columns.

For more information on lists see page lists.

Creating tables

A table is created using the fo:table element. Within the fo:table element there can be one fo:table-header element, any number of fo:table-body elements (which contain the rows) and one fo:table-footer element. Each of the fo:table-header, fo:table-body and fo:table-footer elements contains one or more fo:table-row elements, each containing one or more fo:table-cell elements which in turn contain block-level elements such as fo:block, fo:table and fo:list-block.

Since a fo:table-cell can contain any block-level element you can easily create tables which contain text, nested tables or lists. Table headers and footers defined with the fo:table-header and fo:table-footer elements are automatically repeated at each page break, although this can be suppressed if required.

Figure 4-32 shows the FO for a simple table and shows the table created from the FO.

<fo:table>
  <fo:table-body>
    <fo:table-row>
       <fo:table-cell border='1pt solid blue' padding='2pt'>
          <fo:block>row 1 column 1</fo:block>
       </fo:table-cell>
       <fo:table-cell border='1pt solid blue' padding='2pt'>
          <fo:block>row 1 column 2</fo:block>
       </fo:table-cell>
    </fo:table-row>
       <fo:table-cell border='1pt solid blue' padding='2pt'>
          <fo:block>row 1 column 1</fo:block>
       </fo:table-cell>
       <fo:table-cell border='1pt solid blue' padding='2pt'>
          <fo:block>row 1 column 2</fo:block>
       </fo:table-cell>
    </fo:table-row>
  </fo:table-body>
</fo:table>

Figure 4-32: FO for a table

The padding and border attributes are not inherited from containing elements so must be defined on the fo:table-cell elements.

Setting table column widths

The width of a table column is set using the fo:table-column element. A fo:table element contains zero or more fo:table-column elements each of which defines properties such as width and background-color for a column in the table.

To make the first column 30% of the table width we would add fo:table-column elements as shown in Figure 4-33, which creates the output shown in .

<fo:table>
  
    <fo:table-column column-width='30%' column-number='1'/>
    <fo:table-column column-width='70%' column-number='2'/>
  
  <fo:table-body>
    <fo:table-row>
       <fo:table-cell border='1pt solid blue' padding='2pt'>
          <fo:block>row 1 column 1</fo:block>
       </fo:table-cell>
       <fo:table-cell border='1pt solid blue' padding='2pt'>
          <fo:block>row 1 column 2</fo:block>
       </fo:table-cell>
    </fo:table-row>
    <fo:table-row>
       <fo:table-cell border='1pt solid blue' padding='2pt'>
          <fo:block>row 1 column 1</fo:block>
       </fo:table-cell>
       <fo:table-cell border='1pt solid blue' padding='2pt'>
          <fo:block>row 1 column 2</fo:block>
       </fo:table-cell>
    </fo:table-row>
  </fo:table-body>
</fo:table>

Figure 4-33: Table with table-column elements

For more information on tables see page tables.

Installation

Ibex is installed as from nuget.org as two separate components.

Ibex.PDF.Creator

The Ibex.PDF.Creator package contains the library which you will link to your own application. This can be downloaded either using the "Manage Nuget Packages" menu option from within Visual Studio or using the "dotnet add package" command on the command line.

Ibex.CommandLine

The Ibex.CommandLine package is a console application to create PDF files from the command line, for use during testing and development. The Ibex.CommandLine package is a .Net tool. This is installed from a command shell like so:.

> dotnet tool install -g Ibex.CommandLine

An existing installation can be updated using this command:

> dotnet tool update -g Ibex.CommandLine

It can be uninstalled using this command:

> dotnet tool uninstall --global Ibex.CommandLine

The Ibex.CommandLine tool, when it is installed as a dotnet global tool, is accessed using the command "ibex". So for example if we had a file called 'test.fo' this command would created a PDF file from it:

> ibex test.fo

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 6-1.

using System;
using ibex4;

public class Simple {

   static void Main( string[] args ) {

      FODocument doc = new FODocument();

      gen.generate( "manual.fo", "manual.pdf" );
   }

}
	

Figure 6-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 )
                    

Error Handling & Logging

This chapter describes error handling using the Ibex API.

Ibex associates an error handler with the library as a whole. Generally this error handler will log a message and not throw an exception.

The Ibex Logger object is a singleton which is retrieved using a call to the ibex4.logging.Logger.getLogger() method. Typically you would import the ibex4.logging namespace and then access the logger as shown in Figure 7-1.

using ibex4.logging;

void sumfunc() {
  Logger.getLogger().clearHandlers();
}
    

Figure 7-1: Clearing existing error handlers

The default error handler writes messages to the console. Messages are displayed in various circumstances including:

  • when an invalid attribute is found;

  • when a reference is made to a font or image file which cannot be found;

  • when a formatting error occurs, such as defining the widths of columns in table that exceed the available width.

As the Ibex Logger is a singleton object, logging should be configured once at the start of an application, not on a per-document basis.

Error severity

To change the level of information logged you can set the level on the logging object to one of the values defined in the ibex4.logging.Level object. Possible levels of logging which can be set are:

SEVERE WARNING INFO CONFIG FINE FINER FINEST

An example of how to set the logger to log only messages which are WARNING or worse is shown in Figure 7-2.

  
using System;

using ibex4;
using ibex4.logging;
		
public class Create {
		
  public static void Main( string[] args ) {
		
    PDFDocument doc = new PDFDocument();
		
    Logger.getLogger().setLevel( Level.WARNING );

Figure 7-2: Setting the error level

Logging to a file

To log messages to a file, create an ibex4.logging.FileHandler object and then tell the logger to log to this object. The example in Figure 7-3 logs to the file "log.txt", but any valid file name can be used.

using System;
using ibex4;
using ibex4.logging;
		
public class Create {
		
  public static void Main( string[] args ) {
		
    Logger.getLogger()
      .setLevel( Level.SEVERE )
      .clearHandlers()
      .addHandler( 
        new FileHandler("log.txt") );
	

Figure 7-3: Logging to a file

The FileHandler object synchronises access to the log file.

If you omit the clearHandlers() call shown in the above example, log records will be written to the default console handler and also to the file handler. You will see error messages on the console and they will also be written to the file.

Logging to a stream

Ibex can log messages to a stream created by the caller. The stream is any object which implements the System.IO.Stream interface.

To log messages to a stream, create an ibex4.logging.StreamHandler object and then tell the logger to log to this object. The example in Figure 7-4 logs to a MemoryStream, but any valid stream can be used.

using System;
using System.IO;
using ibex4;
using ibex4.logging;
		
public class Create {
		
  public static void Main( string[] args ) {
		
    Logger.getLogger().clearHandlers();
    MemoryStream stream = new MemoryStream();
    StreamHandler h = new StreamHandler( stream );
    Logger.getLogger().addHandler( h )

Figure 7-4: Logging to a stream

If you omit the clearHandlers() call shown in the above example log records will be written to the default console handler and to the stream handler as well.

Logging to multiple destinations

Errors can be logged to any number of handlers. The example in Figure 7-5 logs to a file called "xslfo.log", to a memory stream and to the console.

using System;
using System.IO;

using ibex4;
using ibex4.logging;

public class Create {

public static void Main( string[] args ) {
 
   MemoryStream stream = new MemoryStream();

   Logger.getLogger()
        .addHandler( new ConsoleHandler() )
        .addHandler( new StreamHandler( stream ) )
        .addHandler( new FileHandler("xslfo.log") );
   }
}
      

Figure 7-5: Logging to multiple destinations

Page Layout

This chapter describes how to configure the size of a page and position the regions in which content appears.

Using one layout for all pages

The first element in any FO file is the fo:root element which contains the whole FO tree defining the document and declares the XML namespaces used. Figure 8-1 shows a simple FO file.

<fo:root xmlns="http://www.w3.org/1999/XSL/Format">
  <fo:layout-master-set>
    <fo:simple-page-master master-name="layout" page-width="8.5in" page-height="8in">
      <fo:region-body region-name="body" margin="2.5cm"/>
    <fo:/simple-page-master>
  <fo:/layout-master-set>
  <fo:page-sequence master-reference="layout">
    <fo:flow flow-name="body">
      <fo:block>Hello world<fo:/block>
    <fo:/flow>
  <fo:/page-sequence>
<fo:/root>

Figure 8-1: Simple FO file

The first FO element within the fo:root element is the fo:layout-master-set element. This contains one or more fo:simple-page-master elements which define the layout of a page, including the width and height.

The simple-page-master element is like a template for a page, defining the page size and the areas on the page into which content will be placed. As content is read from a fo:flow, Ibex decides which simple-page-master to use as the basis for creating the current page. If there is only one fo:simple-page-master then it is always used. If there are several fo:simple-page-masters then a selection process is used to see which one applies to the current page.

The fo:simple-page-master element contains region elements such as fo:region-body which define an area on the page which can be filled with text or image content.

There can be any number of fo:simple-page-master elements provided each has a unique master-name attribute.

Figure 8-2 shows an example of a fo:layout-master-set.

<fo:layout-master-set>
  <fo:simple-page-master master-name="front-page">
    <fo:region-body margin-right="2.5cm" margin-left="4cm" margin-bottom="4cm" margin-top="4cm" region-name="body" background-color="#eeeeee"/>
    <fo:region-after extent="3cm" region-name="footer" background-color='#dddddd'/>
  <fo:/simple-page-master>
<fo:/layout-master-set>

Figure 8-2: Example layout-master-set

This shows a fo:layout-master-set which contains a single fo:simple-page-master with a master-name of "front-page".

This fo:simple-page-master defines a page which has two regions on which content can be rendered. For the purposes of this example the regions have background-colors defined to show them clearly. More complex layouts showing five regions appear in the examples on page .

Having defined a page layout which has a name, (defined by its master-name attribute) we then use the fo:page-sequence element to define the content of the document. The fo:page-sequence element has a master-name attribute which should match the master-name defined for a fo:simple-page-master (or a fo:page-sequence-master, more of which later).

A fo:page-sequence for printing "Hello World" is shown in Figure 8-3.

<fo:page-sequence master-reference="front-page">
  <fo:flow flow-name="body">
    <fo:block>Hello World<fo:/block>
  <fo:/flow>
<fo:/page-sequence>

Figure 8-3: page-sequence for hello world

A key thing to note is that the content of the fo:page-sequence is contained in a fo:flow element. For content of the flow to appear on the PDF page the flow-name attribute of the fo:flow element must match the region-name of a region on the page master specified by the master-reference on the fo:page-sequence. If the flow-name does not match a region-name, none of the content of this fo:flow will appear in the output document.

It is important to understand this feature. It means that a fo:page-sequence can contain multiple fo:flow and fo:static-content elements each containing a fo:flow element with a different flow-name. Only fo:flow elements whose flow-name attribute matches a region-name defined in the current page sequence will appear. This is how we produce different formats for odd and even pages.

Figure 8-4 shows in matching colors the attributes which should match for content to appear.

<fo:root xmlns="http://www.w3.org/1999/XSL/Format">
  <fo:layout-master-set>
    <fo:simple-page-master master-name="front-page">
      <fo:region-body margin-right="2.5cm" margin-left="4cm" margin-bottom="4cm" margin-top="4cm" region-name="body"/>
      <fo:region-after extent="3cm" region-name="footer"/>
    <fo:/simple-page-master>
  <fo:/layout-master-set>

  <fo:page-sequence master-reference="front-page">
    <fo:flow flow-name="body">
      <fo:block>Hello World<fo:/block>
    <fo:/flow>
  <fo:/page-sequence>
<fo:/root>

Figure 8-4: Matching flow and region names

Using different layouts for different pages

It is possible to define different page layouts for different pages. This can be done in two possible ways, either by assigning different page masters to different page sequences, or by using a page-master-alternatives element which chooses from a set of simple-page-master elements based on criteria such as the current page number.

Using different page masters for each page sequence

Using a different page master for each page sequence is useful when you can clearly divide the document into distinct sections. For example, this manual has a different page master for the front cover and for the pages in the table of contents. The page masters for this are shown in Figure 8-5.

<fo:layout-master-set>

  <fo:simple-page-master master-name="front-page" margin="1.5cm" page-height="297mm" page-width="210mm">
    <fo:region-body region-name="body" margin="0.75cm 0.5cm 0.75cm 3cm"/>
    <fo:region-before region-name="header" extent="2.5cm"/>
    <fo:region-after region-name="footer" extent="1cm"/>
    <fo:region-start extent="1cm" background-color="#eeeeee"/>
  <fo:/simple-page-master>

  <fo:simple-page-master master-name="toc-page" margin="1.5cm" >
    <fo:region-body column-count="1" region-name="body" margin="0.75cm 0.5cm 1cm 3cm" margin-left="2cm" margin-right="1.5cm" />
    <fo:region-before region-name="header" extent="1cm"/>
    <fo:region-after region-name="footer" extent="0.75cm"/>
    <fo:region-start extent="2cm" />
    <fo:region-end region-name="end" extent="1.5cm" />
  <fo:/simple-page-master>

<fo:/layout-master-set>

Figure 8-5: Two page masters

Content is allocated to the two sections of the document using two separate page-sequences, as shown in Figure 8-6.

<fo:page-sequence master-reference="front-page">        
   <fo:flow flow-name="body">
      <fo:block>
        content that appears in the body of the front page
      <fo:/block>
  <fo:/flow>
<fo:/page-sequence>

<fo:page-sequence master-reference="toc-page">        
   <fo:flow flow-name="body">
      <fo:block>
        content that appears in the table of contents
      <fo:/block>
  <fo:/flow>
<fo:/page-sequence>

Figure 8-6: Allocating content to two page masters

When using this approach content from one flow always appears on pages with the same layout. Flowing content across different page layouts is described in the next section.

Using page master alternatives

Often it is desirable to have content flow continuously across pages with different layouts. This is done in the Ibex manual, where the pages are laid out like this:

  • first page of chapter
    • has no page header
    • page number is on the right of the footer
  • even numbered page
    • has a page header
    • page number is on the left of the footer
  • odd numbered page
    • has a page header
    • page number is on the right of the footer

The three page masters are shown in Figure 8-7.

<fo:simple-page-master  master-name="chapter-odd-no-header">
  <fo:region-body region-name="body" margin="2.5cm 2.5cm 2.5cm 4.0cm"/>
  <fo:region-after region-name="footer-odd" extent="1.5cm" display-align="before"/>
<fo:/simple-page-master>

<fo:simple-page-master master-name="chapter-even">
  <fo:region-body region-name="body" margin="2.5cm 2.5cm 2.5cm 4.0cm" column-count="1"/>
  <fo:region-before region-name="header-even" extent="1.5cm" display-align="after"/>
  <fo:region-after region-name="footer-even" extent="1.5cm" display-align="before"/>
<fo:/simple-page-master>

<fo:simple-page-master  master-name="chapter-odd">
  <fo:region-body region-name="body" margin="2.5cm 2.5cm 2.5cm 4.0cm"/>
  <fo:region-before region-name="header-odd" extent="1.5cm" display-align="after"/>
  <fo:region-after region-name="footer-odd" extent="1.5cm" display-align="before"/>
<fo:/simple-page-master>

Figure 8-7: Page masters for three different layouts

To make content from a single flow element span multiple pages with different page layouts we use a fo:page-sequence-master element as shown in Figure 8-8. This element contains a fo:repeatable-page-master-alternatives element, which in turn contains a set of fo:conditional-page-master-reference elements.

When formatting content from a fo:page-sequence which has flow-name="chapter", Ibex looks at each of the conditional-page-master-reference elements and chooses which one will be active for the current page. This is done by evaluating conditions specified with the page-position attribute. As a page is created, each conditional-page-master-reference is considered in turn, starting from the first one. The first one found whose conditions are satisfied will determine the page master for the current page. Since alternatives are considered in the order in which they appear in the FO, the order in which the alternatives are listed is important.

When the first page of the chapter is being created, the page-position="first" condition is true, so the first conditional-page-master-reference will be chosen because it has page-position = "first". This has master-reference = "chapter-odd-no-header", so the simple-page-master with master-name = "chapter-odd-no-header" becomes the active page master for the first page of the chapter.

When the second page of the chapter is being created, the page-position="first" is no longer true so the conditions on the next conditional-page-master-reference will be evaluated.

Although not shown in this example, other attributes such as blank-or-not-blank can be used to control the selection of one of the alternatives.

<fo:page-sequence-master master-name="chapter" >
  <fo:repeatable-page-master-alternatives>
    <fo:conditional-page-master-reference page-position="first" master-reference="chapter-odd-no-header"/>
    <fo:conditional-page-master-reference odd-or-even="odd" master-reference="chapter-odd"/>
    <fo:conditional-page-master-reference odd-or-even="even" master-reference="chapter-even"/>
  <fo:/repeatable-page-master-alternatives>
<fo:/page-sequence-master>

Figure 8-8: The page-sequence-master element

Text Formatting

Text is created in the output document using the block element.

The simplest possible block is shown in Figure 9-1.

<fo:block>hello world<fo:/block>	

Figure 9-1: A simple block

This creates a paragraph in the output document which has the default font (which is helvetica) and the default alignment (which is left).

The sections below describe elements and attributes used to control the formatting of text.

Using the font attribute

The quickest way to get the font you require is to use the font attribute, as shown in Figure 9-2.

<fo:block font="bold 12pt garamond">hello world<fo:/block>

Figure 9-2: Using the font attribute

Using the font attribute is simpler than specifying all the individual attributes such as font-weight and font-size, but does need some care. When using the font attribute the order of the words is important. The font style (normal, italic) and the font weight (bold, normal) must come before the font size. The font name must come after the font size. If the font name contains spaces, it must be enclosed in quotes, in Figure 9-3.

<fo:block font="bold 12pt "times new roman"">
      hello world
<fo:/block>

Figure 9-3: A font name with spaces

The full syntax of the font attribute is shown in Figure 9-4.

[ [ <fo:font-style> || <fo:font-variant> || <fo:font-weight> ]?
<fo:font-size> [ / <fo:lineheight>]?
<fo:font-family> ]

Figure 9-4: Syntax of font attribute

Using the font-family attribute

The font-family attribute is used to specify the name of the font to use. More than one font name can be listed. These names can be specific font names such as "times roman" or "garamond", or generic names such as "monospace". Ibex will use the first name in the list which matches a font on your system. Font names are separated by a comma.

The ability to list multiple font names derives from the CSS standard. It is designed to support the creation of a web page which will be rendered on a computer that may not have the same fonts installed as the page's author. In practice when you generate a PDF file you know what fonts you have installed, so you will probably just specify one font.

Italic text

Text is made italic using the font-style attribute.

The font style can be "normal" or "italic". Other font values such as the font-family are inherited from the current font, as shown in Figure 9-5.

<fo:block font-family="arial">
  hello <fo:inline font-style="italic">world<fo:/inline>
<fo:/block>

Figure 9-5: Using font-style

Bold text

Text is made bold using the font-weight attribute.

The font weight can be "normal" or "bold", as shown in Figure 9-6.

<fo:block font-family="arial">
  hello <fo:inline font-weight="bold">world<fo:/inline>
<fo:/block>

Figure 9-6: Using the font-weight attribute

Text size

The size of text is set using the font-size attribute.

The font size specifies the size of the font and can be specified in a number of ways listed below.

A numeric size

The most common approach is to specify the size you want in points, for example font-size="12pt" or font-size="30pt".

An absolute size

Attribute ValueSize
xx-small7.0pt
x-small8.3pt
small10.0pt
medium12.0pt
large14.4pt
x-large17.4pt
xx-large20.7pt

A relative size

This sets the font size based on the size of the prevailing font.

Attribute ValueSize
smallerexisting size / 1.2
largerexisting size * 1.2

Another way of setting the font size relative to the current font size is to use the "em" unit. "1.0em" is the current font size, so "2.0em" specifies a size which is twice as big as the current size.

Underlining text

Text is underlined using the text-decoration attribute.

Specifying text-decoration="underline" will cause text to be underlined, like this.

Striking out text

You can strike out text using the text-decoration attribute.

Specifying text-decoration="line-through" will cause text to be underlined, like this. The precise position of the horizontal line from the baseline is read from the prevailing font file.

Horizontal alignment

Horizontal alignment is specified using the text-align attribute. The default alignment is left.

Valid values for text-align are shown in the table below.

ValueEffect
lefttext is aligned against the left edge of the block
righttext is aligned against the right edge of the block
centertext is centered in the middle of the block
justify text is aligned against both the left and right edges of the block. Space is inserted between words to achieve this effect. Setting text-align = "justify" does not align the last line of the paragraph, this is done using text-align-last = "justify".
start text is aligned against the start edge, which for a block that is not rotated, with the default left-to-right writing direction, is the left edge.
end text is aligned against the end edge, which for a block that is not rotated, with the default left-to-right writing direction, is the right edge.
inside assuming the document is to be bound as a book, text is aligned against the edge which is nearest the binding. For an odd-numbered page this will be the left edge, for an even numbered page it will be the right edge.
outside assuming the document is to be bound as a book, text is aligned against the edge which is furtherest from the binding. For an odd-numbered page this will be the right edge, for an even numbered page it will be the left edge.

For text-align values of "inside" and "outside" the page number is used to determine the binding edge, which is assumed to be the left hand edge of odd-numbered pages and the right hand edge of even-numbered pages.

The effect of some of the text-align values is shown in .

This paragraph has no text-align attribute, so by default is aligned to the left, so that the words form a smooth line against the left margin and a ragged edge on the right. This paragraph has text-align="right" and so is aligned to the right, so that the words form a smooth line against the right margin and have a ragged edge on the left. This paragraph has text-align="justify", so that the words form a smooth line against both the left and right margins, except for the last line which is aligned independently using the text-align-last attribute. This paragraph has text-align="center", so that the words are centered in the middle of the block.

Justifying the last line of a paragraph

Specifying text-align="justify" will justify all lines of a paragraph except the last. This is because a justified paragraph typically looks like the one in , with the last line not being justified.

Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Nunc mollis, turpis vehicula aliquam auctor, metus turpis tempus justo, eu gravida nisl nibh vitae nisl. Cras a nisl. Integer et metus vitae dui placerat egestas. Duis rutrum. Nulla in enim. Suspendisse vel massa in mauris sagittis pharetra. Etiam hendrerit euismod velit. Ut laoreet lectus nec nisl.

The text-align-last attribute controls the alignment of the last line of a paragraph. Values include are shown in the table below:

ValueEffect
relative if text-align is "justify", align the last line against the start edge (normally the left edge), otherwise use the setting if the text-align attribute.
lefttext is aligned against the left edge of the block
righttext is aligned against the right edge of the block
start text is aligned against the start edge, which for a block that is not rotated, with the default left-to-right writing direction, is the left edge.
end text is aligned against the end edge, which for a block that is not rotated, with the default left-to-right writing direction, is the right edge.
inside assuming the document is to be bound as a book, text is aligned against the edge which is nearest the binding. For an odd-numbered page this will be the left edge, for an even numbered page it will be the right edge.
outside assuming the document is to be bound as a book, text is aligned against the edge which is furtherest from the binding. For an odd-numbered page this will be the right edge, for an even numbered page it will be the left edge.
justify justify the last line across the whole width of page.

Left and right margins

The margins of a block are specified using the margin-left and margin-right attributes.

The margin properties indent the edge of the paragraph by the specified amount from the edge of the containing area.

The FO for a block with a 2.5cm left margin is shown in Figure 9-7.

<fo:block margin-left="2.5cm">hello world<fo:/block>	

Figure 9-7: Setting the left margin

If we nest another block inside this one, as shown in Figure 9-8, the margins are cumulative.

<fo:block margin-left="2.5cm">
  block 1
  <fo:block margin-left="2.5cm">
    block 2
  <fo:/block>	
<fo:/block>	

Figure 9-8: Nested blocks

<fo:block margin-left="2.5cm" background-color="#777777">
  block 1
  <fo:block margin-left="2.5cm"  background-color="#999999">
    block 2
  <fo:/block>
<fo:/block>

Figure 9-9: Nested blocks with background color

The approach to indentation defined in the XSL-FO standard is that the content of two nested blocks which do not specify a margin have the same left edge. The edges of the content (which in our example is the text) are aligned, and any borders and padding are placed outside those edges. Figure 9-10 shows the FO for two nested blocks with no margin attributes. The text will be vertically aligned and the background colors will be placed outside the text.

  
<fo:block padding="1cm" background-color="#777777">
  block 1
  <fo:block padding="1cm" background-color="#999999">
    block 2
  <fo:/block>
<fo:/block>

Figure 9-10: Nested blocks with no margins specified

In XSL-FO terms, both areas have the same start-indent and hence the same content rectangle, and the padding on the outer block extends outside its content rectangle. This may seem counter-intuitive to some developers used to the CSS model. You can invoke the CSS nested areas model by specifying a margin-left value, even "0pt".

Spacing between letters

The amount of space between two letters is dependent on the font used. Ibex reads the TrueType or Type 1 font file and loads the width of each character. Kerning information which specifies adjustments to the gaps between particular pairs of characters is also read from the font file and used in the text formatting process.

The spacing between letters can be changed using the letter-spacing attribute. Any value specified using this attribute is added to the default spacing specified by the font.

Figure 9-11 shows the FO to increase the letter spacing of some text.

<fo:block letter-spacing="0.2em">WELLINGTON NEW ZEALAND<fo:/block>

Figure 9-11: Using letter-spacing

It is possible to make letters closer than normal using a negative value for letter-spacing. Example FO for this is shown in Figure 9-12 and the result in .

<fo:block letter-spacing="-0.1em">WELLINGTON NEW ZEALAND<fo:/block>

Figure 9-12: Moving letters closer together

WELLINGTON NEW ZEALAND

Spacing before and after words

Spacing before and after text is specified using the space-start and space-end attributes on the inline element.

The space-start attribute specifies space to appear before text, space-end specifies space to appear after the text.

Figure 9-13 shows how to specify a gap between two words. This FO produces a 3cm gap between the words.

<fo:block>
  hello <fo:inline space-start="3cm">world<fo:/inline>
<fo:/block>

Figure 9-13: Using space-start

Space between words is collapsed (i.e. merged) by default. If a word has space-end="1.0cm" and the following word has space-start="0.5cm", the gap between the two words will be the larger of the two spaces (i.e. 1.0cm), not the sum. FO showing this is in Figure 9-14.

<fo:block>
  <fo:inline space-end="1cm">hello<fo:/inline>
  <fo:inline space-start="0.5cm">world<fo:/inline>
<fo:/block>

Figure 9-14: FO showing merging of spaces

Forcing a line break

You can cause a line break in normal text by inserting an empty block element. Figure 9-15 shows an FO example which does this and shows the resulting output.

<fo:block>
  this will be line one <fo:block/>this will be line two
<fo:/block>

Figure 9-15: Forcing a line break

Space at the start of a line

Space specified with the space-start attribute is normally discarded at the start of the line. To force it to be retained use the space-start.conditionality attribute.

Figure 9-16 shows two blocks which create two lines. The first block will have no space at the start of the word. The second block has space-start.conditionality="retain" so the space specified by the space-start="1cm" will be retained. The output created by this FO is shown in .

<fo:block background-color="#eeeeee">
  <fo:inline space-start="1cm">
  discard
  <fo:/inline>
<fo:/block>
<fo:block background-color="#eeeeee">
  <fo:inline space-start="1cm" space-start.conditionality="retain">
  retain
  <fo:/inline>
<fo:/block>

Figure 9-16: Using retain

discard retain

Vertical alignment

The vertical alignment of blocks of text within a containing flow or block is controlled by the display-align attribute.

The vertical alignment of words on a line is controlled by the vertical-align attribute.

Text on a line is positioned relative to the baseline, which is shown in .

By default text sits on the baseline. In the terms of the XSL-FO specification, this is the alphabetic baseline.

40pt

The height of the font above the baseline is the ascender. The height of the font below the baseline is the descender. Adding the ascender and descender values for the font (not for individual characters) gives the font size. The leading is the space above and below the characters, and is the difference between the line-height and the font-size.

The XSL-FO specification refers to the ascender value as the text-altitude and the descender as the text-depth. Together these two values add up to the allocation rectangle height. In these terms:

leading = ( line-height - text-altitude - text-depth )

so

1/2 leading = ( line-height - text-altitude - text-depth ) / 2

By default the line height is 1.2em. The em unit is proportional to the size of the current font, so as the font size increases so does the line height. This can be changed by setting the Settings.LineHeightNormal value. For instance to make the line height larger and so space text out more vertically you could use the code in Figure 9-17.

      FODocument doc = new FODocument();
      
      doc.Settings.LineHeightNormal = "1.4em";

Figure 9-17: Changing the default line height

The effect of subscript and superscript text on line spacing

When calculating the largest characters on this line, we really mean those whose ascender and descender values are greatest (i.e. futherest from the baseline). When making this calculation, the value of the line-height-shift-adjustment attribute is considered. If text is a subscript or superscript and so has a baseline-shift value which changes its position vertically, this will also change its effective ascender and descender values. If line-height-shift-adjustment = "consider-shifts" (the default value) then the baseline-shift amount is taken into account when working out the greatest ascender and descender. If line-height-shift-adjustment = "disregard-shifts" then the effect of the baseline-shift is ignored. Setting line-height-shift-adjustment = "disregard-shifts" makes lines stay the same distance apart regardless of subscript and superscript elements.

The effect line-height-shift-adjustment is shown in ; the first two lines are in a block which has line-height-shift-adjustment= "consider-shifts" and so are further apart than the second two which are in a block which has line-height-shift-adjustment = "disregard-shifts":

Specifies a string on which content of cells in a table column will align (see the section, in the CSS2 Recommendation2). Specifies a string on which content of cells in a table column will align (see the section, in the CSS2 Recommendation2).

The baseline

The baseline is below the top of the text block a distance equal to 1/2 leading + max(ascender), which places the baseline in the same place for all text elements. This means that normally text rests on the same baseline regardless of the font size, as shown in .

40pt 20pt

Subscript and superscript

Subscripted and superscripted text is created by using the baseline-shift attribute on an inline element.

The effect of the baseline shift is shown in , where the "pt" characters are in an inline element with baseline-shift = "5pt".

40pt 30pt

The FO to move a word above the current baseline by 5 points is shown in Figure 9-18 with the resulting output appears in .

<fo:block
  hello
  <fo:inline color="red" baseline-shift="5pt">
    super
  <fo:/inline>
<fo:/block>

Figure 9-18: FO showing baseline-shift

hello super

Font files contain default baseline shift values for superscripted and subscripted text. Rather than specifying baseline-shift="5pt", you can use the values "super" and "sub". The FO to move a word above the current baseline by the default amount for the current font is shown in Figure 9-19 with the resulting output in . Using the "sub" and "super" values is preferable to using specific measurements because it means (a) if you change the font size of the paragraph you do not have to change all the baseline-shift values and (b) you get the baseline sift the font designer intended.

<fo:block
  hello
  <fo:inline color="red" baseline-shift="super">
    super
  <fo:/inline>
<fo:/block>

Figure 9-19: Using the default superscript

hello super

Line stacking strategies

XSL-FO uses the line-stacking-strategy attribute to determine how lines are stacked vertically on a page. The default value of this attribute is "max-height". When the "max-height" strategy is used the height of a line depends on the height of the characters or images on that line. The information which follows assumes that this default value is used. The other values for line-stacking-strategy, namely "font-height" and "line-height" will produce different results, since the height of the line using these strategies does not change when the content of the line changes.

The leading value is calculated from the line-height and font-size specified for the block element which contains the text. It is constant for the whole block and is not affected by other values specified on contained within the block.

The height the line is calculated using "largest" characters found on the line, i.e. the sum of the max(ascender) and max(descender) values.

Aligning images

An inline element such as external-graphic is treated similarly to a text element. The height of the image is used as the ascender value. The descender value is zero.

This means that by default an image will be positioned on the baseline, as shown in .

40pt

A large image will contribute a large ascender value to the baseline placement calculation, but will still sit on that baseline as shown in .

40pt

The before-edge baseline

By default an element has an alignment-baseline value of "baseline" and so sits on the baseline shown in the above diagrams. For a given line, the largest thing on that line which has alignment-baseline = "baseline" establishes the position of the before edge baseline. This is shown in .

40pt

To align another object with the before edge baseline, either set vertical-align = "top" or alignment-baseline = "before-edge".

shows a second smaller image with default alignment, which positions it on the baseline.

40pt

By specifying vertical-align="top" on the external-graphic for the second image, we can align this image to the before edge baseline and get the layout shown in .

40pt

If all the elements on the line have vertical-align = "top", then the before edge baseline cannot be calculated, so the text before edge baseline is used. This is the top of the ascender for the font specified for the block which contains the elements.

Fonts

Ibex supports TrueType fonts. When Ibex starts font information is read from font files. By default Ibex looks for font files in:

  • c:\windows\fonts- on Windows
  • /usr/share/fonts/truetype - on Linux

If fonts are stored in other than these default locations your can tell Ibex where to find them by using a FontFinder object as shown here:

using ibex4.fontdatabase;
...
FontFinder finder = new FontFinder();
finder.addSearchPath(@"c:\windows\fonts\");
finder.addSearchPath(@"d:\windows\fonts\");
FODocument doc = new FODocument(finder);

This approach works on Windows and Linux.

Information on how to list the fonts which Ibex can use can be found in the usage chapter on page listing-available-fonts.

How Ibex uses fonts

Your FO file contains a series of letters. Each of which is stored in the file as a one or two byte code point such as 65 for 'A' or 0x8226 for the bullet character.

Ibex reads a TrueType font file and looks in the font to see if the font supports that particular code point. If it does, then the font maps that code point to a glyph, which is what gets displayed.

Not all fonts support all code points. For example arial.ttf is 370 KB in size, whereas arialuni.ttf is 23,000 KB, because arialuni has glyphs for a many more code points that arial.ttf.

Not all fonts map a code point to the same glyph. Some fonts map code points they do not support to a glyph such as the square box one.

Floats

The fo:float element can be used to position an image or other elements to the side or top of the page and cause text to flow around that image.

The paragraph in Figure 11-1 uses two fo:float elements to make the image appear on the left and right sides, with the text flowing around the images and below them.

image not found:float1.png

Figure 11-1: Left and right floats

The XML used to create Figure 11-1 is as follows:

<fo:block font-size="1.0em" text-align="justify">
    <fo:float float="left">
      <fo:block-container inline-progression-dimension="2.5cm">
        <fo:block text-align="center">
          <fo:external-graphic src="url(ibexorange.jpg)" content-width="50%" padding="3pt"/>
        <fo:/block>
      <fo:/block-container>
    <fo:/float>
Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Duis in dolor quis lectus cursus condimentum. Vestibulum id nunc vitae dui semper ultrices. Mauris a mi. Phasellus eu lacus. Pellentesque eu ligula mattis odio faucibus faucibus. Aliquam sit amet
    <fo:float float="right">
      <fo:block-container inline-progression-dimension="2.5cm">
        <fo:block text-align="center">
          <fo:external-graphic src="url(ibexorange.jpg)" content-width="50%" padding="3pt"/>
        <fo:/block>
      <fo:/block-container>
    <fo:/float>
nunc laoreet tellus ullamcorper malesuada. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia Curae; Cras nec mauris. Proin cursus tincidunt leo. Maecenas metus lacus, imperdiet fermentum, blandit at, sollicitudin eu, sem. Duis elementum libero vitae lacus. Curabitur justo. Aliquam erat volutpat. Maecenas nec nulla in massa consectetuer volutpat. Aenean turpis nisl, rutrum a, posuere sit amet, varius in, enim. Praesent risus. Nam volutpat enim eget neque. Maecenas a dui ac felis nonummy sollicitudin. Proin iaculis. Vestibulum in eros sit amet libero mollis convallis. nunc laoreet tellus ullamcorper malesuada. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia Curae; Cras nec mauris. Proin cursus tincidunt leo. Maecenas metus lacus,imperdiet fermentum, blandit at, sollicitudin eu, sem. Duis elementum libero vitae lacus. Curabitur justo. Aliquam erat volutpat. Maecenas nec nulla in massa consectetuer volutpat. Aenean turpis nisl, rutrum a, posuere sit amet, varius in, enim. Praesent risus. Nam volutpat enim eget neque. Maecenas a dui ac felis nonummy sollicitudin. Proin iaculis. Vestibulum in eros sit amet libero mollis convallis.
<fo:/block>
  

Figure 11-2: FO for float example

This effect is achieved by having a fo:block which contains the text and two fo:float elements. The fo:float elements in turn contain a fo:block-container element which has a inline-progression-dimension attribute defining the width of the float area. Any elements inside the block-container will be in the float area. If a fo:block-container is not used within the float and the width of the float cannot be determined, a default configurable value is used.

The FO for creating the above is show in Figure 11-2. Figure 11-2 is itself contained inside an fo:float with float = "before", which will make it appear at the top of the following page. This technique is used in this manual when we do not want a large example to be split across page breaks or to interrupt the content. When a fo:float has float = "before", its position in the PDF file is not the same as its position in the FO file, in that it will be moved to the top of the next page and the blocks before and after the fo:float will flow as if the fo:float was not there.

The side on which the float occurs is specified using the float attribute. This can be set to "left" or "right" to position the fo:float at the side of the page. It can also be set to "before" to position the fo:float at the start of the next page.

Side floats (with float = "left" or float = "right") are closely tied to the block which contains the float element. If the float element does not fit on the page, then the float and some or all of the containing block will be moved to the following page. This ensures that the text in the block does not refer to (for example) an image in the float which is not on the same page as the text.

How the float width is calculated

Ibex looks at the content of the fo:float element to try and determine how wide the float should be. If a block-container element is found directly below the float element, and this block-container has a width attribute, then that determines the width of the float. If no width can be found, then the width of the float is calculated from by multplying the containing block width by Settings.SideFloatDefaultWidthPercentage, which defaults to 30%.

Space Handling

XSL-FO defines various attributes for managing whitespace in FO. These allow you to control how linefeeds and whitespace are output.

Linefeeds and carriage returns

A linefeed is a character with ASCII code 10, or Unicode code point U+000A. This is different to a carriage return which has ASCII code 13. Ibex acts on linefeeds, not on carriage returns. Carriage returns are ignored during PDF creation.

Default treatment of linefeeds and spaces

By default linefeeds and whitespace preceding and following linefeeds are removed during formatting. Figure 12-1 shows FO which has linefeeds at the end of each line. The resulting output shown in Figure 12-2 has neither linefeeds nor spaces around the text. This is the default treatment for text in XSL-FO.

<fo:block margin='2cm'>To be, or not to be: that is the question:
Whether 'tis nobler in the mind to suffer
The slings and arrows of outrageous fortune,
Or to take arms against a sea of troubles,
<fo:/block>

Figure 12-1: Text with linefeeds and spaces

image not found:linefeed1.png

Figure 12-2: Output with default settings

Using linefeeds to break text

The linefeed-treatment attribute is used to specify the treatment of linefeeds in text. This defaults to "ignore" causing linefeeds to be ignored. We can retain the linefeeds by setting the linefeed-treatment attribute to "preserve". Figure 12-3 shows our example with this attribute added. Figure 12-4 shows the output from this FO.

<fo:block linefeed-treatment="preserve">To be, or not to be: that is the question:
Whether 'tis nobler in the mind to suffer
The slings and arrows of outrageous fortune,
Or to take arms against a sea of troubles,
<fo:/fo:block>
    

Figure 12-3: Using linefeed-treatment

image not found:linefeed2.png

Figure 12-4: Output with linefeed-treatment

We do not recommend using the linefeed-treatment attribute. It is too prone to breaking when the file is edited with different tools which might insert carriage returns instead of linefeeds or might reformat lines. It is better to use empty fo:block elements to mark line endings like this:

<fo:block>To be, or not to be: that is the question:<fo:block/>
Whether 'tis nobler in the mind to suffer<fo:block/>
The slings and arrows of outrageous fortune,<fo:block/>
Or to take arms against a sea of troubles,<fo:block/>
<fo:/fo:block>

Figure 12-5: Using explicit line endings

Retaining spaces

The white-space-treatment and white-space-collapse attributes are used to control the handling of spaces.

If we want to put some formatted code in our document, Figure 12-6 shows FO for this.

<fo:block linefeed-treatment="preserve">
private void swap_byte( ref byte x, ref byte y ) {
    byte t = x;
    x = y;
    y = t;
}
<fo:/block>

Figure 12-6: Code example

Setting linefeed-treatment = "preserve" we get the output show in Figure 12-7. We have preserved the linefeeds but all formatting spaces have gone.

image not found:lf3o.png

Figure 12-7: Code example output

The white-space-collapse attribute controls whether Ibex compresses adjacent white space characters into a single space. By default any number of adjacent spaces are compressed into a single space.

The white-space-treatment attribute controls whether Ibex ignores spaces adjacent to linefeeds. Setting white-space-treatment = "preserve" makes Ibex retain white space which appears adjacent to linefeeds.

If we set white-space-treatment to "preserve", and white-space-collapse to "false" we will retain the white spaces around the linefeeds. The FO for this is shown in Figure 12-8, and the formatted output is shown in Figure 12-9.

<fo:block
   linefeed-treatment="preserve"
    white-space-treatment="preserve"
   white-space-collapse="false"
      >
private void swap_byte( ref byte x, ref byte y ) {
    byte t = x;
    x = y;
    y = t;
}
<fo:/block>

Figure 12-8: FO to retain spaces and linefeeds

image not found:lf4o.png

Figure 12-9: FO to retain spaces and linefeeds output

Non-breaking spaces

Unicode defines the code point U+00A0 called NO-BREAK SPACE. This can be used to insert a space between words without allowing a line break to occur between the words. Ibex treats two words separated by a U+00A0 as a single word.

The non-breaking space can be inserted into XML using the &#xA0; entity.

The example in Figure 12-10 shows a block used in a table header. It contains the three words "Score per 100". The default formatting is shown in Figure 12-11. If we want to move the word "per" to the next line to keep it with the "100", we replace the space between "per" and "100" with a non-breaking space. This will prevent Ibex breaking the line between the "per" and "100" words.

<fo:block-container width="2.8cm">
  <fo:block border="1pt solid black"
     padding="3pt" text-align="center">
    Score per 100
  <fo:/block>
<fo:/block-container>

Figure 12-10: FO without a non-breaking space

image not found:lf5o.png

Figure 12-11: FO without a non-breaking space output

<fo:block-container width="2.8cm">
  <fo:block border="1pt solid black"
       padding="3pt" text-align="center">
    Score per&#xA0;100
  <fo:/fo:block>
<fo:/fo:block-container>

Figure 12-12: FO with non-breaking space

shows the FO with a non-breaking space and Figure 12-13 shows the resulting output.

Score per 100

image not found:lf6o.png

Figure 12-13: Output with a non-breaking space output

Colors

XSL-FO defines various attributes for managing color. By default a block is displayed with the foreground color (that is the text) being black and the background color being white.

Colors are most commonly expressed using the RGB color scheme, where there are three parts to a color: red, green and blue. Ibex also supports the CMYK color scheme commonly used in the printing industry.

Text color

The color of text is specified using the color attribute. Figure 13-1 shows a simple example of some FO to make text blue.

<fo:block color="blue">
  To be, or not to be: that is the question:
<fo:/block>

Figure 13-1: FO for blue text

Background color

The background color of any element is defined using the background-color attribute. Figure 13-2 shows FO for a block with a gray background.

<fo:block background-color="gray">
    To be, or not to be: that is the question:
<fo:/block>

Figure 13-2: FO for gray background

Available colors

The value used for the color and background-color attributes can be a predefined color such as "red", an RGB color defined using a hex value such as "#eeffdd" or a CMYK color.

Predefined colors

XSL-FO uses the list of colors defined for HTML 4.0, which contains these values:

Name Color
aqua ibex
black ibex
blue ibex
fuchsia ibex
gray ibex
green ibex
lime ibex
maroon ibex
navy ibex
olive ibex
purple ibex
red ibex
silver ibex
teal ibex
white ibex
yellow ibex

Hexadecimal RGB colors

A color can be defined as a string of six digits preceded by a "#" character. The first two digits define the red component of the color, in a range from 0 to 255. The second two digits define the green component and the last two digits define the blue component. This is the same scheme for defining colors as is used in HTML.

CMYK colors

CMYK colors are four-part colors using values for cyan, magenta, yellow and black respectively. The CMYK system is subtractive, meaning that higher values mean less color, unlike RGB where higher values mean more color. CMYK colors are used in the printing industry to define a color which will appear the same across all media. Typically a color defined using RGB will not appear exactly the same on the screen and on a printed page, or even on two different computer screens. CMYK colors are used to ensure that colors are the same on screen and on the printed page.

PDF files are usually created with single color scheme. You would not usually mix CMYK and RGB colors in one document. Note that when creating a CMYK PDF file any images included in the document should be in CMYK format.

A CMYK color is defined using the rgb-icc() function. This takes eight parameters. The first three define the red, green and blue components of a fallback RGB color, the fourth defines the color profile name, and the last four define the four parts of the CMYK color. The color profile must have been declared in the declarations formatting object using a color-profile element.

Figure 13-3 shows an example of the rgb-icc() function.

<fo:block color="rgb-icc( 0, 0, 0, cmyk, 0.7,0.3,0.3,0.4 )">
   in cmyk .5,.5,.5,0
<fo:/block>

Figure 13-3: The rgb-icc function

In Figure 13-3 the three components of the fallback RGB color are zero. This is normal because we are creating a CMYK PDF file and will not be using any fallback RGB colors. The color profile name is "cmyk". Ibex requires that the color profile name be "cmyk" when creating a CMYK color.

A complete document using the CMYK color space is shown in Figure 13-4. This shows how to use the declarations and color-profile elements to define a color profile.

<fo:?xml version="1.0" encoding="UTF-8"?>
<fo:root xmlns="http://www.w3.org/1999/XSL/Format">
	<fo:layout-master-set>
		<fo:simple-page-master master-name="page">
			<fo:region-body margin="1in" region-name="body"/>
		<fo:/simple-page-master>
	<fo:/layout-master-set>
	
	<fo:declarations>
	    <fo:color-profile src="src" color-profile-name="cmyk"/>
	<fo:/declarations>
		
	<fo:page-sequence master-reference="page">
		<fo:flow flow-name="body">
			<fo:block color="rgb-icc( 0, 0, 0, cmyk, 0.7,0.3,0.3,0.4 )">
			in cmyk .5,.5,.5,0
			<fo:/block>
		<fo:/flow>
	<fo:/page-sequence>
<fo:/root>

Figure 13-4: FO for a CMYK PDF file

PDF/X color profiles

Ibex can create PDF files which conform to the PDF/X standard. These files can include embedded color profiles, used to define a common color scheme across different devices.

Color profiles are loaded from files on disk and included in the PDF file. Some color profiles are very large (i.e. > 500k) and can result in large PDF files.

Loading a color profile from a file on disk is an Ibex extension. The name of the color profile file is specified using the color-profile-file-name attribute of the ibex:pdfx element, as shown in Figure 13-5 below.

<fo:?xml version="1.0" encoding="UTF-8"?>
<fo:root xmlns="http://www.w3.org/1999/XSL/Format" xmlns:ibex="http://www.xmlpdf.com/2003/ibex/Format">
	<fo:layout-master-set>
		<fo:simple-page-master master-name="page" page-width="20cm">
			<fo:region-body region-name="body" margin="3cm" reference-orientation='0'/>
		<fo:/simple-page-master>
	<fo:/layout-master-set>

	<fo:ibex:pdfx color-profile-file-name="colorprofiles\USWebCoatedSWOP.icc" output-condition="TR001 SWOP/CGATS"/>

	<fo:page-sequence master-reference="page">
		<fo:flow flow-name="body">
		
			<fo:block font="10pt arial">
				hello world
			<fo:/block>
	<fo:/flow>
		
		
	<fo:/page-sequence>
<fo:/root>

Figure 13-5: FO for a PDF/X showing the loading of a color profile

Lists

Lists are created using the fo:list-block element. A fo:list-block in XSL-FO is an area of content divided into two columns.

We recommend using tables rather than lists. Any output that can be created using an fo:list can be created with a two-column fo:table. So save yourself the time learning fo:lists and just use fo:tables.

A simple fo:list-block is shown in Figure 14-1. The list created by this FO is shown in .

<fo:list-block provisional-distance-between-starts=".5cm" 
   provisional-label-separation="0.1cm">
  <fo:list-item>
     <fo:list-item-label end-indent="label-end()">
        <fo:block font='8pt arial'>&#x25CF;<fo:/block>
     <fo:/list-item-label>
     <fo:list-item-body start-indent="body-start()">
          <fo:block>
              item one
          <fo:/block>
      <fo:/list-item-body>
  <fo:/list-item>
  <fo:list-item>
     <fo:list-item-label end-indent="label-end()">
        <fo:block font='8pt arial'>&#x25CF;<fo:/block>
     <fo:/list-item-label>
     <fo:list-item-body start-indent="body-start()">
          <fo:block>
              item two
          <fo:/block>
      <fo:/list-item-body>
 <fo:/list-item>
<fo:/list-block>

Figure 14-1: FO for a list

Features of lists include:

  • the fo:list-block is a block-level element which contains the whole list.

  • the provisional-​distance-​between-​starts attribute on the fo:list-block defines the distance between the start of the label and the start of the body.

  • the provisional-label-separation attribute on the fo:list-block defines the size of the gap between the end of the label and the start of the body. This gap is created by reducing the size of the label. For example, if provisional-​distance-​between-​starts is 5cm and the provisional-​label-​separation is 1cm, then the start edges of the label and body will be 5cm apart, and the label will be 4cm (5cm - 1cm) wide.

  • each item in the list is contained in a fo:list-item element.

  • each fo:list-item must contain both a fo:list-item-label and a fo:list-item-body. The fo:list-item-label must come first.

  • the fo:list-item-label should have the end-indent attribute set to "label-end()". This is a special function which returns a value derived from provisional-​distance-​between-​starts and provisional-​label-​separation.

  • the fo:list-item-body should have the start-indent attribute set to "body-start()". This is a special function which returns a value derived from provisional-​distance-​between-​starts and provisional-​label-​separation.

  • both the fo:list-item-label and fo:list-item-body contain one or more block-level elements, so a fo:list-item-label or fo:list-item-body can contain other block-level elements such as fo:block, fo:table and fo:list-block.

Bulleted lists

The example in Figure 14-1 also shows how to insert a Unicode character into the FO, using the syntax &#x25CF;.

This table shows some common bullet types for lists:

UnicodeValue
&#x2022;

&#x2023;

&#x25CF;

&#x25CB;

&#x25A0;

&#x25A1;

&#x25C6;

&#x25C7;

Note that what is displayed in the document depends on whether the font you are using contains the specified character. If the font does not contain the specified character you will see a warning message like the one in Figure 14-2.

warning:380 No glyph index found for code point 2023 in font ArialMT

Figure 14-2: Error message if bullet not in font

Tables

A table in XSL-FO is an area of content divided into rows and columns. A table is created with the fo:table element.

A FO for a simple table is shown in Figure 15-1 and the output it creates is shown in Figure 15-2. This shows the basic structure of a fo:table element containing fo:table-body, fo:table-row and fo:table-cell elements.

<fo:table>
  <fo:table-body>
    <fo:table-row>	
      <fo:table-cell border="1pt solid blue" padding="2pt">
            <fo:block>row 1 column 1<fo:/block>
      <fo:/table-cell>
      <fo:table-cell border="1pt solid blue" padding="2pt">
            <fo:block>row 1 column 2<fo:/block>
      <fo:/table-cell>
    <fo:/table-row>
    <fo:table-row>	
       <fo:table-cell border="1pt solid blue" padding="2pt">
             <fo:block>row 2 column 1<fo:/block>
       <fo:/table-cell>
       <fo:table-cell border="1pt solid blue" padding="2pt">
             <fo:block>row 2 column 2<fo:/block>
       <fo:/table-cell>
    <fo:/table-row>
<fo:/table-body>

Figure 15-1: FO for a simple 2 x 2 table

image not found:table1.png

Figure 15-2: Simple table

The padding and border attributes are not inherited from containing elements, so are best defined on the fo:table-cell elements.

Cell padding

Padding is the amount of space that appears between the inside edge of the border of a cell and the outside edge of the content of the cell. Padding is specified by the padding attribute. The default amount of padding is '0pt'. Figure 15-4 shows a table with two cells. The first cell has padding="1pt" and the second has padding="5pt". Padding is almost always used to avoid having the content too close to the cell borders.

<fo:table keep-together.within-page="always">
	<fo:table-body>
		<fo:table-row>
			<fo:table-cell border="1pt solid blue" padding="1pt">
				<fo:block>this cell has padding set to '1pt' so the text is close to the edges of the cell<fo:/fo:block>
			<fo:/fo:table-cell>
			<fo:table-cell border="1pt solid blue" padding="5pt">
				<fo:block>this cell has padding set to '5pt' so the text is not so close to the edges of the cell<fo:/fo:block>
			<fo:/fo:table-cell>
		<fo:/fo:table-row>
	<fo:/fo:table-body>
<fo:/fo:table>

Figure 15-3: FO showing cells with different padding

image not found:table2.png

Figure 15-4: Different levels of padding on cells

The padding attribute sets padding for all four sides of the cell. Individual sides can be set using the padding-left, padding-right, padding-top and padding-bottom attributes.

The padding attribute also supports a shorthand format where:

  • if one value is specified ( padding="2pt" ) the same value will apply to all four sides;

  • if two values are specified ( padding="2pt 3pt" ) the first value will apply to the top and bottom edges, the second value to the left and right edges;

  • if three values are specified ( padding="2pt 3pt 1pt" ) the first value will apply to the top edge, the second to the left and right edges, and the third to bottom edge;

  • if four values are specified ( padding="2pt 3pt 1pt 0pt" ) these will apply to top, right, bottom and left edges in that order.

Cell background color

The background color of a cell is specified using the background-color attribute. This supports the same predefined colors as CSS and the use of hex values such as "#33ffcc". The background color of the cell extends to the inside edge of the border, which means that the area specified by the padding attribute is colored by the background color.

If you do not want the background to extend to the edge of the padding, specify the background-color attribute on the contents of the cell (i.e. the fo:block elements) rather than on the fo:table-cell. An example FO for this is shown in Figure 15-5 and the resulting output appears in .

<fo:table>
  <fo:table-body>
    <fo:table-row>	
      <fo:table-cell border='1pt solid blue' padding='1pt'>
            <fo:block>
            this cell has padding set to '1pt' so the text is close to the edges of the cell
            <fo:/block>
      <fo:/table-cell>
      <fo:table-cell border='1pt solid blue' padding='5pt' 
            background-color='#dddddd'>
            <fo:block background-color='#dddddd'>
            this cell has padding set to '5pt' so the text is not so close to the edges of the cell
            <fo:/block>
      <fo:/table-cell>
    <fo:/table-row>
<fo:/table-body>

Figure 15-5: FO setting the background color on a fo:table-cell

Cell background images

An image can be used as the background to a cell by specifying the background-image element, as shown in Figure 15-6.

<fo:table>
  <fo:table-body>
    <fo:table-row>	
      <fo:table-cell border='1pt solid blue' padding='1pt'>
            <fo:block>
            this cell has padding set to '1pt' so the text is close to the edges of the cell
            <fo:/block>
      <fo:/table-cell>
      <fo:table-cell border='1pt solid blue' padding='5pt' 
            background-image='url(ibex.jpg)'>
            <fo:block>
            this cell has a background image
            <fo:/block>
      <fo:/table-cell>
    <fo:/table-row>
<fo:/table-body>

Figure 15-6: FO for using an image as a cell background

By default the image will be repeated if it is less than the width of the cell. This can be changed using the background-repeat attribute. This is set to "no-repeat" the output the image once.

The background image can be positioned in the cell using the background-position-horizontal and background-position-vertical attributes.

Implicit and explicit rows

Usually FO files use the fo:table-row element to define which cells are in which rows, as shown in Figure 15-7.

<fo:table>
  <fo:table-body>
    <fo:table-row>	
      <fo:table-cell border="1pt solid blue" padding="2pt">
            <fo:block>row 1 column 1<fo:/block>
      <fo:/table-cell>
      <fo:table-cell border="1pt solid blue" padding="2pt">
            <fo:block>row 1 column 2<fo:/block>
      <fo:/table-cell>
    <fo:/table-row>
    <fo:table-row>	
       <fo:table-cell border="1pt solid blue" padding="2pt">
             <fo:block>row 2 column 1<fo:/block>
       <fo:/table-cell>
       <fo:table-cell border="1pt solid blue" padding="2pt">
             <fo:block>row 2 column 2<fo:/block>
       <fo:/table-cell>
    <fo:/table-row>
<fo:/table-body>

Figure 15-7: Tables with cells contained in rows

However it is possible to dispense with the fo:table-row element and have the fo:table-body contain fo:table-cell elements directly. In this case any cell can have the ends-row attribute set to "true", which causes a new row to be started containing the next cell. This approach is sometimes easier to use when generating the FO using XSLT, for example transforming a list of elements into a table with multiple elements one each row.

Figure 15-8 shows what the above FO would look like if we changed it to use implicit rows.

<fo:table>
  <fo:table-body>
      <fo:table-cell border='1pt solid blue' padding='2pt'>
            <fo:block>row 1 column 1<fo:/block>
      <fo:/table-cell>
      <fo:table-cell border='1pt solid blue' padding='2pt' 
            ends-row='true'>
            <fo:block>row 1 column 2<fo:/block>
      <fo:/table-cell>
       <fo:table-cell border='1pt solid blue' padding='2pt'>
             <fo:block>row 2 column 1<fo:/block>
       <fo:/table-cell>
       <fo:table-cell border='1pt solid blue' padding='2pt'>
             <fo:block>row 2 column 2<fo:/block>
       <fo:/table-cell>
<fo:/table-body>

Figure 15-8: FO for a table with implicit rows

Table columns

The fo:table-column element is used to set the column width and other characteristics of a table column. A fo:table-column element has an associated column number which determines which column the fo:table-column element refers to. This column number is either implied (with the first fo:table-column element applying to the first column, the second to the next etc.), or explicitly set using the column-number attribute.

A single fo:table-column element can be used to define the style of multiple columns by using the number-columns-spanned attribute.

Figure 15-9 shows the FO for a table with two fo:table-column elements, which apply to the first and second columns. In this case they set the column widths (to 30% and 70%), and the give the second column a shaded background.

<fo:table>
    <fo:table-column column-width='30%'/>
      <fo:table-column column-width='70%' background-color='#dddddd'/> 
  <fo:table-body>
    <fo:table-row>
      <fo:table-cell border='1pt solid blue' padding='2pt'>
            <fo:block>row 1 column 1<fo:/block>
      <fo:/table-cell>
      <fo:table-cell border='1pt solid blue' padding='2pt'>
            <fo:block>row 1 column 2<fo:/block>
      <fo:/table-cell>
    <fo:/table-row>
    <fo:table-row>	
       <fo:table-cell border='1pt solid blue' padding='2pt'>
             <fo:block>row 2 column 1<fo:/block>
       <fo:/table-cell>
       <fo:table-cell border='1pt solid blue' padding='2pt'>
             <fo:block>row 2 column 2<fo:/block>
       <fo:/table-cell>
    <fo:/table-row>
<fo:/table-body>

Figure 15-9: FO using table-column elements

Some cell attributes such as background color are determined using attributes from the cell itself and from the other elements of the table structure. The order of precedence in determining cell characteristics such as background-color is fo:table-cell, fo:table-row, fo:table-body, fo:table-column and finally fo:table.

Proportional column widths

Columns can be allocated widths which are proportional to the widths of other columns. For example, if we have two columns and want to give the first column twice the width of the second, we can specify column widths using the proportional-column-width() function as shown in Figure 15-10. The total of the values used in the proportional-column-width() functions is 3 (2+1), so the first column will gave 2/3 of the width and the second 1/3.

<fo:table>
  <fo:table-column 
         column-width='proportional-column-width(2)'/>
  <fo:table-column 
         column-width='proportional-column-width(1)' 
         background-color='#dddddd'/>
  <fo:table-body>
    <fo:table-row>	
      <fo:table-cell border='1pt solid blue' padding='2pt'>
            <fo:block>row 1 column 1<fo:/block>
      <fo:/table-cell>
      <fo:table-cell border='1pt solid blue' padding='2pt'>
            <fo:block>row 1 column 2<fo:/block>
      <fo:/table-cell>
    <fo:/table-row>
    <fo:table-row>	
       <fo:table-cell border='1pt solid blue' padding='2pt'>
             <fo:block>row 2 column 1<fo:/block>
       <fo:/table-cell>
       <fo:table-cell border='1pt solid blue' padding='2pt'>
             <fo:block>row 2 column 2<fo:/block>
       <fo:/table-cell>
    <fo:/table-row>
<fo:/table-body>

Figure 15-10: FO using proportional column widths

Spanning columns and rows

The number of columns which a cell spans is set by the number-columns-spanned attribute. An example FO for this is shown in Figure 15-11. In this example the first cell of the first row spans two columns. The output from this FO appears in Figure 15-12.

<fo:table>
  <fo:table-column column-width="30%"/>
  <fo:table-column column-width="70%" 
         background-color="#dddddd"/>
  <fo:table-body>
    <fo:table-row>	
      <fo:table-cell border="1pt solid blue" padding="2pt"
          number-columns-spanned="2">
            <fo:block>row 1 column 1<fo:/block>
      <fo:/table-cell>
    <fo:/table-row>
    <fo:table-row>	
       <fo:table-cell border="1pt solid blue" padding="2pt">
             <fo:block>row 2 column 1<fo:/block>
       <fo:/table-cell>
       <fo:table-cell border="1pt solid blue" padding="2pt">
             <fo:block>row 2 column 2<fo:/block>
       <fo:/table-cell>
    <fo:/table-row>
<fo:/table-body>

Figure 15-11: FO for cell spanning 2 columns

image not found:table4.png

Figure 15-12: Cell spanning two columns

The number of rows which a cell spans is set by the number-rows-spanned attribute. Example FO for this is shown in Figure 15-13. In this example the first cell of the first row spans two rows. The output from this FO appears in Figure 15-14.

<fo:table>
    <fo:table-column column-width='30%'/>
    <fo:table-column column-width='70%' 
         background-color='#dddddd'/>
    <fo:table-body>
    <fo:table-row>	
      <fo:table-cell border='1pt solid blue' padding='2pt'
          number-rows-spanned='2'>
            <fo:block>row 1 column 1<fo:/block>
      <fo:/table-cell>
       <fo:table-cell border='1pt solid blue' padding='2pt'>
             <fo:block>row 1 column 2<fo:/block>
       <fo:/table-cell>
    <fo:/table-row>
    <fo:table-row>	
       <fo:table-cell border='1pt solid blue' padding='2pt'>
             <fo:block>row 2 column 2<fo:/block>
       <fo:/table-cell>
    <fo:/table-row>
<fo:/table-body>

Figure 15-13: FO for cell spanning two rows

image not found:table5.png

Figure 15-14: Cell spanning two rows

Table headers

Table headers are created using the fo:table-header element. The fo:table-header should appear inside the fo:table element after any fo:table-column elements and before any fo:table-body elements. The fo:table-header element is similar in structure to a fo:table-body element in that it contains fo:table-row elements.

This section describes the behavior of table headers which do not change. Headers which can have different content on different pages are described later in this chapter in the section on continuation markers on page continuation-markers.

Figure 15-15 shows the FO for a simple table with a one row header and two content rows.

<fo:table>
	<fo:table-column column-width="100%"/>
	<fo:table-header>
		<fo:table-row>
  		<fo:table-cell border="1pt solid black" padding="5pt">
		  	<fo:block>Heading<fo:/block>
	  	<fo:/table-cell>
		<fo:/table-row>
	<fo:/table-header>
	<fo:table-body>
		<fo:table-row>
  		<fo:table-cell border="1pt solid black" padding="5pt">
		  	<fo:block>row 1<fo:/block>
	  	<fo:/table-cell>
		<fo:/table-row>
		<fo:table-row border="1pt solid black" padding="5pt">
  		<fo:table-cell>
		  	<fo:block>row 2<fo:/block>
	  	<fo:/table-cell>
		<fo:/table-row>
	<fo:/table-body>
<fo:/table>
	  
	  

Figure 15-15: Simple table with header

By default table headers are repeated at the top of the table after each page break. To prevent the table header appearing on pages after the first, specify table-omit-header-at-break = "true" on the fo:table element.

Table footers

Table footers are created using the fo:table-footer element. The fo:table-footer should appear inside the fo:table element after any fo:table-column and fo:table-header elements and before any fo:table-body elements. The fo:table-footer element is similar in structure to a fo:table-body element in that it contains fo:table-row elements.

It is a common error to place the fo:table-footer element at the end of the table, after the fo:table-body elements. It must be placed before the fo:table-body elements because Ibex may start rendering the table to PDF before the whole table has been read from the FO file.

This section describes the behavior of table footers which do not change. Footers which can have different content on different pages are described later in this chapter in the section on continuation markers on page continuation-markers.

Figure 15-16 shows the FO for a simple table with a one row header and footer and two content rows.

<fo:table>
	<fo:table-column column-width="100%"/>
	<fo:table-header>
		<fo:table-row>
  		<fo:table-cell border="1pt solid black" padding="5pt">
		  	<fo:block>Heading<fo:/block>
	  	<fo:/table-cell>
		<fo:/table-row>
	<fo:/table-header>
	<fo:table-footer>
		<fo:table-row>
  		<fo:table-cell border="1pt solid black" padding="5pt">
		  	<fo:block>Footer<fo:/block>
	  	<fo:/table-cell>
		<fo:/table-row>
	<fo:/table-footer>
	<fo:table-body>
		<fo:table-row>
  		<fo:table-cell border="1pt solid black" padding="5pt">
		  	<fo:block>row 1<fo:/block>
	  	<fo:/table-cell>
		<fo:/table-row>
		<fo:table-row border="1pt solid black" padding="5pt">
  		<fo:table-cell>
		  	<fo:block>row 2<fo:/block>
	  	<fo:/table-cell>
		<fo:/table-row>
	<fo:/table-body>
<fo:/table>

Figure 15-16: FO for simple table with header and footer

By default table footers are repeated at the bottom of the table before each page break. To prevent the table footer appearing on pages other than the last, specify table-omit-footer-at-break = "true" on the fo:table element.

Repeating headers

Table headers are repeated at the top of the table after each page break. This is the default. To prevent the table header appearing on pages after the first, specify table-omit-header-at-break = "true" on the fo:table element.

Repeating footers

Table footers are repeated at the bottom of the table before each page break. This is the default. To prevent the table footer appearing on pages other than the last, specify table-omit-footer-at-break = "true" on the fo:table element.

Repeating table borders

Table borders by default do not repeat at a break in the table, so the top border of a table is rendered only on the first page the table is on and the bottom border is rendered only on the last page.

To make the table bottom border repeat at each page break it is necessary to specify border-after-width.conditionality = "retain" on the table element.

To make the table top border repeat at each page break it is necessary to specify border-before-width.conditionality = "retain" on the table element.

Table continuation markers

Table continuation markers provide a way of dynamically changing the header and footer on a table so that different content can be displayed on different pages. A typical use of this feature is to put the words "continued on next page" in the footer of a table on all pages except the last.

Here we examine how the "continued on next page" requirement can be satisfied using Ibex. The approach taken by XSL-FO has two parts, implemented using the fo:marker and fo:retrieve-table-marker elements. First a fo:retrieve-table-marker element is added to the footer. When the PDF is created this element will be replaced by the contents of one of the fo:marker elements which has the same value for the class attribute. Which fo:marker element is chosen to appear in the table footer depends on the values of the attributes on the fo:retrieve-table-marker.

The footer for this example is shown in Figure 15-17. As the PDF file is created the contents of the fo:marker element with marker-class-name = "continued" will be located and inserted into the fo:table-footer element. The content of the marker element must be valid FO elements for their position in the table-footer. In this example the retrieved elements go directly under the table-footer element, so the elements retrieved must be table-row elements.

<fo:table-footer>
  <fo:retrieve-table-marker 
        retrieve-class-name="continued" 
        retrieve-position-within-table="first-starting" 
        retrieve-boundary-within-table="page"/>
<fo:/table-footer>

Figure 15-17: FO for retrieve-table-marker

Typically, there will be more than one fo:marker element which has the marker-class-name = "continued". If this is not the case then the footer content will never change. The retrieve-position attribute specifies which marker to retrieve. In this example we want the first marker which appears on the page, so we use retrieve-position = "first-starting-within-page". We also specify retrieve-boundary = "table" so any marker from any part of the table which has been output to PDF can be retrieved. Other options are detailed later in this section.

Conceptually, Ibex looks at every row in the table which has been output to the PDF file (including rows on the current page), collects all the markers associated with each of those rows and selects one to go into the footer. Markers associated with rows which are not on either the current page or prior pages are not considered. It is possible to have a different marker associated with every row in the table. This is useful for situations such as like rendering a running total.

The second part of the process is to define one or more fo:marker elements. In this case our marker elements are associated with fo:table-row elements. The first table-row has a marker element which specifies the "continued on next page" text. The contents of this marker will be retrieved for all pages except the last.

The last row of the table has an empty marker element. The content of this (that is to say no rows) will be what appears in the footer on the last page of the table. The marker from the first row is shown in Figure 15-18 and the marker from the last row is shown in Figure 15-19.

<fo:table-row>
	<fo:marker marker-class-name="continued">
		<fo:table-row>
			<fo:table-cell>
				<fo:block>continued on next page/<fo:block>
			<fo:/table-cell>
		<fo:/table-row>
	<fo:/marker>
	
	<fo:table-cell>
		<fo:block>row 1 cell 1 /<fo:block>
	<fo:/table-cell>
<fo:/table-row>

Figure 15-18: FO for marker in the first table row

<fo:table-row>
	<fo:marker marker-class-name="continued"/>
	<fo:table-cell>
		<fo:block>row (last) cell 1 /<fo:block>
	<fo:/table-cell>
<fo:table-row>

Figure 15-19: FO for marker in the last table row

Aligning columns at the decimal point

Ibex can align the contents of cells in a column on the decimal point by specifying text-align="." on each fo:table-cell in the column. This can be done explicity on each fo:table-cell, or to make things easier to maintain it can be done by specifying text-align="." on the fo:table-column and text-align="from-table-column" on each fo:table-cell.

Example FO for aligning columns is shown in Figure 15-20.

<fo:table font="10pt arial">
  <fo:table-column column-width="50%" />
  <fo:table-column column-width="50%" text-align="."/>
  <fo:table-body>
    <fo:table-row>
      <fo:table-cell border="1pt solid black" padding="3pt" >
        <fo:block>ibexdls<fo:/block>
      <fo:/table-cell>
      <fo:table-cell border="1pt solid black" padding="3pt" 
         text-align="from-table-column()">
        <fo:block>499.02<fo:/block>
      <fo:/table-cell>
    <fo:/table-row>
    <fo:table-row>
      <fo:table-cell border="1pt solid black" padding="3pt" >
        <fo:block>Total<fo:/block>
      <fo:/table-cell>
      <fo:table-cell border="1pt solid black" padding="3pt" 
         text-align="from-table-column()" font-size="18pt">
        <fo:block>499.00<fo:/block>
      <fo:/table-cell>
    <fo:/table-row>
  <fo:/table-body>
<fo:/table>

Figure 15-20: FO for decimal point alignment

image not found:table6.png

Figure 15-21: Output for decimal point alignment

Images

Image basics

Images are added to the document using either the fo:external-graphic or fo:instream-foreign-object elements. The fo:external-graphic element is used to include a file in JPEG, GIF, TIFF, BMP, SVG or PNG formats. The fo:instream-foreign-object element is used to include an image defined in Scalable Vector Graphics (SVG) format where the image SVG is contained within the FO.

The properties used to format the fo:external-graphic and fo:instream-foreign-object elements are the same.

The size of the image is distinct from the size of the area in which the image is placed.

The height and width attributes on the external-graphic or instream-foreign-object element specify the size of the area into which the graphic will be placed. If these properties are not specified they default to an area large enough to contain the image.

The content-width and content-height attributes control the size of the image. These can be values such as "3cm" or percentages such as "120%". If content-width and content-height not specified the image defaults to the size in pixels specified in the image file itself. This means that if you do not specify any of the above attributes the image will be as large as specified in the image file, and will be placed in an area the same size.

The dots per inch (dpi) value of the image makes a difference to the image size. Two images can have the same dimensions in pixels but appear different sizes in the PDF file. This is because Ibex uses the dpi value to work out the size of the image. An image which is 300 pixels wide and stored at 300 dpi will be 1 inch wide. The same image stored at 100 dpi will be 3 inches wide.

An image is an inline element, so for formatting purposes it can be placed in a sentence surrounded by text and is treated as a single word.

The fo:external-graphic element is used to include an image which is in a file external to the FO file. The name of the file to be included is specified using the src attribute.

The src attribute is called a uri-specification and must follow the following rules:

A sequence of characters that is "url(", followed by optional white space, followed by an optional single quote (') or double quote (") character, followed by a URI reference as defined in [RFC2396], followed by an optional single quote (') or double quote (") character, followed by optional white space, followed by ")". The two quote characters must be the same and must both be present or absent. If the URI reference contains a single quote, the two quote characters must be present and be double quotes.

This means the following are all valid values for the src attribute:

uri(ibex.jpg)

uri("ibex.jpg")

uri('ibex.jpg')

url(http://www.xmlpdf.com/images/download2.gif)

As the src attribute is a URL, an image which exists on a web server can be downloaded automatically by Ibex as the PDF file is created. This is common in real estate and catalog applications and means you do not need to make a copy of an existing image just to get it into the PDF file. The FO shown in Figure 16-1 will fetch the file download2.gif from http://www.xmlpdf.com.

<fo:block space-before="6pt">
   <fo:external-graphic border="1pt solid black" src="url(http://www.xmlpdf.com/images/download2.gif)" 
     content-width="200%" content-height="200%"/>
<fo:/block>

Figure 16-1: FO to insert an image from a web server

The fo:external-graphic element can be used to include image files in PNG, JPEG, TIFF, BMP, SGV and GIF formats.

The fo:inline-foreign-object is used for loading images from SVG content that is contained inline in the FO. See SVG Images on page .

Making an image fit a specified space

To make an image fit a specified size use the height and width attributes to specify the size of the fo:external-graphic element, and then use the content-width and content-height to fit the image to the size specified on the fo:external-graphic element.

For example to fit an image into an area 2cm x 2cm, set the width and height attributes to "2cm" and set the content-width and content-height attributes to "scale-to-fit".

<fo:external-graphic src="url(image.jpg)"
	height="2in" width="2in" 
	content-height="scale-to-fit"  
	content-width="scale-to-fit"/>

Figure 16-2: Scaling an image

If you only want the image reduced in size to fit the specified area and do not want it increased in size if it is smaller, specify content-width="scale-down-to-fit". This also applies to content-height.

If you only want the image enlarged to fit the specified area and do not want it reduced in size if it is larger, specify content-width="scale-up-to-fit". This also applies to content-height.

Clipping

If the image is larger than the area in which it is contained then the image may be clipped. If we specify the height of the fo:external-graphic element as 2.5cm and specify overflow="hidden", the image will be clipped to this height.

If we specify the height of the fo:external-graphic element as 2.5cm and do not specify overflow="hidden", the image will not be clipped to this height, and will overwrite other content as shown to the right. Because the image is positioned on the same baseline as text, the overflow will be at the top of the area containing the image.

Image size and alignment

If an image is smaller than the containing area we can control where it appears in that area using the display-align and text-align attributes. The display-align attribute controls the vertical alignment, text-align controls the horizontal alignment. By default the image appears in the top left corner of the inline area created by the fo:external-graphic or fo:instream-foreign-object element, as shown in Figure 16-3

image not found:image7.png

Figure 16-3: Default image alignment

If we specify text-align="center" the image will move to the horizontal center of the inline area, as shown in Figure 16-4.

image not found:image8.png

Figure 16-4: Centered image alignment

The image is an inline element and can be treated like a normal word, so that attributes such as "text-align" apply can be used. If we specify text-align="center" and display-align="center" the image will move to the horizontal and vertical center of the inline area, as shown in .

image not found:image9.png

Figure 16-5: Image horizontal and vertical alignment

Leading

Looking at the image in Figure 16-6 you can see a gap between the top of the image and the border. This is the leading, which appears because the image is treated as a text element and sits on the baseline. The amount of leading is derived from the font size, so you can reduce it to zero by setting the font size to zero, by specifying font-size="0pt" on the containing block element. This has been done in Figure 16-7.

image not found:image10.png

Figure 16-6: Image showing leading

image not found:image11.png

Figure 16-7: Image with no leading

Image resolution

The resolution of an image in dots per inch (dpi) can be set using the dpi attribute on the fo:external-graphic element. Setting this attribute overrides the dpi value read from the image file.

Setting the dpi to a lower value than the one specified in the image will result in smaller image of lower quality than the original. This is often done to reduce the size of the image in the PDF file and can result in massive decreases in PDF file size. If you have an image which is stored at 2400 dpi, and your end user will display it on a 96 dpi screen or print it on 600 dpi printer, reducing the image dpi to 600 will not effect the appearance of the image.

Setting the dpi to a value higher than the value read from the image file has no effect.

If for example if we wanted to store an image in the PDF file at 1200 dpi, we would use the FO shown in Figure 16-8.

<fo:block space-before="6pt">
  <fo:external-graphic border="1pt solid black" 
      src="url(http://www.xmlpdf.com/images/download2.gif)" 
      content-width="200%" content-height="200%"
      dpi="1200"/>
<fo:/block>

Figure 16-8: FO to set image dpi

The dpi attribute is an Ibex extension. It is not part of the XSL-FO standard.

Image anti-aliasing

Images are anti-aliased by default. This can be disabled using the ibex:anti-alias attribute as shown in figure Figure 16-9.

<fo:block space-before="6pt">
  <fo:external-graphic 
      src="url(http://www.xmlpdf.com/images/download2.gif)" 
      ibex:anti-alias="false"
      dpi="1200"/>
<fo:/block>

Figure 16-9: FO to disable anti-aliasing

image not found:image12.png

Figure 16-10: Images with and without anti-aliasing

Figure 16-10 shows two images, the left right one has anti-aliasing disabled so the edges of the image appear more clearly.

The ibex:anti-alias attribute is an Ibex extension. It is not part of the XSL-FO standard.

Loading an image from memory

Ibex has the facility to load an image which is stored in memory. This permits an application to dynamically generate an image or to load an image from a database for inclusion in the PDF file.

The image must be passed to Ibex in a byte array or a Stream (from the System.IO namespace).

The image must be given a unique identifier by which it can be retrieved during the PDF creation process. This is done using the addNamedImage() method on the FODocument object. This method takes two parameters; (1) a string which identifies the image and (2) the stream or array which contains the image itself.

For example if we had an image in a byte array called "image" and we wanted to give it the identifier "1029" we would use the code shown in Figure 16-11 to do this.

byte[] image = ... dynamically create
FODocument document = new FODocument();
document.addNamedImage( "1029", image );

Figure 16-11: C# code to load an image from memory

This must be done before calling generate() to create the PDF file.

Within the FO file the image is retrieved from memory using the syntax shown in Figure 16-12

<fo:external-graphic src="url(data:application/ibex-image,1029)"/>

Figure 16-12: FO to load an image from memory

The value of the src attribute must be the string "url(data:application/ibex-image," followed by the unique identifier which was passed to addNamedImage().

This syntax for the url attribute conforms to RFC 2397 - The "data" URL scheme (which can be found at http://www.faqs.org/rfcs/rfc2397.html).

Transparent GIF images

GIF images which have transparent areas are supported. The FO in Figure 16-13 places the same transparent GIF image on two different backgrounds.

<fo:block background-color="blue">
   <fo:external-graphic src="url(ibm-logo.gif)" content-height="2cm"/>
<fo:/block>  
<fo:block background-color="black">
   <fo:external-graphic src="url(ibm-logo.gif)" content-height="2cm"/>
<fo:/block>  

Figure 16-13: FO for transparent image

Transparent PNG images

PNG images which have transparent areas are supported. The FO in Figure 16-14 places a transparent PNG image on a white backgrounds.

<fo:block background-color="white">
   <fo:external-graphic src="url(RedbrushAlpha-0.25.png)" content-height="2cm"/>
<fo:/block>  

Figure 16-14: FO for transparent image

Transparent images using masking

Ibex can use image masking to make some parts of an image appear transparent. This is an extension to the standard.

Image masking works by defining colors from the image which should not be displayed. The PDF viewer will compare each pixel in the image with the mask and not display pixels which match the mask, effectively making these pixels transparent and so leaving visible the content behind the image.

The image mask is defined using the <fo:ibex:mask> element, which must be contained within an fo:external-graphic element, as shown in Figure 16-15.

<fo:external-graphic src="url(ixsl.jpg)"  z-index='10'>
	<fo:ibex:mask 
	       red-min="255" red-max="255"   
	       green-min="255" green-max="255"  
	       blue-min="255" blue-max="255"/>
<fo:/external-graphic>

Figure 16-15: FO to mask an image

To use the ibex:mask element you must reference the ibex namespace in your FO as shown in Figure 16-16.

<fo:root 
  xmlns:fo="http://www.w3.org/1999/XSL/Format" 
  xmlns:ibex="http://www.xmlpdf.com/2003/ibex/Format">

Figure 16-16: Referencing the ibex namespace

The mask defines the minimum and maximum values for each of the red, green and blue components of an image. A mask using these values is applicable only to images which are in RGB format with 24 bits per pixel.

For CMYK images, attributes called c-min, c-max, m-min, m-max, y-min, y-max, k-min and k-max define the minimum and maximum values for each of the cyan, magenta, yellow and black components of the image.

The image mask shown above causes any pixel which has red=255, green=255 and blue=255 to not be rendered. As a pixel with red, green and blue all equal to 255 is white, this means any white pixels will not be rendered.

Transparent Images using SVG

Transparent images can also be implemented by placing a SVG image over the top of other content. This approach uses the vector SVG renderer introduced in Ibex 2.1.2 and is only available when using .NET 1.1 or higher. This is the best approach for transparent images because (a) there is no background on the SVG image so the best clarity is achieved, and (b) SVG uses a vector renderer which creates a smaller PDF file than you would get using a bitmap image.

Figure 16-17 shows the FO to put the word "ibex" over some text.

<fo:block-container>
  <fo:block-container space-before="6pt" 
    absolute-position="absolute" top="-1.6cm" 
        left="5cm">
    <fo:block>
       <fo:instream-foreign-object z-index="30">
          <fo:svg width="315" height="100" 
              xmlns="http://www.w3.org/2000/svg">
               <fo:text  x="30" y="60" fill="blue" stroke="blue" 
                  font-size="61pt" font-style="italic"
                  style="font-family:arial;stroke-width:0.5">
                  Ibex
               <fo:/text>
          <fo:/svg>
       <fo:/instream-foreign-object>
    <fo:/block>
  <fo:/block-container>
<fo:/block-container>

Figure 16-17: FO using SVG to place content over text

Network credentials used in accessing images

Ibex can retrieve images from HTTP servers as shown in Figure 16-18 below. By default Ibex will do this using the credentials of the process which is creating the PDF file. If Ibex is running in an ASP.NET server then the default configuration is that ASP runs as the ASPNET user. This user does not have permissions to access other servers and so will not be able to retrieve images from other servers.

<fo:block space-before="6pt">
   <fo:external-graphic border="1pt solid black" src="url(http://www.xmlpdf.com/images/download2.gif)" content-width="200%" content-height="200%"/>
<fo:/block>

Figure 16-18: FO to insert an image from an HTTP server

The FODocument object supports the setNetworkCredentials() method. This method takes 4 parameters, as shown in Figure 16-19.

public void setNetworkCredentials( 
    string prefix, 
    string username, 
    string password, 
    string domain ) 

Figure 16-19: The setNetworkCredentials method

The parameters are:

prefix The start of a URL, such as "http://www.xmlpdf.com". Any image URL which starts with this prefix will use these credentials.
username the username passed to the remote server
password the password passed to the remote server
domain the domain name passed to the remote server

Each call to setNetworkCredentials() is passed a prefix which is compared with image URLs to see which set of credentials to use.

For example if your application accesses two HTTP servers using different credentials your code might look like the code in Figure 16-20. Obviously you would get the username and password information from somewhere in your application rather than hard coding them.

FODocument doc = new FODocument()
doc.setNetworkCredentials( "http://www.xmlpdf.com","user1","password1","domain1" );
doc.setNetworkCredentials( "http://www.ibex4.com","user2","password2","domain2" );

Figure 16-20: Setting credentials for different servers

Internally Ibex uses the System.Net.WebRequest and System.Net.NetworkCredential objects to pass credentials to the remote server. If credentials have been passed to Ibex using the setNetworkCredentials() method a new NetworkCredential object is created when creating the WebRequest object. SO the actual forwarding of the credentials to the remote server is all done by .Net.

Calls to setNetworkCredentials() should be made before the generate() method is called.

Multi-page TIFF image processing

Ibex has an extension attribute "ibex:page" which is used to specify which page of a multi-page TIFF image should be included in the PDF file.

FO to place the third page of a multi-page TIFF image is shown in Figure 16-21.

<fo:block>
  <fo:external-graphic src="url('7pages.tif')" ibex:page="3"/>
<fo:/block>

Figure 16-21: Specifying the page of a multi-page TIFF image

Scalable Vector Graphics (SVG) images

Ibex supports the inclusion of Scalable Vector Graphics (SVG) images in the PDF file. SVG images retain their vector format inside the PDF file, so will remain precise under high magnification unlike bitmap images which will be come pixellated.

SVG images are inserted into the document using either the <fo:external-graphic> or <fo:instream-foreign-object> elements. Images can be included inline like this:

<fo:block border="1pt solid red">
  <fo:instream-foreign-object>
    <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20">
      <rect width="10" height="10" fill="green"/>
    </svg>
  </fo:instream-foreign-object>
</fo:block>

or from an external file like this:

<fo:block border="1pt solid red">
  <fo:external-graphic src="url(file.svg)"/>
</fo:block>

where the external file contains the SVG image, for example:

<?xml version="1.0" encoding="UTF-8"?>
<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20">
  <rect width="10" height="10" fill="green"/>
</svg>

If an image occurs more than once in the document it should be loaded from an external file so that it is only store in the PDF once.

Namespaces

The SVG image must begin with the <svg> element in the namespace "http://www.w3.org/2000/svg". Images which do not declare the namespace will not be included in the PDF.

Image size

The size of the image should be specified using the width and height attributes the outer <svg> element. These can be absolute measurements such as "3cm" or scalar values such as "400". Scalar values are assumed to be pixels and are converted to inches based on 1 pixel = 1/96 inch. Percentages cannot be effectively used; the size of the block containing the image is determined from the size of the image, at the time the image is processed the size of the containing block is unknown because it is dependent on the size of the image.

Summary of supported elements

This section briefly documents the degree to which SVG elements are supported in Ibex. It is not an SVG manual. Information on the SVG specification can be found at http://www.w3.org/TR/SVG11/expanded-toc.html

Animation of SVG elements using javascript is not supported.

<svg>

The <svg> element is used to define the size and shape of the image (using the width and height attributes) and to establish a new coordinate system using the viewBox attribute.

<g>

The <g> element used to move the coordinate system using the transform attribute. Supported transform operations are:

Operation Effect
translate(x,y) translate the coordinate system x units horizontally and y units vertically
translate(x) translate the coordinate system x units horizontally and zero units vertically
matrix(a,b,c,d,e,f) multiply the current transformation matrix by the one specified
scale(x,y) scale the coordinate system x units horizontally and y units vertically
rotate(angle) rotate the coordinate system angle degrees about the origin
rotate(angle,x,y) rotate the coordinate system angle degrees about the point x,y
skewX(angle) skew the coordinate system angle degrees along the X axis
skewY(angle) skew the coordinate system angle degrees units along the Y axis

Multiple transformations can be performed by placing them one after the other in the transform attribute, like this:

<g transform="translate(10,20) scale(2,3) rotate(30)">

Transforms will be applied in the order in which they appear.

<defs>

The <defs> element is supported as a container for other elements. See <symbol> below for an example.

<desc>

The <desc> element is ignored.

<title>

The <title> element is ignored.

<symbol>

The <symbol> element is supported. The following image shows an example of definining a system using <symbol> and retrieving it using <use>.

<?xml version="1.0" standalone="yes"?>
<svg width="10cm" height="3cm" viewBox="0 0 100 30"
      xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
  <defs>
    <symbol id="MySymbol" viewBox="0 0 20 20">
      <rect x="1" y="1" width="8" height="8"/>
      <rect x="11" y="1" width="8" height="8"/>
      <rect x="1" y="11" width="8" height="8"/>
      <rect x="11" y="11" width="8" height="8"/>
    </symbol>
  </defs>

  <use x="45" y="10" width="100" height="100" xlink:href="#MySymbol" fill="blue" />

</svg>

The <use> element will find the symbol element with id="#MySymbol" and display the content of this element, which should look like this:

<use>

The <use> element is supported, see above for an example. Note that as this element uses the xlink:href attribute it is necessary to declare the xmlns:xlink="http://www.w3.org/1999/xlink" namespace.

<image>

The <image> element is supported. This element embeds an image inside the SVG image. For example this image will display a rectangle and on top of that display the image held in the file "use_symbol.svg":

<?xml version="1.0"?>
<svg width="4cm" height="2cm" viewBox="0 0 200 100" xmlns:xlink="http://www.w3.org/1999/xlink"
      xmlns="http://www.w3.org/2000/svg" version="1.1" preserveAspectRatio="none">

  <rect width="300" height="150" stroke="red" stroke-width="1" fill="silver"/>

  <image x="20" y="20" xlink:href="use_symbol.svg" width="100" height="100"/>

</svg>

<switch>

The <switch> element is ignored.

<path>

The <path> element is supported. Internally PDF does not support quadratic Bézier curves so they are converted to cubic Bézier curves. The following SVG draws a simple curve with marked end points:

<?xml version="1.0" standalone="no"?>
<svg width="6cm" height="5cm" viewBox="0 0 1200 600" xmlns="http://www.w3.org/2000/svg">
  <rect x="1" y="1" width="1198" height="598" fill="none" stroke="blue" stroke-width="1" />

  <path d="M200,300 Q400,50 600,300 T1000,300" fill="none" stroke="red" stroke-width="5"  />
  <!-- End points -->
  <g fill="black" >
    <circle cx="200" cy="300" r="10"/>
    <circle cx="600" cy="300" r="10"/>
    <circle cx="1000" cy="300" r="10"/>
  </g>
  <!-- Control points and lines from end points to control points -->
  <g fill="#888888" >
    <circle cx="400" cy="50" r="10"/>
    <circle cx="800" cy="550" r="10"/>
  </g>
  <path d="M200,300 L400,50 L600,300
    L800,550 L1000,300"
        fill="none" stroke="#888888" stroke-width="2" />
</svg>

The curve looks like this:

Path line join shapes

The shape where a path changes direction is set with the stroke-linejoin attribute. Possible values are:

Value Shape
stroke-linejoin="miter"
stroke-linejoin="bevel"
stroke-linejoin="round"

<style>

The <style> element is currently implemented to some extent in .Net. In .Net the class attribute can be used in conjunction with a style to apply that style to an element.

<rect>

The <rect> element is supported. A simple rectangle can be drawn like this:

<svg xmlns="http://www.w3.org/2000/svg" width="400" height="120" >
  <rect x="10" y="10" width="100" height="100" fill="none" stroke="red"/>
</svg>

resulting in this image:

<circle>

The <circle> element is supported. A simple circle can be drawn like this:

<svg xmlns="http://www.w3.org/2000/svg" width="400" height="120" >
    <circle cx="50" cy="50" r="30" fill="none" stroke="red"/>
</svg>

resulting in this image:

<ellipse>

The <ellipse> element is supported. A simple ellipse can be drawn like this:

<svg xmlns="http://www.w3.org/2000/svg" width="400" height="200" >
  <ellipse cx="100" cy="100" rx="75" ry="50" fill="none" stroke="black"/>
</svg>

resulting in this image:

<line>

The <line> element is supported. A simple line can be drawn like this:

<svg xmlns="http://www.w3.org/2000/svg" width="400" height="400" >
   <line x1="10" y1="10" x2="100" y2="10" stroke="blue" stroke-width="4"/>
</svg>

resulting in this image:

Line end shapes

The shape of the end of a line is set with the stroke-linecap attribute. Possible values are:

Value Shape
stroke-linecap="butt"
stroke-linecap="round"
stroke-linecap="square"
The end of the line is the same shape as the default stroke-linecap="butt" but projects further beyond the end coordinate.

Dashed lines

Dashed lines are supported using the stroke-dasharray attribute. A dashed line can be drawn like this:

<svg xmlns="http://www.w3.org/2000/svg" width="400" height="400" >
  <line x1="10" y1="10" x2="100" y2="10" stroke="blue" stroke-width="4" stroke-dasharray="3 2"/>
</svg>

resulting in this image:

<polyline>

The <polyline> element is supported. A simple polyline can be drawn like this:

<svg xmlns="http://www.w3.org/2000/svg" width="12cm" height="4cm"
  viewBox="0 0 1200 400">
  <polyline fill="none" stroke="blue" stroke-width="10"
            points="50,375
                    150,375 150,325 250,325 250,375
                    350,375 350,250 450,250 450,375
                    550,375 550,175 650,175 650,375
                    750,375 750,100 850,100 850,375
                    950,375 950,25 1050,25 1050,375
                    1150,375" />

</svg>

resulting in this image:

<polygon>

The <polygon> element is supported. A simple polygon can be drawn like this:

<svg xmlns="http://www.w3.org/2000/svg" width="12cm" height="4cm"
      viewBox="0 0 1200 400">
        <polygon fill="red" stroke="blue" stroke-width="10"
                    points="350,75  379,161 469,161 397,215
                    423,301 350,250 277,301 303,215
                    231,161 321,161" />
        <polygon fill="lime" stroke="blue" stroke-width="10"
                  points="850,75  958,137.5 958,262.5
                    850,325 742,262.6 742,137.5" />
</svg>

resulting in this image:

<text>

The <text> element is supported.

<tspan>

The <tspan> element is not implemented.

<textpath>

The <textpath> element is not implemented.

<pattern>

The <pattern> element is not implemented.

Opacity

The attributes stroke-opacity and fill-opacity are supported. Using the group opacity attribute to apply opacity to a group of elements is not supported, instead the opacity value is applied as if stroke-opacity and fill-opacity has been specified.

This example shows a transparent blue rectangle drawn over an opaque red rectangle.

<svg xmlns="http://www.w3.org/2000/svg" width="400" height="140" >
  <rect width="400" height="140" fill="none" stroke="silver"/>
  <g transform="translate(10,10)">
    <rect width="100" height="100" fill="red"/>
  </g>
  <g transform="translate(30,30)">
    <rect width="100" height="100" fill="blue" stroke-width="1" fill-opacity="0.3" />
  </g>
</svg>

resulting in this image:

Markers

Markers are supported at the start and end of <line> and <path> elements. The <marker> element contains a separate drawing which can be reused. This example shows an arrowhead which is drawn at the each end of a line:

<?xml version="1.0" standalone="no"?>
<svg width="4in" height="2in"
     viewBox="0 0 4000 2000" version="1.1"
     xmlns="http://www.w3.org/2000/svg">
  <defs>
    <marker id="RedTriangle" viewBox="0 0 10 10" refX="0" refY="5"
      markerUnits="strokeWidth"
      markerWidth="4" markerHeight="3"
      orient="auto" fill="red">
      <path d="M 0 0 L 10 5 L 0 10 z" />
    </marker>
  </defs>
  <rect x="10" y="10" width="3980" height="1980"
       fill="none" stroke="blue" stroke-width="10" />

  <g transform="translate(400,1700) scale(.8)">
    <line x1="0" x2="1000" y1="0" y2="0" stroke="red" stroke-width="100" marker-end="url(#RedTriangle)"
          marker-start="url(#RedTriangle)"/>
  </g>

  <g transform="translate(400,700) scale(.8)">
    <line x1="0" x2="1000" y1="300" y2="0" stroke="red" stroke-width="30" marker-end="url(#RedTriangle)"
          marker-start="url(#RedTriangle)"/>
  </g>

</svg>

In this example the arrowhead appears once in the SVG, and is rendered four times. Each time it is rendered its rotaton and size are changed to match the rotation and size of the line.

Linear gradients

Linear gradients are supported. This example produces a gradient from red to yellow horizontally:

<?xml version="1.0" standalone="no"?>
<svg width="8cm" height="4cm" viewBox="0 0 800 400" version="1.1"
      xmlns="http://www.w3.org/2000/svg">

  <g>
    <defs>
      <linearGradient id="MyGradient"
           x1="100" x2="500" gradientUnits="userSpaceOnUse">
        <stop offset="5%" stop-color="#F60" />
        <stop offset="95%" stop-color="#FF6" />
      </linearGradient>
    </defs>

    <rect fill="none" stroke="blue"
          x="1" y="1" width="798" height="398"/>

    <rect fill="url(#MyGradient)" stroke="black" stroke-width="5"
          x="100" y="100" width="600" height="200"/>
  </g>
</svg>

producing this image:

The interpretation of the values specified for the coordinates x1/x2/y1/y2 of the linearGradient element changes depending on value specified for gradientUnits.

When gradientUnits="userSpaceOnUse" the specified values are in "user space", which is the space defined by the prevailing <g> element. The specified coordinates are relative to the prevailing <g> element, so two elements which use the same gradient as their fill color will appear differently if they are placed in different locations on the page.

This SVG image shows rectangles using the same gradient in conjunction with gradientUnits="userSpaceOnUse"

<?xml version="1.0" standalone="no"?>
<svg width="8cm" height="3cm" viewBox="0 0 1000 450" version="1.1" xmlns="http://www.w3.org/2000/svg">
  <g>
    <defs>
      <linearGradient id="linear_userSpaceOnUse" gradientUnits="userSpaceOnUse" x1="100" y1="100" x2="700" y2="300">
          <stop offset="5%" stop-color="#ff0000" />
          <stop offset="95%" stop-color="#0000ff" />
      </linearGradient>
    </defs>

    <rect fill="none" stroke="blue" x="1" y="1" width="990" height="440"/>

    <g transform="translate(10,50)">
       <rect fill="url(#linear_userSpaceOnUse)" x="10" y="10" width="600" height="100"/>
       <rect fill="url(#linear_userSpaceOnUse)" x="200" y="120" width="600" height="100"/>
    </g>

  </g>
</svg>

producing this image:

When gradientUnits="objectBoundingBox" the specified values are relative to the bounding box of the element being filled, and should be expressed as fractions of the dimensions of the element being filled. The values for coordinates should be in the range [0..1], so for example specifying x1="0" starts the gradient at the left hand edge of the element being filled, and specifying x1="0.2" starts the gradient at 20% of the width of that element. As the gradient is positioned relative to the element being filled, two element using the same gradient will appear the same regardless of the position of the element.

This SVG image shows rectangles using the same gradient in conjunction with gradientUnits="objectBoundingBox"

<?xml version="1.0" standalone="no"?>
<svg width="8cm" height="3cm" viewBox="0 0 1000 450" version="1.1" xmlns="http://www.w3.org/2000/svg">
  <g>
    <defs>
      <linearGradient id="linear_objectBoundingBox" x1="0" y1="0" x2="1" y2="1">
        <stop offset="5%" stop-color="#ff0000" />
        <stop offset="95%" stop-color="#0000ff" />
      </linearGradient>

    </defs>

    <rect fill="none" stroke="blue" x="1" y="1" width="990" height="440"/>

    <g transform="translate(10,50)">
       <rect fill="url(#linear_userSpaceOnUse)" x="10" y="10" width="600" height="100"/>
       <rect fill="url(#linear_userSpaceOnUse)" x="200" y="120" width="600" height="100"/>
    </g>

  </g>
</svg>

producing this image:

Radial gradients

Radial gradients are supported from version 5.7.6 onwards.

The interpretation of the values specified for the coordinates cx/cy/r/fx/fy of the radialGradient element changes depending on value specified for gradientUnits.

When gradientUnits="userSpaceOnUse" the specified values are in "user space", which is the space defined by the prevailing <g> element. The specified coordinates are relative to the prevailing <g> element, so two elements which use the same gradient as their fill color will appear differently if they are placed in different locations on the page.

This SVG image shows rectangles using the same gradient in conjunction with gradientUnits="userSpaceOnUse"

<?xml version="1.0" standalone="no"?>
<svg width="8cm" height="3cm" viewBox="0 0 1000 550" version="1.1" xmlns="http://www.w3.org/2000/svg">

  <g>
    <defs>
      <radialGradient id="radial_userSpaceOnUse" gradientUnits="userSpaceOnUse" cx="400" cy="200" r="300" fx="400" fy="200">
        <stop offset="0%" stop-color="green" />
        <stop offset="50%" stop-color="blue" />
        <stop offset="100%" stop-color="red" />
      </radialGradient>
    </defs>

    <rect fill="none" stroke="blue" x="1" y="1" width="990" height="530"/>
    <rect fill="url(#radial_userSpaceOnUse)" stroke="black" stroke-width="5" x="100" y="100" width="600" height="200"/>
    <rect fill="url(#radial_userSpaceOnUse)" stroke="black" stroke-width="5" x="100" y="310" width="600" height="200"/>
  </g>
</svg>

producing the image below, in which you can clearly see the gradient circles are centered within the first rectangle.

When gradientUnits="objectBoundingBox" the specified values are relative to the bounding box of the element being filled, and should be expressed as fractions of the dimensions of the element being filled. The values for coordinates should be in the range [0..1], so for example specifying x1="0" starts the gradient at the left hand edge of the element being filled, and specifying x1="0.2" starts the gradient at 20% of the width of that element. As the gradient is positioned relative to the element being filled, two element using the same gradient will appear the same regardless of the position of the element.

This SVG image shows rectangles using the same gradient in conjunction with gradientUnits="userSpaceOnUse"

producing the image below.

Absolute Positioning

Content can be positioned anywhere on the page by placing the content in a fo:block-container element and setting the absolute-position attribute.

If the absolute-position attribute is set to "fixed", the content will then be positioned on the page relative to the page area which contains the fo:block-container element.

If the absolute-position attribute is set to "absolute", the content will be positioned on the page relative to the reference area which contains the fo:block-container element. The reference area is not the containing block, it is the containing fo:region, fo:table-cell, fo:block-container, fo:inline-container or fo:table-caption. In XSL-FO 1.0, the specification was ambiguous and the block-container was positioned relative to the containing area, but in XSL 1.1 this has been clarified to mean the containing reference area.

Positioning block-containers

It is important to realise that block-containers are not positioned relative to the containing block. Figure 18-1 shows FO with two absolutely positioned block containers. Both block-containers will be positioned relative to the containing region, because the region is the containing reference area. As they both have the same top attribute they will both be positioned in the same place.

<fo:flow flow-name="body">
  <fo:block>
    some text
    <fo:block-container absolute-position="absolute" height="2cm" top="3cm">
       <fo:block>
         in block-container one
       <fo:/block>
    <fo:/block-container>
  <fo:/block>       

  <fo:block>
    some more text
    <fo:block-container absolute-position="absolute" height="2cm" top="3cm">
       <fo:block>
         in block-container two
       <fo:/block>
    <fo:/block-container>
  <fo:/block>       
<fo:/flow>  

Figure 18-1: Badly positioned block containers

The simplest way to position a block-container is to place it inside another block-container which does not have the absolute-position attribute. FO for doing this is shown in Figure 18-2. The outer block-container is not absolutely positioned and will be placed in the normal flow of content. The inner block-container is absolutely positioned relative to the outer one.

<fo:flow flow-name="body">
  <fo:block>
    some text
    <fo:block-container>
      <fo:block-container absolute-position="absolute" height="2cm" top="3cm">
         <fo:block>
           in block-container one
         <fo:/block>
      <fo:/block-container>
    <fo:/block-container>
  <fo:/block>       

  <fo:block>
    some more text
    <fo:block-container>
      <fo:block-container absolute-position="absolute" height="2cm" top="3cm">
         <fo:block>
           in block-container two
         <fo:/block>
      <fo:/block-container>
    <fo:/block-container>
  <fo:/block>       
<fo:/flow>  

Figure 18-2: Positioned a block-container using another block-container

Positioning and sizing block containers

A block-container with absolute-position = "absolute" is positioned relative to its containing reference area.

The distance between the left edge of the block-container and the left edge of the containing reference area is set by the left attribute. This attribute specifies the offset of the block-container's left edge from the containing reference area's left edge. The default value is "0pt", which causes the two edges to be in the same place. Positive values of left move the left edge of the block-container to the right, making the block-container smaller.

The distance between the right edge of the block-container and the right edge of the containing reference area is set by the right attribute. This attribute specifies the offset of the block-container's right edge from the containing reference area's right edge. The default value is "0pt", which causes the two edges to be in the same place. Positive values of right move the right edge of the block-container to the left, making the block-container smaller.

The distance between the top edge of the block-container and the top edge of the containing reference area is set by the top attribute. This attribute specifies the offset of the block-container's top edge from the containing reference area's top edge. The default value is "0pt", which causes the two edges to be in the same place. Positive values of top move the top edge of the block-container downwards, making the block-container smaller.

The distance between the bottom edge of the block-container and the bottom edge of the containing reference area is set by the bottom attribute. This attribute specifies the offset of the block-container's bottom edge from the containing reference area's bottom edge. The default value is "0pt", which causes the two edges to be in the same place. Positive values of bottom move the bottom edge of the block-container upwards, making the block-container smaller.

If none of the left, right, top or bottom attributes is specified the block-container will be the same size as the reference area which contains it. This is because the offsets all default to "0pt" so the edges of the block-container are the same as the edges of its containing reference area. This means a block-container with absolute-position= "absolute" which is placed in a region will by default fill that region.

The height of a block-container can be specified with the height attribute, and the width with the width attribute.

Figure 18-3 shows the FO for a block container with height and width of 10cm, and an inner block-container which is offset from the outer one, including a negative offset on the left side. The output from this FO appears in .

<fo:flow flow-name="body">
  <fo:block>
    <fo:block-container height="10cm" width="10cm" margin-left="3cm"
       background-color="#dddddd">
      <fo:block>outer block container<fo:/block>
      <fo:block-container absolute-position="absolute" 
        top="1cm"
        right="2cm"
        left="-2cm"
        bottom="4cm"
        background-color="#77ccdd"
       >
         <fo:block>
           inner block-container 
         <fo:/block>
      <fo:/block-container>
    <fo:/block-container>
  <fo:/block>       
<fo:/flow>  

Figure 18-3: block-containers positioned and sized

Multi-column pages

XSL-FO allows us to define a page which has multiple columns.

This can only be done for whole pages, not for partial pages. However if we are in a region which has multiple columns we can treat it as a single-column region and place output across the whole width of the multi-column page by setting span="all" on block-level elements which appear immediately below the flow element.

Columns are defined by setting the column-count attribute of a body region element to a value greater than 1, and optionally setting the column-gap attribute to define a gap between the columns.

The page master for this is similar to the one shown in Figure 19-1.

<fo:simple-page-master  master-name="chapter-2col-odd">
    <fo:region-start extent='2.5cm'/>
    <fo:region-end extent='2.5cm'/>
    <fo:region-body column-count='2'
       region-name="body" margin='2.5cm'/>
    <fo:region-after region-name="footer-odd" extent="2.5cm"/>
    <fo:region-before region-name="header-odd" extent="2.5cm"/>
<fo:/simple-page-master>

Figure 19-1: The page master for a multi-column page

All the blocks above, including this one, have span="all" set so that they span the whole page.

This block does not have span="all", so it will be fitted into the first column in the page. Text will flow to the bottom of this page and then start at the top of the next column.

If there are blocks above this one on the page which have span="all" (as there are) then they will remain in place and the text which is in only one column will be placed in the next column, below the span="all" blocks.

We deliberately repeat the paragraph to demonstrate this wrapping. This block does not have span="all", so it will be fitted into the first column in the page. Text will flow to the bottom of this page and then start at the top of the next column. If there are blocks above this one on the page (as there are) which have span="all" then they will remain in place and the text which is in only one column will be placed in the next column, below the span="all" blocks.

It is also possible to have a page start with content in two columns (like this).

When a block-level object is encountered which has span="all" the content already on the page is pushed up to the top, and the block with span="all" is spread over the two columns.

Bookmarks

Bookmarks are the entries which appear on the right in a PDF file in Adobe Acrobat. They are used to navigate directly to locations within the document. They also have a hierarchical structure, where one bookmark can contain a set of child bookmarks which in turn can themselves contain other bookmarks.

The bookmark-tree element is optional. If used it should be placed under the fo:root element, after the fo:layout-master-set and fo:declarations elements and before any fo:page-sequence or fo:page-sequence-wrapper elements.

The structure of a bookmark tree is shown in Figure 20-1.

<fo:bookmark-tree>
  <fo:bookmark internal-destination="section-1">
    <fo:bookmark-title>Chapter 1<fo:/bookmark-title>
    <fo:bookmark internal-destination="section-1-1">
      <fo:bookmark-title>Section 1<fo:/bookmark-title>
    <fo:/bookmark>
    <fo:bookmark internal-destination="section-1-2">
      <fo:bookmark-title>Section 2<fo:/bookmark-title>
    <fo:/bookmark>
  <fo:/bookmark>
  <fo:bookmark internal-destination="section-2">
    <fo:bookmark-title>Chapter 2<fo:/bookmark-title>
    <fo:bookmark internal-destination="section-2-1">
      <fo:bookmark-title>Section 1<fo:/bookmark-title>
    <fo:/bookmark>
  <fo:/bookmark>
<fo:/bookmark-tree>

Figure 20-1: A bookmark tree

We can see the following from the structure shown in Figure 20-1.

  • The bookmarks are contained in a fo:bookmark-tree element.

  • A fo:bookmark element has an internal-destination attribute identifying where in the document it links to. The value for this attribute should be used as the id attribute on the destination element.

  • A bookmark element can contain other bookmark elements.

  • The text which appears in the bookmark is contained within a fo:bookmark-title element. Ibex supports using Unicode text in bookmarks.

The example above creates bookmarks like the ones in the Ibex manual.

The bookmarks which have child bookmark elements appear in the PDF file in a closed state, so the user can click the '+' next to them to display the child elements. If you specify starting-state="show" on a bookmark or bookmark-tree element it's immediate children will be visible when the PDF file is opened.

Configuration

All configuration of Ibex is done using the Settings class which is accessed from the ibex4.FODocument object. This class has many properties which can be changed to configure the operation of Ibex.

Properties of the Settings class should be changed prior to calling the generate() method on the FODocument object. The fact that the Settings object is a property of the FODocument object means that different documents can have different Settings values. For example Figure 21-1 shows how to set the default line height to 1.4em.

using System;

using ibex4;

public class IbexTester {

   public static void Main(string[] args) {
   
      FODocument doc = new FODocument()
          
      doc.Settings.LineHeightNormal = "1.4em";
           
      using( Stream xml = new FileStream( args[0], FileMode.Open, FileAccess.Read ) ) {
          using ( Stream output = new FileStream( args[1], FileMode.Create, FileAccess.Write ) ) {
                    doc.generate( xml, output );
               }
           }
   }
}

Figure 21-1: Example usage of the Settings object

Fonts

The following properties on the Settings change the way fonts a processed. By default each absolute font size (small, medium, large etc.) is 1.2 times larger than the previous size.

PropertyTypeDefaultNotes
XX_Smallstring7.0pt Must end in 'pt'.
X_Smallstring8.3pt Must end in 'pt'.
Smallstring10.0pt Must end in 'pt'.
Mediumstring12.0pt Must end in 'pt'.
Largestring14.4pt Must end in 'pt'.
X_Largestring17.4pt Must end in 'pt'.
XX_Largestring20.7pt Must end in 'pt'.

PropertyTypeDefaultNotes
Smallerstring0.8em Must end in 'em'.
Largerstring1.2em Must end in 'em'.

Line height

The following properties on the Settings change the default line height. Ideally Settings.LineHeightNormal should end in 'em' to make line height proportional to the font height.

PropertyTypeDefaultNotes
LineHeightNormalstring1.2em

Page size

The following properties on the Settings change the default page size.

PropertyTypeDefaultNotes
PageHeightstring297mm
PageWidthstring210mm

Include paths

The following properties on the Settings effect retrieving XML or XSL files.

PropertyTypeDefaultNotes
BaseURI_XMLstring This value sets the base URI for including images and other XML files. When an external-graphic element specifies a relative path, Settings.BaseURI_XML is the base URI used in accordance with the rfc2396 URI Specification. When an XML file uses an entity to include another XML file, Settings.BaseURI_XML is the base URI used when Ibex searches for the included XML file.
BaseURI_XSLstring This value sets the base URI for including other XSL files. When an xsl:include element is used to include another XSL stylesheet, Settings.BaseURI_XSL can be used to specify the location the included stylesheet should be loaded from.

Images

The following properties on the Settings effect retrieving images specified using the external-graphic element.

PropertyTypeDefaultNotes
BaseURI_XMLstring This value sets the base URI for including images and other XML files. When an external-graphic element specifies a relative path, Settings.BaseURI_XML is the base URI used in accordance with the rfc2396 URI Specification. When an XML file uses an entity to include another XML file, Settings.BaseURI_XML is the base URI used when Ibex searches for the included XML file.
WebRequestTimeoutMsint300 When an external-graphic element specifies an image is retrieved from a web server, this is the timeout used for the call to the web server. Units are milliseconds.

Border widths

The following properties on the Settings change the values for border widths specified with constants like 'thin'.

PropertyTypeDefaultNotes
BorderWidthThinstring1pt
BorderWidthMediumstring2pt
BorderWidthThickstring3pt

Layout

The following properties on the Settings change the appearance of content in the PDF file.

PropertyTypeDefaultNotes
OverflowIsVisiblebooltrue By default a region has overflow='auto', leaving it up the Ibex to decide whether content which overflows the bottom edge of a region is displayed or discarded.
If Settings.OverflowIsVisible is true, the content will be displayed, if false it will be discarded. This property applies only if the attribute 'overflow' is not set or is set to 'auto'.

Leaders

The following properties on the Settings change the values for leader formatting objects.

PropertyTypeDefaultNotes
LeaderDotchar. When leader-pattern='dots', this is the character used as the dot

Extensions

This chapter details Ibex-specific extensions to XSL-FO. Typically these extensions implement functionality which is not part of the XSL-FO standard such as password protecting a document .

The Ibex extensions have a namespace which is specified using the xmlns attribute as shown in Figure 22-1.

Document security

Ibex supports encryption of PDF documents and the setting of various document permissions. This is done using the ibex:security element as shown in Figure 22-1.

<root xmlns="http://www.w3.org/1999/XSL/Format" 
	xmlns:ibex="http://www.xmlpdf.com/2003/ibex/Format">	

<ibex:security deny-print='true' deny-extract='true' 
	deny-modify='true' user-password='user' owner-password='owner'/>

...

Figure 22-1: FO using the ibex:security element

Two levels of encryption are available, 40 bit and 128 bit. When using 40 bit encryption available permissions which can be set including deny-print, deny-extract and deny-modify. When using 128 bit encyption additional permissions can be set including deny-assembly and deny-print-high-resolution. These options are details in the sections below.

The level of encryption is specified using the bits attribute of the ibex:security element. This defaults to "40", so specify 128 bit encryption specify bits="128".

If used the ibex:security element must occur before any page-sequence elements.

40 bit encryption security options

When the number of bits of encryption is set to 40 or not specified, the attributes of the ibex:security element are:

AttributeValueMeaning
user-password Specifies a password required to open the document in Acrobat. Once the document is opened with the correct user password, access is limited to permissions given using the attributes below.
owner-password Specifies a password required to get all rights to the document in Acrobat. Once the document is opened with the correct owner password the user has total control of the document.
deny-printtrue
false
If this is set to true a user who opens the document with the user password will not be able to print the document.
deny-extracttrue
false
If this is set to true a user who opens the document with the user password will not be able to use cut-and-paste functionality to copy part of the document.
deny-modifytrue
false
If this is set to true a user who opens the document with the user password will not be able to modify the document.

Setting any of the attributes listed above will cause Ibex to encrypt the document.

Specifying the user-password but not the owner-password will set the owner-password to the same value as the user-password. This means anyone who can open the document using the user password has complete control of the document.

Specifying the owner-password but not the user-password is common usage. This means the user can open the document with limited rights without needing a password, but cannot then change or exceed those rights without knowing the owner password.

128 bit encryption security options

When the number of bits of encryption is set to 128, the attributes of the ibex:security element are:

AttributeValueMeaning
user-password Specifies a password required to open the document in Acrobat. Once the document is opened with the correct user password, access is limited to permissions given using the attributes below.
owner-password Specifies a password required to get all rights to the document in Acrobat. Once the document is opened with the correct owner password the user has total control of the document.
deny-printtrue
false
If this is set to true a user who opens the document with the user password will not be able to print the document.
deny-print-high-resolutiontrue
false
If this is set to true a user who opens the document with the user password will not be able to print a high resolution copy of the document. They will only be able to print a low resolution (150dpi) version. If deny-print="true" this attribute has no effect and the document cannot be printed.
deny-extracttrue
false
If this is set to true a user who opens the document with the user password will not be able to use cut-and-paste functionality to copy part of the document.
deny-modifytrue
false
If this is set to true a user who opens the document with the user password will not be able to modify the document but can still "assemble" it. See deny-assembly below.
deny-assemblytrue
false
If deny-modify="true" and deny-assembly="false" then the user cannot change the document, but can "assemble" it, which means insert, rotate or delete pages and create bookmarks or thumbnail images. Setting deny-modify="true" and deny-assembly="true" prevents assembly.

Setting any of the attributes listed above will cause Ibex to encrypt the document.

Specifying the user-password but not the owner-password will set the owner-password to the same value as the user-password. This means anyone who can open the document using the user password has complete control of the document.

Specifying the owner-password but not the user-password is common usage. This means the user can open the document with limited rights without needing a password, but cannot then change or exceed those rights without knowing the owner password.

Standard document properties

Ibex allows you to set the various properties associated with a PDF document. These properties can be viewed in Acrobat by using the File | Document Properties | Summary menu option or just pressing control-d.

Figure 22-2 shows FO for setting the document properties using the ibex:properties element.

<fo:root xmlns="http://www.w3.org/1999/XSL/Format" xmlns:ibex="http://www.xmlpdf.com/2003/ibex/Format">	

<ibex:properties 
     title="Ibex User Manual"  subject="Ibex" 
     author="visual programming limited" 
     keywords="xml,pdf"	creator="xtransform" />
...

Figure 22-2: FO using ibex:properties

If used the ibex:security element must occur before any page-sequence elements.

The attributes of the ibex:properties element are:

AttributeValueMeaning
title Specifies a string which becomes the title property of the document.
subject Specifies a string which becomes the subject property of the document.
author Specifies a string which becomes the author property of the document.
keywords Specifies a string which becomes the keywords property of the document. Separate individual keywords with commas.
creator Specifies a string which becomes the creator property of the document. This should be the name of the application which created the document from which the PDF file was created.
page-mode Specifies how Acrobat will display the document when it is first opened. If set to 'bookmarks' then if the document has bookmarks they will be displayed. If set to 'thumbs' then the thumbnails tab in Acrobat will be displayed. If set to 'fullscreen' the document will be displayed without any toolbar, border etc.

Following the PDF standard, the document creator property should be the name of the product which converted the content to PDF format, so this is always Ibex. Other document properties such as creation and modification date are populated automatically by Ibex.

Custom Document Properties

Acrobat supports the display and editing of custom document properties. These properties are a set of name value pairs stored within the PDF file. In Acrobat 6.0 these properties can be viewed by using the File | Document Properties menu option and clicking on the "Custom" entry in the list box to display a screen like this:

These custom properties are inserted into the PDF using the ibex:custom element as shown in Figure 22-3.

<fo:root xmlns="http://www.w3.org/1999/XSL/Format" xmlns:ibex="http://www.xmlpdf.com/2003/ibex/Format">	

<ibex:properties title="Ibex User Manual">
    <ibex:custom name="favourite color" value="blue"/>
</ibex:properties>
...

Figure 22-3: FO using the ibex:custom element

Each property must have a name and value attribute.

Image processing

Image resolution

Ibex adds the dpi attribute to the external-graphic element to permit managing the dots per inch resolution of images. See Image resolution on page image-resolution.

Anti-aliasing

Ibex adds the ibex:anti-alias attribute to the external-graphic element to permit disabling anti-aliasing in order to achieve clearer images. See Image anti-aliasing on page image-anti-aliasing.

Multi-page TIFF image processing

Ibex adds the ibex:page attribute to the external-graphic element to specify which page of a muti-page TIFF image should be included in the PDF file. See Multi-page TIFF images on page image-multi-page-tif.

Bookmarks

XSL-FO 1.0 had no support for creating bookmarks in the PDF file. XSL 1.1 now has this feature so the ibex:bookmark element is no longer supported.

The XSL 1.1 implementation of bookmarks is described on page bookmarks.

Document base URL

The PDF format supports setting a base URL for links created with a basic-link element. This base URL is prepended to the destination specified with an external-destination attribute if (and only if) the specified destination does not start with a '/' character.

Figure 22-4 shows FO which creates a document with "http://www.xmlpdf.com" as the base URL and a link to the page "index.html". When the user clicks on the link in the PDF file, it will go to "http://www.xmlpdf.com/index.html".

<ibex:document-base-url value="http://www.xmlpdf.com"/>
..
<fo:block>
   <fo:basic-link external-destination='url(index.html)'>
      index.html
   </fo:basic-link>
</fo:block>

Figure 22-4: FO setting the document base URL

The base URL is a document-wide property and can be set only once.

This property should not be confused with the Settings.BaseURI value which specifies a base URI to be used when Ibex retrieves images, stylesheets and XML during creation of the PDF file.

Ibex version

The ibex:version element inserts the version number of Ibex used to create the PDF file. This is an inline element which inserts characters into the document. Figure 22-5 shows FO which uses this element.

<fo:block xmlns:ibex="http://www.xmlpdf.com/2003/ibex/Format">
  created with Ibex version <ibex:version/>
</fo:block>

Figure 22-5: FO using ibex:version

PDF/X

Ibex can create PDF files which comply with the PDF/X standard. This is described in detail on page pdf-x.

Viewer Preferences

Ibex can set flags on the PDF file which control how the viewer application, such as Acrobat Reader, will display the PDF file.

These flags are set using the ibex:viewer-preferences element as shown in Figure 22-6.

<fo:root xmlns="http://www.w3.org/1999/XSL/Format" xmlns:ibex="http://www.xmlpdf.com/2003/ibex/Format">	

<ibex:viewer-preferences hide-toolbar="true"/>
...

Figure 22-6: FO using the ibex:viewer-preferences element

The attributes for the ibex:viewer-preferences element are:

AttributeValueMeaning
hide-toolbartrue
false
Set to true to hide the viewer application's tool bars
hide-menubartrue
false
Set to true to hide the viewer application's menu bar
hide-window-uitrue
false
Set to true to hide the UI and just display the document content
fit-windowtrue
false
Set to true to resize the viewer window to fit the document page size
center-windowtrue
false
Set to true to center the viewer window on the screen
display-doc-titletrue
false
Set to true to have the viewer display the document title in the viewer frame rather than the file name. The document title is set using the title attribute of the ibex:properties element as detailed on page document-properties.

PDF/X

This chapter details Ibex-specific extensions to the XSL-FO XML to support creation of PDF files which conform to the PDF/X standard.

Ibex implements the PDF/X standard using the ibex:pfdx element as shown in Figure 23-1.

<fo:root xmlns="http://www.w3.org/1999/XSL/Format" 
	xmlns:ibex="http://www.xmlpdf.com/2003/ibex/Format">	

<ibex:pdfx color-profile-file-name="WideGamutRGB.icc"/>

...

Figure 23-1: PDF/X

The Ibex extensions have a namespace which is specified using the xmlns attribute as shown above.

The ibex:pdfx element must occur before any output is generated.

Using the ibex:pdfx element will automatically set the document color space to CMYK.

The existence of the ibex:pdfx element causes Ibex to create a PDF/X compatible PDF file. The field Settings.PDFXMode used in earlier releases has been removed.

The attributes of the ibex:pdfx element are:

AttributeValueMeaning
color-profile-file-name Full or relative path to a ICC color profile file
registry-name Registry Name used in the PDF OutputIntents structure. If not specified this defaults to "http://www.color.org".
info Optional text which will become the Info value in the first OutputIntents array entry.
output-condition-identifier Optional text which will become the OutputConditionIdentifier value in the first OutputIntents array entry. This defaults to "Custom"
output-condition Optional text which will become the OutputCondition value in the first OutputIntents array entry. This defaults to "Custom". Acrobat proposes values such as "TR001 SWOP/CGATS".

The color profiles is read from the specified ICC file, compressed, and embedded in the PDF file.

Media box

The MediaBox size within the PDF file will be set to the size of the page as specified on the simple-page-master for that page.

Bleed box

The BleedBox size defaults to the MediaBox size. The BleedBox can be specified as a change from the MediaBox by specifying the ibex:bleed-width attribute on the simple-page-master. This attribute specifies the distance by which the BleedBox is smaller than the MediaBox as shown in Figure 23-2.

<fo:simple-page-master page-height="313mm" page-width="226mm" master-name="page" ibex:bleed-width="3mm">

Figure 23-2: Setting the bleed box size

If one value is used it applies to all sides of the page, if two values are used the top and bottom edges use the first value and the left and right edges use the second. If there are three values the top is set to the first value, the sides are set to the second value, and the bottom is set to the third value. If there are four values, they apply to the top, right, bottom and left edges in that order.

The following attributes can be specified to set each side explicitly: bleed-top-width, bleed-bottom-width, bleed-right-width, bleed-left-width.

Trim box

The TrimBox size defaults to the BleedBox size. The TrimBox can be specified as a change from the BleedBox by specifying the ibex:trim-width attribute on the simple-page-master. This attribute specifies the distance by which the TrimBox is smaller than the BleedBox as shown in Figure 23-3.

<fo:simple-page-master page-height="313mm" page-width="226mm" master-name="page" ibex:trim-width="3mm">

Figure 23-3: Setting the trim box size

If one value is used it applies to all sides of the page, if two values are used the top and bottom edges use the first value and the left and right edges use the second. If there are three values the top is set to the first value, the sides are set to the second value, and the bottom is set to the third value. If there are four values, they apply to the top, right, bottom and left edges in that order.

The following attributes can be specified to set each side explicitly: trim-top-width, trim-bottom-width, trim-right-width, trim-left-width.

Overprint

Overprint mode can be enabled for the entire page by specifying the ibex:ibex-overprint-stroking, ibex:overprint-nonstroking and ibex:overprint-mode attributes as shown in Figure 23-4.

<fo:simple-page-master page-height="313mm" page-width="226mm" master-name="page" 
	ibex:overprint-stroking="true" 
    ibex:overprint-nonstroking="true" ibex:overprint-mode="1">

Figure 23-4: Setting the overprint mode

Elements and Attributes

This chapter describes each major formatting object and its usage.

Declarations and pagination and layout formatting objects

The objects described in this section are used to define the geometry of the page and to control which content appears where on the page.

fo:root

This is the top level element in the FO and contains the fo:layout-master-set, an optional fo:declarations and one or more fo:page-sequence elements. These child elements must be in the order listed.

fo:bookmark-tree   (zero or one)

fo:declarations   (zero or one)

fo:layout-master-set   (exactly one)

fo:page-sequence   (zero or more)

fo:page-sequence-wrapper   (zero or more)

For an example showing the use of the element see Figure 24-1.

<fo:?xml version='1.0' encoding='UTF-8'?>
<fo:root xmlns="http://www.w3.org/1999/XSL/Format">
   <fo:layout-master-set>
      <fo:simple-page-master master-name="simple">
         <fo:region-body margin="2.5cm" region-name="body"  background-color='#eeeeee'/>
      <fo:/simple-page-master>
   <fo:/layout-master-set>

   <fo:page-sequence master-reference="simple">
      <fo:flow flow-name="body">
         <fo:block>Hello World<fo:/block>
      <fo:/flow>
   <fo:/page-sequence>
<fo:/root>

Figure 24-1: Using root

fo:declarations

The declarations formatting object is used to group global declarations for a stylesheet. In Ibex it acts as a container for the fo:color-profile element which is used in PDF/X files. See pdf-x for more information.

fo:color-profile  

fo:root

fo:color-profile

This element is used to specify an external color profile file used in the creation of PDF/X files.

See pdf-x for more information.

fo:declarations

fo:page-sequence

This element contains content for one or more pages. The content is contained in fo:static-content elements which hold content for the page header, footer and other regions, and a one or more fo:flow elements which contains content to be placed in the body regions of the page.

The page-sequence has a master-reference attribute which should correspond to the master-name of an element contained within the documents fo:layout-master-set, such as a fo:single-page-master.

The page number for the first page created by this page sequence can be set using the initial-page-number attribute. The format of the page number is controlled using the format attribute.

fo:flow   (one or more)

fo:folio-prefix   (zero or more)

fo:folio-suffix   (zero or more)

fo:static-content   (zero or more)

fo:title   (zero or more)

fo:root

fo:page-sequence-wrapper

For an example showing the use of the element see Figure 24-1.

fo:page-sequence-wrapper

This element is used to specify attributes which can be inherited by a group of page-sequence elements which are contained in the page-sequence-wrapper.

fo:page-sequence   (zero or more)

fo:page-sequence-wrapper   (zero or more)

fo:root

fo:page-sequence-wrapper

For an example showing the use of the element see Figure 24-2.

<fo:?xml version='1.0' encoding='UTF-8'?>
<fo:root xmlns="http://www.w3.org/1999/XSL/Format">
   <fo:layout-master-set>
      <fo:simple-page-master master-name="simple">
         <fo:region-body margin="2.5cm" region-name="body"
            background-color='#eeeeee'/>
      <fo:/simple-page-master>
   <fo:/layout-master-set>

   <fo:page-sequence-wrapper index-key="main">
     <fo:page-sequence master-reference="simple">
        <fo:flow flow-name="body">
           <fo:block>Hello World<fo:/block>
        <fo:/flow>
     <fo:/page-sequence>
   <fo:/page-sequence-wrapper>
<fo:/root>

Figure 24-2: Using page-sequence-wrapper

fo:layout-master-set

This element contains all the page master elements (fo:simple-page-master, fo:page-sequence-master) used to create individual pages or sequence of pages.

At least one child element must exist or the document will contain no pages.

fo:flow-map   (zero or more)

fo:page-sequence-master   (zero or more)

fo:simple-page-master   (zero or more)

fo:root

For an example showing the use of the element see Figure 24-1.

fo:page-sequence-master

This element is used to define the sequence in which one or more page master elements (fo:simple-page-master, fo:repeatable-page-master) are used to create pages.

The element describes a sequence of page layouts and has a master-name which uniquely identifies it. This master-name is used as the master-reference on a fo:page-sequence element in order to create pages using the sequence described by this page-sequence-master.

Each child of this element specifies a sequence of one or more pages:

A fo:single-page-master-reference element is used define the layout for one page.

A fo:repeatable-page-master-reference element is used define multiple pages which have the same layout because they use the same page master.

A fo:repeatable-page-master-alternatives element is used define multiple pages which can have different layouts created using different page master elements.

fo:repeatable-page-master-alternatives   (zero or more)

fo:repeatable-page-master-reference   (zero or more)

fo:single-page-master-reference   (zero or more)

fo:layout-master-set

For an example showing the use of the element see Figure 24-3.

<fo:?xml version='1.0' encoding='UTF-8'?>
<fo:root xmlns="http://www.w3.org/1999/XSL/Format">
   <fo:layout-master-set>
      <fo:simple-page-master master-name="simple">
         <fo:region-body margin="2.5cm" region-name="body"
            background-color='#eeeeee'/>
      <fo:/simple-page-master>
      <fo:page-sequence-master master-name='repeated'>
          <fo:repeatable-page-master-reference
             master-reference='simple'/>
      <fo:/page-sequence-master>
   <fo:/layout-master-set>

   <fo:page-sequence master-reference="repeated">
      <fo:flow flow-name="body">
         <fo:block>Hello World<fo:/block>
      <fo:/flow>
   <fo:/page-sequence>
<fo:/root>

Figure 24-3: Using page-sequence-master

fo:single-page-master-reference

This element specifies that the fo:simple-page-master which has a master-name corresponding to the master-reference of this element should be used to define the layout for a single page.

This element must be empty.

fo:page-sequence-master

For an example showing the use of the element see Figure 24-1.

fo:repeatable-page-master-reference

This element specifies that the fo:simple-page-master which has a master-name corresponding to the master-reference of this element should be used to define the layout of one or more pages.

The difference between this and a fo:single-page-master-reference is that the single-page-master-reference produces one page whereas this element can produce multiple pages. The maximum number of pages created by this element is controlled by the maximum-repeats attribute which by default is unlimited.

This element must be empty.

fo:page-sequence-master

For an example showing the use of the element see Figure 24-3.

fo:repeatable-page-master-alternatives

This element contains a set of fo:conditional-page-master-reference elements, each of which specifies a page master and some conditional information.

When the rendering of content from a fo:flow element triggers the creation of a new page each fo:conditional-page-master-reference contained in this element is evaluated to see if it should be used.

Typically the fo:conditional-page-master-reference elements are used to specify different page layouts for the first page of a sequence or for odd and even pages. The Ibex manual uses this approach, so that the first page of each chapter has no header.

fo:conditional-page-master-reference   (one or more)

fo:page-sequence-master

For an example showing the use of the element see Figure 24-4.

<fo:page-sequence-master master-name='chapter'>
 <fo:repeatable-page-master-alternatives>
   <fo:conditional-page-master-reference 
       page-position="first"
       master-reference='chapter-odd-no-header'/>
     
   <fo:conditional-page-master-reference 
        odd-or-even='odd'
        master-reference='chapter-odd'/>
             
   <fo:conditional-page-master-reference 
        odd-or-even='even'
        master-reference='chapter-even'/>
   <fo:/repeatable-page-master-alternatives>
<fo:/page-sequence-master>

Figure 24-4: Using repeatable-page-master-alternatives

fo:conditional-page-master-reference

This element associates a page master and a condition such that the page master will be used when the condition is true.

The conditions which are associated with this element are page-position, odd-or-even, and blank-or-not-blank. Each condition on each fo:conditional-page-master-reference in a fo:repeatable-page-master-alternatives element is evaluated in turn until one is found which is true, and that conditional-page-master-reference is used.

This element must be empty.

fo:repeatable-page-master-alternatives

For an example showing the use of the element see Figure 24-4.

fo:simple-page-master

This element defines the layout of a single page. It is uniquely identified by its master-name which is used on fo:page-sequence and other elements to create pages which use this layout.

The content of the page goes into the named regions which are specified by the child elements of this element.

The size of the page is defined using the page-height and page-width attributes. The default page size is A4.

fo:region-after   (zero or one)

fo:region-before   (zero or one)

fo:region-body   (one or more)

fo:region-end   (zero or one)

fo:region-start   (zero or one)

fo:layout-master-set

For an example showing the use of the element see Figure 24-1.

fo:region-body

This element defines the shape of the main area on the page into which content from fo:flow elements will be placed.

The region has a default name of "xsl-region-body" which is usually changed to something simpler using the region-name attribute.

A page can be defined which has multiple columns by using the column-count and column-gap attributes on this region.

Within the region all of the content can be aligned to the top, bottom or middle of the region using the display-align attribute.

Ibex supports multiple body regions. There can be any number of body regions, provided each has a unique region-name. Content from different flows is mapped to different regions using the fo:flow-map element.

The content of the region can be rotated using the reference-orientation attribute.

This element must be empty.

fo:simple-page-master

For an example showing the use of the element see Figure 24-5.

<fo:simple-page-master master-name="front-page" margin='1.5cm' 
     page-height="297mm" page-width="210mm">
  <fo:region-body region-name="body" 
         margin='0.75cm 0.5cm 0.75cm 3cm'/>
  <fo:region-before region-name="header" extent="2.5cm"/>
  <fo:region-after region-name="footer" extent="1cm"/>
  <fo:region-start extent='1cm' background-color='#eeeeee'/>
  <fo:region-end extent='1cm' background-color='#eeeeee'/>
<fo:/simple-page-master>

Figure 24-5: Using regions

fo:region-before

This element defines the shape of a region which is at the top of a non-rotated page. Content from fo:static-content elements whose flow-name matches the region-name will be placed in this region.

The region has a default name of "xsl-region-before" which is usually changed to something simpler such as "header" using the region-name attribute.

Within the region all of the content can be aligned to the top, bottom or middle of the region using the display-align attribute.

The content of the region can be rotated using the reference-orientation attribute.

Unlike the fo:region-body element the region-before does not have margin properties. The size of the region is defined using the extent attribute.

By default the before region is reduced in width by the presence of the fo:region-start and fo:region-end elements. This can be changed by setting the precedence attribute to "true".

This element must be empty.

fo:simple-page-master

For an example showing the use of the element see Figure 24-5.

fo:region-after

This element defines the shape of a region which is at the bottom of a non-rotated page. Content from fo:static-content elements whose flow-name matches the region-name will be placed in this region.

The region has a default name of "xsl-region-after" which is usually changed to something simpler such as "footer" using the region-name attribute.

Within the region all of the content can be aligned to the top, bottom or middle of the region using the display-align attribute.

The content of the region can be rotated using the reference-orientation attribute.

Unlike the fo:region-body element the region-after does not have margin properties. The size of the region is defined using the extent attribute.

By default the before region is reduced in width by the presence of the fo:region-start and fo:region-end elements. This can be changed by setting the precedence attribute to "true".

This element must be empty.

fo:simple-page-master

For an example showing the use of the element see Figure 24-5.

fo:region-start

This element defines the shape of a region which is at the left of a non-rotated page. Content from fo:static-content elements whose flow-name matches the region-name will be placed in this region.

The region has a default name of "xsl-region-start" which is usually changed to something simpler such as "left" using the region-name attribute.

Within the region all of the content can be aligned to the top, bottom or middle of the region using the display-align attribute.

The content of the region can be rotated using the reference-orientation attribute.

Unlike the fo:region-body element the region-start does not have margin properties. The size of the region is defined using the extent attribute.

This element must be empty.

fo:simple-page-master

For an example showing the use of the element see Figure 24-5.

fo:region-end

This element defines the shape of a region which is at the right of a non-rotated page. Content from fo:static-content elements whose flow-name matches the region-name will be placed in this region.

The region has a default name of "xsl-region-start" which is usually changed to something simpler such as "right" using the region-name attribute.

Within the region all of the content can be aligned to the top, bottom or middle of the region using the display-align attribute.

The content of the region can be rotated using the reference-orientation attribute.

Unlike the fo:region-body element the region-end does not have margin properties. The size of the region is defined using the extent attribute.

This element must be empty.

fo:simple-page-master

For an example showing the use of the element see Figure 24-5.

fo:flow

This element contains block-level objects which create content which will appear in the body region of the page.

The flow-name attribute must correspond to a region-name used on the body region of the current page master for the content to be output. Which page master this is, is determined by the master-reference attribute of the containing fo:page-sequence. If the flow-name does not match the region-name the content will not appear.

fo:^%block   (one or more)

fo:page-sequence

fo:static-content

This element is used to create content in a region other then the body region. The term "static" refers to the fact that the content will go only on the current page, unlike the content of a fo:flow element that may extend to many pages.

Static content is commonly used for page headers and footers. The content is usually different on each page as the page number changes.

The flow-name attribute may correspond to a region-name used on a non-body region of the current page master. Which page master this corresponds to is determined by the master-reference attribute of the containing fo:page-sequence. If the flow-name does not match a region-name the content will not appear. This makes it possible to have a fo:page-sequence which contains many static content elements each matching a different page layout. Only the static content which matches a region which is on the current page layout will be displayed.

fo:block   (zero or more)

fo:block-container   (zero or more)

fo:float   (one or more, cannot be used inside an out-of-line element)

fo:index-range-begin   (one or more, subject to constraints specified for this element)

fo:index-range-end   (one or more, subject to constraints specified for this element)

fo:list-block   (zero or more)

fo:retrieve-marker   (one or more, subject to constraints specified for this element)

fo:table   (zero or more)

fo:table-and-caption   (zero or more)

fo:wrapper   (one or more, subject to constraints specified for this element)

fo:page-sequence

For an example showing the use of the element see .

fo:title

The title element associates a string title with a page sequence. This has no function when generating PDF so is discarded by Ibex.

text

fo:basic-link   (zero or more)

fo:bidi-override   (zero or more)

fo:character   (zero or more)

fo:external-graphic   (zero or more)

fo:float   (one or more, cannot be used inside an out-of-line element)

fo:footnote   (one or more, cannot be used inside an out-of-line element)

fo:index-page-citation-last   (zero or more)

fo:index-range-begin   (one or more, subject to constraints specified for this element)

fo:index-range-end   (one or more, subject to constraints specified for this element)

fo:inline   (zero or more)

fo:inline-container   (zero or more)

fo:instream-foreign-object   (zero or more)

fo:leader   (zero or more)

fo:page-number   (zero or more)

fo:page-number-citation   (zero or more)

fo:page-number-citation-last   (zero or more)

fo:retrieve-marker   (one or more, subject to constraints specified for this element)

fo:scaling-value-citation   (zero or more)

fo:wrapper   (one or more, subject to constraints specified for this element)

fo:page-sequence

fo:flow-map

The flow-map is used to specify the assignment of flows to regions. Using the fo:flow-map the content from one or more fo:flow elements can be assigned to appear in one or more regions. So content from one fo:flow can be rendered across multiple regions on the same page, filling one region then another.

fo:flow-map elements must have a unique flow-map-name value. This is referenced by the flow-map-reference attribute of an fo:page-sequence to assign the content of that fo:page-sequence using the named flow-map.

flow-maps were added to XSL-FO in version 1.1.

fo:flow-assignment   (zero or more)

fo:layout-master-set

For an example showing the use of the element see .

fo:flow-assignment

The fo:flow-assignment is used to assign a list of fo:flows to a list of regions.

fo:flow-source-list   (exactly one)

fo:flow-target-list   (exactly one)

fo:flow-map

For an example showing the use of the element see .

fo:flow-source-list

The fo:flow-source-list contains a list of fo:flow-name-specifier elements which specify the names of flows which will be assigned by the containing flow-map.

fo:flow-name-specifier   (one or more)

fo:flow-assignment

For an example showing the use of the element see .

fo:flow-name-specifier

The fo:flow-name-specifier has one attribute which specifies the name of a fo:flow. This is used in the fo:flow-map element to add the named fo:flow to a list of flows mapped to regions.

This element must be empty.

fo:flow-source-list

For an example showing the use of the element see .

fo:flow-target-list

The fo:flow-target-list contains a list of fo:region-name-specifier elements which specify the names of regions which will be assigned by the containing fo:flow-map.

fo:region-name-specifier   (one or more)

fo:flow-assignment

For an example showing the use of the element see .

fo:region-name-specifier

The fo:region-name-specifier has one attribute which specifies the name of a region. This is used in the fo:flow-map element to add the named region to a list of regions mapped to fo:flows.

This element must be empty.

fo:flow-target-list

For an example showing the use of the element see .

Block level formatting objects

The objects described in this section are used to contain text and other block-level and inline-level elements.

fo:block

This element is the main container for text content. The simplest block element looks like this:

<fo:block>this is text<fo:/block>
			

Figure 24-6:

The block is a block-level element. The other block-level elements are fo:table, fo:table-and-caption, fo:list-block, and fo:block-container.

A block element can contain other block-level elements as well as text. A typical usage would be to insert an empty block into a paragraph of text to cause a line break, like this:

<fo:block>this will be line 1<fo:/block>
<fo:block/>
<fo:block>this will be line 2<fo:/block>
			

Figure 24-7:

Another use of nested blocks is to keep two other block-level objects together by using the keep-together attribute on the previous block, like this:

<fo:block keep-together="always">
     <fo:block>this will be line 1<fo:/block>
     <fo:block>this will be line 2<fo:/block>
<fo:/block>
			

Figure 24-8:

To keep a block together and prevent it being split by a page break use the keep-together attribute.

To keep a block with the block following it use the keep-with-next attribute.

To keep a block with the block before it use the keep-with-previous attribute.

To format a block of text retaining line-feeds which were in the XML, use the linefeed-treatment attribute.

To change the color of text use the color attribute.

To align a paragraph to the left, right or both margins use the text-align and text-align-last attributes.

A block may contain a fo:retrieve-marker only if the block is inside a fo:static-content element.

fo:basic-link   (zero or more)

fo:bidi-override   (zero or more)

fo:block   (zero or more)

fo:block-container   (zero or more)

fo:character   (zero or more)

fo:external-graphic   (zero or more)

fo:float   (one or more, cannot be used inside an out-of-line element)

fo:footnote   (one or more, cannot be used inside an out-of-line element)

fo:index-page-citation-last   (zero or more)

fo:index-range-begin   (one or more, subject to constraints specified for this element)

fo:index-range-end   (one or more, subject to constraints specified for this element)

fo:inline   (zero or more)

fo:inline-container   (zero or more)

fo:instream-foreign-object   (zero or more)

fo:leader   (zero or more)

fo:list-block   (zero or more)

fo:page-number   (zero or more)

fo:page-number-citation   (zero or more)

fo:page-number-citation-last   (zero or more)

fo:PCDATA  

fo:retrieve-marker   (one or more, subject to constraints specified for this element)

fo:scaling-value-citation   (zero or more)

fo:table   (zero or more)

fo:table-and-caption   (zero or more)

fo:wrapper   (one or more, subject to constraints specified for this element)

fo:wrapper

fo:basic-link

fo:float

fo:footnote-body

fo:static-content

fo:table-caption

fo:block

fo:block-container

fo:inline

fo:inline-container

fo:bidi-override

fo:table-cell

fo:list-item-label

fo:list-item-body

fo:marker

For an example showing the use of the element see Figure 24-1.

fo:block-container

This element is used to create an area (a "reference area" in the specifications terms) that has a different writing direction or rotation. If you want to achieve other ends such as keeping two blocks together use a fo:block as the container.

If you do use reference-orientation to rotate the content to be vertical on the page then you need to specify inline-progression-dimension to limit the vertical height of the content.

The block-container element can be used to position content in a location relative to the page or to another block-container by setting the absolute-position attribute. See absolute-positioning for more information.

fo:block   (zero or more)

fo:block-container   (zero or more)

fo:float   (one or more, cannot be used inside an out-of-line element)

fo:index-range-begin   (one or more, subject to constraints specified for this element)

fo:index-range-end   (one or more, subject to constraints specified for this element)

fo:list-block   (zero or more)

fo:retrieve-marker   (one or more, subject to constraints specified for this element)

fo:table   (zero or more)

fo:table-and-caption   (zero or more)

fo:wrapper   (one or more, subject to constraints specified for this element)

fo:wrapper

fo:basic-link

fo:float

fo:footnote-body

fo:static-content

fo:table-caption

fo:block

fo:block-container

fo:inline

fo:inline-container

fo:bidi-override

fo:table-cell

fo:list-item-label

fo:list-item-body

fo:marker

For an example showing the use of the element see .

Inline level formatting objects

The objects described in this section are used directly contain and format text and other inline elements which are usually formatted across the page.

fo:bidi-override

This element is used when the Unicode BIDI algorithm fails to force some text to be written in a specific writing direction.

text

fo:basic-link   (zero or more)

fo:bidi-override   (zero or more)

fo:block   (zero or more)

fo:block-container   (zero or more)

fo:character   (zero or more)

fo:external-graphic   (zero or more)

fo:float   (one or more, cannot be used inside an out-of-line element)

fo:footnote   (one or more, cannot be used inside an out-of-line element)

fo:index-page-citation-last   (zero or more)

fo:index-range-begin   (one or more, subject to constraints specified for this element)

fo:index-range-end   (one or more, subject to constraints specified for this element)

fo:inline   (zero or more)

fo:inline-container   (zero or more)

fo:instream-foreign-object   (zero or more)

fo:leader   (zero or more)

fo:list-block   (zero or more)

fo:page-number   (zero or more)

fo:page-number-citation   (zero or more)

fo:page-number-citation-last   (zero or more)

fo:retrieve-marker   (one or more, subject to constraints specified for this element)

fo:scaling-value-citation   (zero or more)

fo:table   (zero or more)

fo:table-and-caption   (zero or more)

fo:wrapper   (one or more, subject to constraints specified for this element)

fo:index-page-citation-range-separator

fo:index-page-citation-list-separator

fo:index-page-number-prefix

fo:index-page-number-suffix

fo:wrapper

fo:basic-link

fo:title

fo:block

fo:inline

fo:folio-suffix

fo:folio-prefix

fo:bidi-override

fo:marker

fo:character

This element is used to insert a single character into the content. Given that modern XML editors can insert all Unicode characters there is little requirement to use this element.

This element must be empty.

fo:index-page-citation-range-separator

fo:index-page-citation-list-separator

fo:index-page-number-prefix

fo:index-page-number-suffix

fo:wrapper

fo:basic-link

fo:title

fo:block

fo:inline

fo:folio-suffix

fo:folio-prefix

fo:bidi-override

fo:marker

fo:initial-property-set

This element is used to format the first line of a block. It does not create any areas but its attributes are applied to the first line in the block which contains the initial-property-set.

Ibex does not currently implement this functionality

This element must be empty.

For an example showing the use of the element see .

fo:external-graphic

This element is used to include an image into the document.

This is an inline element so it must be contained in a fo:block element.

The image source is defined by the src attribute.

The src attribute is called a uri-specification and must follow the following rules:

A sequence of characters that is "url(", followed by optional white space, followed by an optional single quote (") or double quote (") character, followed by a URI reference as defined in [RFC2396], followed by an optional single quote (") or double quote (") character, followed by optional white space, followed by ")". The two quote characters must be the same and must both be present or both be absent. If the URI reference contains a single quote, the two quote characters must be present and be double quotes.

This means the following are all valid values for the src attribute:

uri(ibex.jpg)

uri("ibex.jpg")

uri("ibex.jpg")

url(http://www.xmlpdf.com/images/download2.gif)

To set the size of the image use the content-height and content-width attributes.

This element must be empty.

fo:index-page-citation-range-separator

fo:index-page-citation-list-separator

fo:index-page-number-prefix

fo:index-page-number-suffix

fo:wrapper

fo:basic-link

fo:title

fo:block

fo:inline

fo:folio-suffix

fo:folio-prefix

fo:bidi-override

fo:marker

For an example showing the use of the element see .

fo:instream-foreign-object

This element is used to place an object which is contained in the XML into the PDF document. The only supported object type is an SVG image.

An example of include an inline SVG image is:

<fo:instream-foreign-object width="20%" height="1cm">
    <fo:svg xmlns:fo="http://www.w3.org/TR/xsl/Format" 
                xmlns="http://www.w3.org/2000/svg">
         <fo:path style="stroke-width:1;fill:rgb(246,127,0);" 
              d="M204.33 139.83 C196.33 133.33 z" />
    <fo:/svg>
<fo:/instream-foreign-object>
	

Figure 24-9:

Not all implementations of Ibex support SVG images.

This element must be empty.

fo:index-page-citation-range-separator

fo:index-page-citation-list-separator

fo:index-page-number-prefix

fo:index-page-number-suffix

fo:wrapper

fo:basic-link

fo:title

fo:block

fo:inline

fo:folio-suffix

fo:folio-prefix

fo:bidi-override

fo:marker

fo:inline

This element is used to format some text in a way which is different to the containing fo:block such as giving it a different font.

text

fo:basic-link   (zero or more)

fo:bidi-override   (zero or more)

fo:block   (zero or more)

fo:block-container   (zero or more)

fo:character   (zero or more)

fo:external-graphic   (zero or more)

fo:float   (one or more, cannot be used inside an out-of-line element)

fo:footnote   (one or more, cannot be used inside an out-of-line element)

fo:index-page-citation-last   (zero or more)

fo:index-range-begin   (one or more, subject to constraints specified for this element)

fo:index-range-end   (one or more, subject to constraints specified for this element)

fo:inline   (zero or more)

fo:inline-container   (zero or more)

fo:instream-foreign-object   (zero or more)

fo:leader   (zero or more)

fo:list-block   (zero or more)

fo:page-number   (zero or more)

fo:page-number-citation   (zero or more)

fo:page-number-citation-last   (zero or more)

fo:retrieve-marker   (one or more, subject to constraints specified for this element)

fo:scaling-value-citation   (zero or more)

fo:table   (zero or more)

fo:table-and-caption   (zero or more)

fo:wrapper   (one or more, subject to constraints specified for this element)

fo:index-page-citation-range-separator

fo:index-page-citation-list-separator

fo:index-page-number-prefix

fo:index-page-number-suffix

fo:wrapper

fo:basic-link

fo:title

fo:footnote

fo:block

fo:inline

fo:folio-suffix

fo:folio-prefix

fo:bidi-override

fo:marker

For an example showing the use of the element see .

fo:inline-container

This element is used create an inline reference area. Because it can contain block-level elements it can be used to place a block-level element such as a table into a line of text. This can be used to horizontally center the block-level element by centering the inline-container, which being an inline element can be centered using normal text alignment attributes.

fo:block   (zero or more)

fo:block-container   (zero or more)

fo:float   (one or more, cannot be used inside an out-of-line element)

fo:index-range-begin   (one or more, subject to constraints specified for this element)

fo:index-range-end   (one or more, subject to constraints specified for this element)

fo:list-block   (zero or more)

fo:retrieve-marker   (one or more, subject to constraints specified for this element)

fo:table   (zero or more)

fo:table-and-caption   (zero or more)

fo:wrapper   (one or more, subject to constraints specified for this element)

fo:index-page-citation-range-separator

fo:index-page-citation-list-separator

fo:index-page-number-prefix

fo:index-page-number-suffix

fo:wrapper

fo:basic-link

fo:title

fo:block

fo:inline

fo:folio-suffix

fo:folio-prefix

fo:bidi-override

fo:marker

fo:leader

This element is used to draw a horizontal line across the page.

A simple line is drawn like this:

<fo:block>
  <fo:leader leader-pattern="rule" rule-thickness="0.2pt"/>
<fo:/block>
		

Figure 24-10:

The leader can also be drawn between other pieces of text on the same line and can be set to expand to fill available space like this:

<fo:block text-align="justify" text-align-last="justify">
 This is before the leader
  <fo:leader leader-pattern="rule" rule-thickness="0.2pt"/>
 this is after the leader
<fo:/block>
		

Figure 24-11:

producing the effect below. Note the use of text-align-last which is required to justify the single line paragraph.

This is before the leader this is after the leader

Setting the leader-pattern attribute to "dots" changes the line into dots like this:

This is before the leader this is after the leader

Setting the leader-pattern attribute to "space" changes the line into spaces like this:

This is before the leader this is after the leader

The use of leader-pattern = "use-content" is not supported.

fo:index-page-citation-range-separator

fo:index-page-citation-list-separator

fo:index-page-number-prefix

fo:index-page-number-suffix

fo:wrapper

fo:basic-link

fo:title

fo:block

fo:inline

fo:folio-suffix

fo:folio-prefix

fo:bidi-override

fo:marker

fo:page-number

This element is used to insert the current page number into the document.

The page-number string is formatted using the string conversion properties of the containing fo:page-sequence, namely format, grouping-separator, grouping-size, letter-value, country and language.

This element must be empty.

fo:index-page-citation-range-separator

fo:index-page-citation-list-separator

fo:index-page-number-prefix

fo:index-page-number-suffix

fo:wrapper

fo:basic-link

fo:title

fo:block

fo:inline

fo:folio-suffix

fo:folio-prefix

fo:bidi-override

fo:marker

For an example showing the use of the element see .

fo:page-number-citation

This element is used to insert the first page number on which the content created by some other element occurs.

The page-number string is formatted using the string conversion properties of the containing fo:page-sequence, namely format, grouping-separator, grouping-size, letter-value, country and language.

The page-number-citation has a ref-id attribute which should match the id attribute of the element whose page number we want to appear.

This element must be empty.

fo:index-page-citation-range-separator

fo:index-page-citation-list-separator

fo:index-page-number-prefix

fo:index-page-number-suffix

fo:wrapper

fo:basic-link

fo:title

fo:block

fo:inline

fo:folio-suffix

fo:folio-prefix

fo:bidi-override

fo:marker

For an example showing the use of the element see Figure 24-12.

<fo:?xml version='1.0' encoding='UTF-8'?>
<fo:root xmlns="http://www.w3.org/1999/XSL/Format">
   <fo:layout-master-set>
      <fo:simple-page-master master-name="simple">
         <fo:region-body margin="2.5cm" region-name="body"/>
      <fo:/simple-page-master>
   <fo:/layout-master-set>

  <fo:page-sequence master-reference="simple">
      <fo:flow flow-name="body">
         <fo:block id='22'>
         Hello 
         <fo:/block>
      <fo:/flow>
  <fo:/page-sequence>
  
  <fo:page-sequence master-reference="simple">
      <fo:flow flow-name="body">
         <fo:block>
         		The block with id='22' starts on page 
         		<fo:page-number-citation ref-id='22'/>
         		and ends on page
         		<fo:page-number-citation-last ref-id='22'/>
         <fo:/block>
      <fo:/flow>
  <fo:/page-sequence>
  
<fo:/root>

Figure 24-12: Example of page-number-citation

fo:page-number-citation-last

This element is used to insert the last page number on which the content created by some other element occurs.

The page-number string is formatted using the string conversion properties of the containing fo:page-sequence, namely format, grouping-separator, grouping-size, letter-value, country and language.

The page-number-citation-last has a ref-id attribute which should match the id attribute of the element whose page number we want to appear.

fo:index-page-citation-range-separator

fo:index-page-citation-list-separator

fo:index-page-number-prefix

fo:index-page-number-suffix

fo:wrapper

fo:basic-link

fo:title

fo:block

fo:inline

fo:folio-suffix

fo:folio-prefix

fo:bidi-override

fo:marker

For an example showing the use of the element see Figure 24-12.

fo:folio-prefix

This element is used create a prefix which appears before the page number (inserted by page-number, page-number-citation and page-number-citation-last).

text

fo:basic-link   (zero or more)

fo:bidi-override   (zero or more)

fo:character   (zero or more)

fo:external-graphic   (zero or more)

fo:float   (one or more, cannot be used inside an out-of-line element)

fo:footnote   (one or more, cannot be used inside an out-of-line element)

fo:index-page-citation-last   (zero or more)

fo:index-range-begin   (one or more, subject to constraints specified for this element)

fo:index-range-end   (one or more, subject to constraints specified for this element)

fo:inline   (zero or more)

fo:inline-container   (zero or more)

fo:instream-foreign-object   (zero or more)

fo:leader   (zero or more)

fo:page-number   (zero or more)

fo:page-number-citation   (zero or more)

fo:page-number-citation-last   (zero or more)

fo:retrieve-marker   (one or more, subject to constraints specified for this element)

fo:scaling-value-citation   (zero or more)

fo:wrapper   (one or more, subject to constraints specified for this element)

fo:page-sequence

fo:folio-suffix

This element is used create a suffix which appears after the page number (inserted by page-number, page-number-citation and page-number-citation-last).

text

fo:basic-link   (zero or more)

fo:bidi-override   (zero or more)

fo:character   (zero or more)

fo:external-graphic   (zero or more)

fo:float   (one or more, cannot be used inside an out-of-line element)

fo:footnote   (one or more, cannot be used inside an out-of-line element)

fo:index-page-citation-last   (zero or more)

fo:index-range-begin   (one or more, subject to constraints specified for this element)

fo:index-range-end   (one or more, subject to constraints specified for this element)

fo:inline   (zero or more)

fo:inline-container   (zero or more)

fo:instream-foreign-object   (zero or more)

fo:leader   (zero or more)

fo:page-number   (zero or more)

fo:page-number-citation   (zero or more)

fo:page-number-citation-last   (zero or more)

fo:retrieve-marker   (one or more, subject to constraints specified for this element)

fo:scaling-value-citation   (zero or more)

fo:wrapper   (one or more, subject to constraints specified for this element)

fo:page-sequence

fo:scaling-value-citation

This element is used to retrieve the amount by which an image was scaled when it was inserted into the PDF file.

The image should be identified with an id attribute which has the same value as the ref-id attribute on this element.

This element must be empty.

fo:index-page-citation-range-separator

fo:index-page-citation-list-separator

fo:index-page-number-prefix

fo:index-page-number-suffix

fo:wrapper

fo:basic-link

fo:title

fo:block

fo:inline

fo:folio-suffix

fo:folio-prefix

fo:bidi-override

fo:marker

Formatting objects for tables

The objects described in this section are used to create tables.

fo:table-and-caption

This element is used to create a table which has a caption above or below it, and to keep the table and caption together.

By default the caption appears above the table. Set caption-side="bottom" to make the caption appear below the table.

fo:table   (zero or more)

fo:table-caption   (zero or one)

fo:wrapper

fo:basic-link

fo:float

fo:footnote-body

fo:static-content

fo:table-caption

fo:block

fo:block-container

fo:inline

fo:inline-container

fo:bidi-override

fo:table-cell

fo:list-item-label

fo:list-item-body

fo:marker

fo:table

This element creates a table. Tables have rows and columns and possibly also headers and footers.

The size of table columns can either be calculated from the content of cells, or specified using fo:table-column elements. Using table-column elements results in consistent output regardless of cell contents.

The width and other characteristics of columns are defined using fo:table-column elements. An optional table header, which by default is repeated after each page break, is specified using the fo:table-header element. An optional table footer, which by default is repeated before each page break, is specified using the fo:table-footer element.

Table rows are contained in one or more fo:table-body elements.

Table borders are controlled using the border-collapse attribute. If this has a value of "collapse" then table and cell borders are collapsed into a single border. If the value is "separate" then table, row and cell borders are all drawn separately, one inside the other.

The default value for border-collapse is "collapse". To create the kind of borders used in CSS where the cell borders appears inside the row and table borders set border-collapse to "separate".

fo:table-body   (one or more)

fo:table-column   (zero or more)

fo:table-footer   (zero or one)

fo:table-header   (zero or one)

fo:wrapper

fo:basic-link

fo:float

fo:footnote-body

fo:static-content

fo:table-and-caption

fo:table-caption

fo:block

fo:block-container

fo:inline

fo:inline-container

fo:bidi-override

fo:table-cell

fo:list-item-label

fo:list-item-body

fo:marker

fo:table-column

This element is used to specify characteristics for columns in a table such as the background color and the width.

A table would typically have multiple table-column elements looking something like this:

<fo:table>
    <fo:table-column column-width="20%"/>	
    <fo:table-column column-width="30%"/>	
    <fo:table-column column-width="50%"/>	
    <fo:table-body>
         <fo:table-row> 
              <fo:table-cell>col 1<fo:/table-cell>
              <fo:table-cell>col 2<fo:/table-cell>
              <fo:table-cell>col 3<fo:/table-cell>
         <fo:/table-row>
    <fo:/table-body>
<fo:/table>
		

Figure 24-13:

This defines a table with three columns. Implicitly the three table-column elements specify the width of columns one, two and three in that order. This can be made explicit using the column-number attribute like this:

<fo:table>
    <fo:table-column column-number="1" 
      column-width="20%"/>	
    <fo:table-column column-number="2" 
      column-width="30%"/>	
    <fo:table-column column-number="3" 
      column-width="50%"/>	
    <fo:table-body>
         <fo:table-row> 
              <fo:table-cell>col 1<fo:/table-cell>
              <fo:table-cell>col 2<fo:/table-cell>
              <fo:table-cell>col 3<fo:/table-cell>
         <fo:/table-row>
    <fo:/table-body>
<fo:/table>
		

Figure 24-14:

A single table-column can be used to set the width and other characteristics of multiple columns by using the columns-spanned attribute. In the example below the first table-column sets the width of the first two columns to 20% and the third column to 50%:

<fo:table>
    <fo:table-column columns-spanned="2" 
         column-width="20%"/>	
    <fo:table-column 
        column-width="50%"/>	
    <fo:table-body>
         <fo:table-row> 
              <fo:table-cell>col 1<fo:/table-cell>
              <fo:table-cell>col 2<fo:/table-cell>
              <fo:table-cell>col 3<fo:/table-cell>
         <fo:/table-row>
    <fo:/table-body>
<fo:/table>
		

Figure 24-15:

Percentage values used in the column-width attribute refer to the width of the table.

If table-column elements are not used all columns will be of equal width.

This element must be empty.

fo:table

fo:table-caption

This element is used to contain block-level formatting objects containing the caption for the table. It is used as part of a table-and-caption element.

fo:block   (zero or more)

fo:block-container   (zero or more)

fo:float   (one or more, cannot be used inside an out-of-line element)

fo:index-range-begin   (one or more, subject to constraints specified for this element)

fo:index-range-end   (one or more, subject to constraints specified for this element)

fo:list-block   (zero or more)

fo:retrieve-marker   (one or more, subject to constraints specified for this element)

fo:table   (zero or more)

fo:table-and-caption   (zero or more)

fo:wrapper   (one or more, subject to constraints specified for this element)

fo:table-and-caption

fo:table-header

This element creates a header which appears once at the top of the table and is then repeated after each page break. To prevent this repetition set table-omit-header-at-break to "true" on the containing table.

A table-header is itself a table and contains rows and cells in the same manner as fo:table element.

fo:table-cell   (zero or more)

fo:table-row   (zero or more)

fo:table

Notes on attributes

As described in section 6.7.6 of the XSL-FO specification, only the background properties from this set apply. If the value of border-collapse on the table is "collapse" or "collapse-with-precedence" the border properties also apply.

fo:table-footer

This element creates a footer which appears once at the bottom of the table and also before each page break. To prevent this repetition set table-omit-footer-at-break to "true" on the containing table.

A table-footer is itself a table and contains rows and cells in the same manner as fo:table element.

fo:table-cell   (zero or more)

fo:table-row   (zero or more)

fo:table

Notes on attributes

As described in section 6.7.7 of the XSL-FO specification, only the background properties from this set apply. If the value of border-collapse on the table is "collapse" or "collapse-with-precedence" the border properties also apply.

fo:table-body

This element is a container for fo:table-row and fo:table-cell elements. A single fo:table element can contain multiple table-body elements which are output in the order in which they appear in the XML.

fo:table-cell   (zero or more)

fo:table-row   (zero or more)

fo:table

Notes on attributes

As described in section 6.7.8 of the XSL-FO specification, only the background properties from this set apply. If the value of border-collapse on the table is "collapse" or "collapse-with-precedence" the border properties also apply.

fo:table-row

This element acts as a container for fo:table-cell elements.

Table row elements are not required. A table-body element can contain table-cell elements directly using the starts-row and ends-row attributes on the cells to determine where rows start and end.

The height of a row is by default the height of the tallest cell in the row. This can be overridden using the height or block-progression-dimension attributes. Use block-progression-dimension.minimum to set a minimum height, block-progression-dimension.maximum to set a maximum height.

Rows cannot have padding. This is stated in section 6.7.9 of the XSL-FO specification.

fo:table-cell   (one or more)

fo:table-header

fo:table-footer

fo:table-body

fo:table-cell

This element is a container for content in a cell within a table. Cell content is contained in block-level elements within the cell. A common error is to place text directly within the table-cell element, which results in the text being discarded.

A table-cell element can contain any number of block level elements.

Contents of a cell are aligned vertically using the display-align attribute.

To have a cell span mutiple columns use the number-columns-spanned attribute. To span multiple rows use the number-rows-spanned attribute.

fo:block   (zero or more)

fo:block-container   (zero or more)

fo:float   (one or more, cannot be used inside an out-of-line element)

fo:index-range-begin   (one or more, subject to constraints specified for this element)

fo:index-range-end   (one or more, subject to constraints specified for this element)

fo:list-block   (zero or more)

fo:retrieve-marker   (one or more, subject to constraints specified for this element)

fo:table   (zero or more)

fo:table-and-caption   (zero or more)

fo:wrapper   (one or more, subject to constraints specified for this element)

fo:table-header

fo:table-row

fo:table-footer

fo:table-body

Formatting objects for lists

The objects described in this section are used to create lists.

fo:list-block

This element is used to create a list, which is similar to a two column table.

A simple list looks like this:

 <fo:list-block provisional-distance-between-starts=".5cm" 
     provisional-label-separation="0.1cm">
    <fo:list-item>
       <fo:list-item-label end-indent="label-end()">
          <fo:block font="8pt arial">&#x25CF;<fo:/block>
       <fo:/list-item-label>
       <fo:list-item-body start-indent="body-start()">
            <fo:block>
                item one
            <fo:/block>
        <fo:/list-item-body>
   <fo:/list-item>
    <fo:list-item>
       <fo:list-item-label end-indent="label-end()">
          <fo:block font="8pt arial">&#x25CF;<fo:/block>
       <fo:/list-item-label>
       <fo:list-item-body start-indent="body-start()">
            <fo:block>
                item two
            <fo:/block>
        <fo:/list-item-body>
   <fo:/list-item>
<fo:/list-block>

Figure 24-16:

producing the following content:

item one item two

The list is rendered as two columns. The first column is called the label, the second is called the body.

The distance from the start of the label column to the start of the body column is set by the provisional-distance-between-starts attribute. The gap between the columns is set by the provisional-label-separation attribute. The width of the label column is therefore:

provisional-distance-between-starts 
  - provisional-label-separation
	

Figure 24-17:

Each item in the list is contained in a fo:list-item element. The list-item contains exactly one fo:list-item-label and fo:list-item-body element, with the fo:list-item-label coming first.

The fo:list-item-label should always have its end-indent attribute set to "label-end()" which is a function returning a value calculated from the provisional-distance-between-starts and provisional-label-separation attributes. If the end-indent is not so specified the label column will overlap the body column.

The fo:list-item-body should always have its start-indent attribute set to "body-start()" which is a function returning a value calculated from the provisional-distance-between-starts and provisional-label-separation attributes. If the start-indent is not so specified the label column will overlap the body column.

fo:list-item  

fo:wrapper

fo:basic-link

fo:float

fo:footnote-body

fo:static-content

fo:table-caption

fo:block

fo:block-container

fo:inline

fo:inline-container

fo:bidi-override

fo:table-cell

fo:list-item-label

fo:list-item-body

fo:marker

fo:list-item

This element contains the label and body of an entry in a list.

The height of the list-item will be the taller of the label and body items it contains.

fo:list-item-body   (exactly one)

fo:list-item-label   (exactly one)

fo:list-block

For an example showing the use of the element see .

fo:list-item-body

This element contains the body part of a list item.

The list-item-body contains block-level elements, it does not itself contain text.

fo:block   (zero or more)

fo:block-container   (zero or more)

fo:float   (one or more, cannot be used inside an out-of-line element)

fo:index-range-begin   (one or more, subject to constraints specified for this element)

fo:index-range-end   (one or more, subject to constraints specified for this element)

fo:list-block   (zero or more)

fo:retrieve-marker   (one or more, subject to constraints specified for this element)

fo:table   (zero or more)

fo:table-and-caption   (zero or more)

fo:wrapper   (one or more, subject to constraints specified for this element)

fo:list-item

For an example showing the use of the element see .

fo:list-item-label

This element contains the label part of a list item.

The list-item-label contains block-level elements, it does not itself contain text.

The fo:list-item-label should always have its end-indent attribute set to "label-end()" which is a function returning a value calculated from the provisional-distance-between-starts and provisional-label-separation attributes. If the end-indent is not so specified the label column will overlap the body column.

The fo:list-item-body should always have its start-indent attribute set to "body-start()" which is a function returning a value calculated from the provisional-distance-between-starts and provisional-label-separation attributes. If the start-indent is not so specified the label column will overlap the body column.

fo:block   (zero or more)

fo:block-container   (zero or more)

fo:float   (one or more, cannot be used inside an out-of-line element)

fo:index-range-begin   (one or more, subject to constraints specified for this element)

fo:index-range-end   (one or more, subject to constraints specified for this element)

fo:list-block   (zero or more)

fo:retrieve-marker   (one or more, subject to constraints specified for this element)

fo:table   (zero or more)

fo:table-and-caption   (zero or more)

fo:wrapper   (one or more, subject to constraints specified for this element)

fo:list-item

For an example showing the use of the element see .

Dynamic effects: link and multi formatting objects

The objects described in this section are used to create links and dynamic content. As most of the elements in this section relate to dynamic content, which is not applicable to PDF, only basic-link is implemented.

fo:basic-link

This element is used to create a link in the PDF document, either to an external URL or to another location in the document.

text

fo:basic-link   (zero or more)

fo:bidi-override   (zero or more)

fo:block   (zero or more)

fo:block-container   (zero or more)

fo:character   (zero or more)

fo:external-graphic   (zero or more)

fo:float   (one or more, cannot be used inside an out-of-line element)

fo:footnote   (one or more, cannot be used inside an out-of-line element)

fo:index-page-citation-last   (zero or more)

fo:index-range-begin   (one or more, subject to constraints specified for this element)

fo:index-range-end   (one or more, subject to constraints specified for this element)

fo:inline   (zero or more)

fo:inline-container   (zero or more)

fo:instream-foreign-object   (zero or more)

fo:leader   (zero or more)

fo:list-block   (zero or more)

fo:page-number   (zero or more)

fo:page-number-citation   (zero or more)

fo:page-number-citation-last   (zero or more)

fo:retrieve-marker   (one or more, subject to constraints specified for this element)

fo:scaling-value-citation   (zero or more)

fo:table   (zero or more)

fo:table-and-caption   (zero or more)

fo:wrapper   (one or more, subject to constraints specified for this element)

fo:index-page-citation-range-separator

fo:index-page-citation-list-separator

fo:index-page-number-prefix

fo:index-page-number-suffix

fo:wrapper

fo:basic-link

fo:title

fo:block

fo:inline

fo:folio-suffix

fo:folio-prefix

fo:bidi-override

fo:marker

Formatting objects for bookmarks

The objects described in this section are used to create bookmarks which link to parts of the document and appear in a tree structure.

fo:bookmark-tree

This is the top level element in a tree of bookmarks, used to create the bookmark entries displayed on the right side in a PDF viewer.

fo:bookmark   (zero or more)

fo:root

For an example showing the use of the element see Figure 24-18.

<fo:bookmark-tree>
  <fo:bookmark internal-destination="section-1">
    <fo:bookmark-title>Chapter 1<fo:/bookmark-title>
    <fo:bookmark internal-destination="section-1-1">
      <fo:bookmark-title>Section 1<fo:/bookmark-title>
    <fo:/bookmark>
    <fo:bookmark internal-destination="section-1-2">
      <fo:bookmark-title>Section 2<fo:/bookmark-title>
    <fo:/bookmark>
  <fo:/bookmark>
  <fo:bookmark internal-destination="section-2">
    <fo:bookmark-title>Chapter 2<fo:/bookmark-title>
    <fo:bookmark internal-destination="section-2-1">
      <fo:bookmark-title>Section 1<fo:/bookmark-title>
    <fo:/bookmark>
  <fo:/bookmark>
<fo:/bookmark-tree>
    

Figure 24-18: A bookmark tree

fo:bookmark

This creates a single bookmark which links to a place in the PDF file. The destination in the PDF file is created by giving some formatting object an id attribute, then setting the internal-destination attribute on the bookmark to the value specified in the destination id.

fo:bookmark   (zero or more)

fo:bookmark-title   (exactly one)

fo:bookmark-tree

fo:bookmark

For an example showing the use of the element see Figure 24-18.

fo:bookmark-title

This element holds the text for a bookmark entry.

fo:bookmark

For an example showing the use of the element see Figure 24-18.

Out-of-line formatting objects

The objects described in this section are used to create floats and footnotes.

fo:float

This element is used to position content either (a) at the top of a page or (b) to the side of a page so that text flows around it.

fo:block   (zero or more)

fo:block-container   (zero or more)

fo:float   (one or more, cannot be used inside an out-of-line element)

fo:index-range-begin   (one or more, subject to constraints specified for this element)

fo:index-range-end   (one or more, subject to constraints specified for this element)

fo:list-block   (zero or more)

fo:retrieve-marker   (one or more, subject to constraints specified for this element)

fo:table   (zero or more)

fo:table-and-caption   (zero or more)

fo:wrapper   (one or more, subject to constraints specified for this element)

fo:index-page-citation-range-separator

fo:index-page-citation-list-separator

fo:index-page-number-prefix

fo:index-page-number-suffix

fo:wrapper

fo:basic-link

fo:title

fo:float

fo:footnote-body

fo:static-content

fo:table-caption

fo:block

fo:block-container

fo:inline

fo:folio-suffix

fo:folio-prefix

fo:inline-container

fo:bidi-override

fo:table-cell

fo:list-item-label

fo:list-item-body

fo:marker

For an example showing the use of the element see Figure 24-19.

<fo:block>
  <fo:float float="start">
   <fo:block-container inline-progression-dimension="3cm" padding="5mm">
      <fo:block padding="2mm" space-before.conditionality="retain" border="1pt solid white" width="2cm">
         <fo:block padding-left="2mm">
          <fo:external-graphic src="url(ibexorange.jpg)" content-width='50%'/>
         <fo:/block>
     <fo:/block>
   <fo:/block-container>
 <fo:/float>
 <fo:block padding-top="2mm" padding-bottom='2mm' space-before="9pt" font="10pt 'minion regular'">
 This text should appear to the right of the image until we pass the bottom of the image
 and then appear below the image as well.  
 <fo:/block>
 <fo:block font="10pt 'minion regular'">
 We have lots of text here just to show that it will be formatted in the correct way and eventually
 there will be enough text to go past the image and appear below it on the page.  Then we will have some
 XML which shows how to acheive this effect.
 We have lots of text here just to show that it will be formatted in the correct way and eventually
 there will be enough text to go past the image and appear below it on the page.  Then we will have some
 XML which shows how to acheive this effect.
 We have lots of text here just to show that it will be formatted in the correct way and eventually
 there will be enough text to go past the image and appear below it on the page.  Then we will have some
 XML which shows how to acheive this effect.
	
 <fo:/block>
	      
<fo:/block>
	

Figure 24-19: The float element

fo:footnote

This element is used to insert a footnote which will appear at the bottom of the region. The footnote contains an inline which is the anchor and is position in the containing block at the point the footnote occurs. The contents of the footnote-body are move out of line to the end of the region.

fo:footnote-body   (exactly one)

fo:inline   (exactly one)

fo:index-page-citation-range-separator

fo:index-page-citation-list-separator

fo:index-page-number-prefix

fo:index-page-number-suffix

fo:wrapper

fo:basic-link

fo:title

fo:block

fo:inline

fo:folio-suffix

fo:folio-prefix

fo:bidi-override

fo:marker

fo:footnote-body

This element is used to insert a the content of a footnote which will appear at the bottom of the region.

fo:block   (zero or more)

fo:block-container   (zero or more)

fo:float   (one or more, cannot be used inside an out-of-line element)

fo:index-range-begin   (one or more, subject to constraints specified for this element)

fo:index-range-end   (one or more, subject to constraints specified for this element)

fo:list-block   (zero or more)

fo:retrieve-marker   (one or more, subject to constraints specified for this element)

fo:table   (zero or more)

fo:table-and-caption   (zero or more)

fo:wrapper   (one or more, subject to constraints specified for this element)

fo:footnote

Formatting objects for indexing

These objects are used in creating an index at the end of a document.

fo:index-page-number-prefix

This element is used to specify a prefix for page numbers created using an fo:index-key-reference element.

text

fo:basic-link   (zero or more)

fo:bidi-override   (zero or more)

fo:character   (zero or more)

fo:external-graphic   (zero or more)

fo:float   (one or more, cannot be used inside an out-of-line element)

fo:footnote   (one or more, cannot be used inside an out-of-line element)

fo:index-page-citation-last   (zero or more)

fo:index-range-begin   (one or more, subject to constraints specified for this element)

fo:index-range-end   (one or more, subject to constraints specified for this element)

fo:inline   (zero or more)

fo:inline-container   (zero or more)

fo:instream-foreign-object   (zero or more)

fo:leader   (zero or more)

fo:page-number   (zero or more)

fo:page-number-citation   (zero or more)

fo:page-number-citation-last   (zero or more)

fo:retrieve-marker   (one or more, subject to constraints specified for this element)

fo:scaling-value-citation   (zero or more)

fo:wrapper   (one or more, subject to constraints specified for this element)

fo:index-key-reference

fo:index-page-number-suffix

This element is used to specify a suffix for page numbers created using an fo:index-key-reference element.

text

fo:basic-link   (zero or more)

fo:bidi-override   (zero or more)

fo:character   (zero or more)

fo:external-graphic   (zero or more)

fo:float   (one or more, cannot be used inside an out-of-line element)

fo:footnote   (one or more, cannot be used inside an out-of-line element)

fo:index-page-citation-last   (zero or more)

fo:index-range-begin   (one or more, subject to constraints specified for this element)

fo:index-range-end   (one or more, subject to constraints specified for this element)

fo:inline   (zero or more)

fo:inline-container   (zero or more)

fo:instream-foreign-object   (zero or more)

fo:leader   (zero or more)

fo:page-number   (zero or more)

fo:page-number-citation   (zero or more)

fo:page-number-citation-last   (zero or more)

fo:retrieve-marker   (one or more, subject to constraints specified for this element)

fo:scaling-value-citation   (zero or more)

fo:wrapper   (one or more, subject to constraints specified for this element)

fo:index-key-reference

fo:index-range-begin

This element is used to indicate the start of a range of content which has an associated index key. The index will typically contain the range of page numbers between an fo:index-range-begin and an fo:index-range-end. An fo:index-range-begin/fo:index-range-end pair match if the ref-id property of the fo:index-range-end has the same value as the id property on the fo:index-range-begin.

This element must be empty.

fo:index-page-citation-range-separator

fo:index-page-citation-list-separator

fo:index-page-number-prefix

fo:index-page-number-suffix

fo:wrapper

fo:basic-link

fo:title

fo:float

fo:footnote-body

fo:static-content

fo:table-caption

fo:block

fo:block-container

fo:inline

fo:folio-suffix

fo:folio-prefix

fo:inline-container

fo:bidi-override

fo:table-cell

fo:list-item-label

fo:list-item-body

fo:marker

fo:index-range-end

This element is used to indicate the end of a range of content which has an associated index key. The index will typically contain the range of page numbers between an fo:index-range-begin and an fo:index-range-end. An fo:index-range-begin/fo:index-range-end pair match if the ref-id property of the fo:index-range-end has the same value as the id property on the fo:index-range-begin.

This element must be empty.

fo:index-page-citation-range-separator

fo:index-page-citation-list-separator

fo:index-page-number-prefix

fo:index-page-number-suffix

fo:wrapper

fo:basic-link

fo:title

fo:float

fo:footnote-body

fo:static-content

fo:table-caption

fo:block

fo:block-container

fo:inline

fo:folio-suffix

fo:folio-prefix

fo:inline-container

fo:bidi-override

fo:table-cell

fo:list-item-label

fo:list-item-body

fo:marker

fo:index-key-reference

This element is used in the index creation process to insert a set of page numbers for all occurrences of the specified index-key.

The child fo:index-page-number-prefix and fo:index-page-number-suffix elements specify content which will appear before and after the page numbers. This is how you would create page numbers like [20].

fo:index-page-number-prefix   (zero or one)

fo:index-page-number-suffix   (zero or one)

fo:index-page-citation-list

fo:index-page-citation-list

This element is used in the index creation process to group set of page numbers in the index.

fo:index-key-reference   (one or more)

fo:index-page-citation-list-separator   (zero or one)

fo:index-page-citation-range-separator   (zero or one)

Other formatting objects

fo:change-bar-begin

This element marks the start of a change region, and causes a change bar to be drawn on the side of the containing region from the point this element occurs to the location of the matching fo:change-bar-end element.

This element must be empty.

fo:change-bar-end

This element marks the end of a change region, and causes a change bar to be drawn on the side of the containing region from the location of the matching fo:change-bar-begin this element of this element.

This element must be empty.

fo:wrapper

This element is used to specify inherited attributes for the elements it contains.

text

fo:basic-link   (zero or more)

fo:bidi-override   (zero or more)

fo:block   (zero or more)

fo:block-container   (zero or more)

fo:character   (zero or more)

fo:external-graphic   (zero or more)

fo:float   (one or more, cannot be used inside an out-of-line element)

fo:footnote   (one or more, cannot be used inside an out-of-line element)

fo:index-page-citation-last   (zero or more)

fo:index-range-begin   (one or more, subject to constraints specified for this element)

fo:index-range-end   (one or more, subject to constraints specified for this element)

fo:inline   (zero or more)

fo:inline-container   (zero or more)

fo:instream-foreign-object   (zero or more)

fo:leader   (zero or more)

fo:list-block   (zero or more)

fo:page-number   (zero or more)

fo:page-number-citation   (zero or more)

fo:page-number-citation-last   (zero or more)

fo:retrieve-marker   (one or more, subject to constraints specified for this element)

fo:scaling-value-citation   (zero or more)

fo:table   (zero or more)

fo:table-and-caption   (zero or more)

fo:wrapper   (one or more, subject to constraints specified for this element)

fo:index-page-citation-range-separator

fo:index-page-citation-list-separator

fo:index-page-number-prefix

fo:index-page-number-suffix

fo:wrapper

fo:basic-link

fo:title

fo:float

fo:footnote-body

fo:static-content

fo:table-caption

fo:block

fo:block-container

fo:inline

fo:folio-suffix

fo:folio-prefix

fo:inline-container

fo:bidi-override

fo:table-cell

fo:list-item-label

fo:list-item-body

fo:marker

fo:marker

This element contains some content which will be retrieved elsewhere in the document using a fo:retrieve-marker element.

Typically marker is used to set some piece of text such as the current chapter title which is then retrieved within a fo:static-content element for placing in the page header. The Ibex manual uses this technique to place the current chapter name in the top right corner of most pages.

An marker cannot be used in fo:static-content elements, and a fo:retrieve-maker can be used only in fo:static-content elements.

An marker uses the marker-class-name attribute to group markers which have a common purpose. The fo:retrieve-marker element has some attributes to specify which marker should be retrieved, such as the first or last one in the document or the first or last one on that page.

text

fo:basic-link   (zero or more)

fo:bidi-override   (zero or more)

fo:block   (zero or more)

fo:block-container   (zero or more)

fo:character   (zero or more)

fo:external-graphic   (zero or more)

fo:float   (one or more, cannot be used inside an out-of-line element)

fo:footnote   (one or more, cannot be used inside an out-of-line element)

fo:index-page-citation-last   (zero or more)

fo:index-range-begin   (one or more, subject to constraints specified for this element)

fo:index-range-end   (one or more, subject to constraints specified for this element)

fo:inline   (zero or more)

fo:inline-container   (zero or more)

fo:instream-foreign-object   (zero or more)

fo:leader   (zero or more)

fo:list-block   (zero or more)

fo:page-number   (zero or more)

fo:page-number-citation   (zero or more)

fo:page-number-citation-last   (zero or more)

fo:retrieve-marker   (one or more, subject to constraints specified for this element)

fo:scaling-value-citation   (zero or more)

fo:table   (zero or more)

fo:table-and-caption   (zero or more)

fo:wrapper   (one or more, subject to constraints specified for this element)

For an example showing the use of the element see .

fo:retrieve-marker

The fo:marker element contains some content which will be retrieved elsewhere in the document using a retrieve-marker element.

Typically marker is used to set some piece of text such as the current chapter title which is then retrieved within a fo:static-content element for placing in the page header. The Ibex manual uses this technique to place the current chapter subject in the footer.

The fo:marker element cannot be used in fo:static-content elements and the retrieve-maker element can be used only in fo:static-content elements.

An fo:marker uses the marker-class-name attribute to group markers which have a common purpose. The retrieve-marker element has some attributes to specify which marker should be retrieved, such as the first or last one in the document or the first or last one on that page.

For the retrieve-marker element to work its retrieve-class-name attribute must have the same value as the maker-class-name attribute used on some fo:marker element.

This element must be empty.

fo:index-page-citation-range-separator

fo:index-page-citation-list-separator

fo:index-page-number-prefix

fo:index-page-number-suffix

fo:wrapper

fo:basic-link

fo:title

fo:float

fo:footnote-body

fo:static-content

fo:table-caption

fo:block

fo:block-container

fo:inline

fo:folio-suffix

fo:folio-prefix

fo:inline-container

fo:bidi-override

fo:table-cell

fo:list-item-label

fo:list-item-body

fo:marker

For an example showing the use of the element see .

fo:retrieve-table-marker

The fo:marker element contains some content which will be retrieved elsewhere in the document using a retrieve-table-marker or retrieve-marker element.

The retrieve-table-marker element is used inside a table-header or table-footer to specify a marker whose content will be retrieved. This is described in detail on page continuation-markers

For the retrieve-marker element to work its retrieve-class-name attribute must have the same value as the maker-class-name attribute used on some fo:marker element.

This element must be empty.

For an example showing the use of the element see .

Attributes

absolute-position

Default value: "auto"

Value

Notes

auto

absolute

fixed

inherit

alignment-adjust

This is used on a formatting objects to help explicitly determine the baseline for objects such as images which do not have a baseline.

Default value: "auto"

alignment-baseline

This is used to specify which baseline an object should be aligned on. See page baseline for a discussion of baselines.

Default value: "auto"

Value

Notes

inherit

auto

baseline

before-edge

text-before-edge

central

middle

after-edge

text-after-edge

ideographic

alphabetic

hanging

mathematical

allowed-height-scale

Sets possible scaling values for images. Not used in PDF creation.

Default value: "any"

allowed-width-scale

Sets possible scaling values for images. Not used in PDF creation.

Default value: "any"

background-attachment

Specifies whether background images scroll nor not. Not used in PDF creation.

Default value: "any"

background-color

Sets the background color for the element.

Default value: "transparent"

Value

Notes

<color>

A color such as 'red', 'blue' etc. or an RGB color such as '#445566' or a CMYK color defined using the rgb-icc color.

transparent

inherit

background-image

Specifies a URL for an image to be displayed in the background of an element. See page images for an example.

Default value: "none"

background-position-horizontal

Specifies the initial horizontal position of a background image. See page images for an example.

Default value: "0%"

background-position-vertical

Specifies the initial vertical position of a background image. See page images for an example.

Default value: "0%"

background-repeat

Specifies if a background image should be repeated when it is smaller than the containing area. See page images for an example.

Default value: "repeat"

Value

Notes

repeat

The image is repeated horizontally and vertically

repeat-x

The image is repeated horizontally only

repeat-y

The image is repeated vertically only

no-repeat

The image is not repeated

baseline-shift

Specifies the amount by which text in an inline should be shifted from the baseline. This is used to create subscript and superscript text. See page subscript for an example.

Default value: "baseline"

Value

Notes

baseline

Text is not shifted

sub

Text is lowered by an amount read from the font file

super

Text is raised by an amount read from the font file

percentage

Text is raised or lowered by a percentage of the current font size

length

Text is raised or lowered by the specified amount

blank-or-not-blank

This is used on a repeatable-page-master-alternative to specify whether the page master should be selected when the current page is blank. The current page will be blank if an extra page is being generated in a page sequence because it must have an odd or even number of pages, or because the following page sequence must start on an odd or even page.

Default value: "any"

Value

Notes

any

blank

not-blank

Text is raised by an amount read from the font file

block-progression-dimension

Sets the dimension of content in the block progression direction, which for a non-rotated page is down the page.

The content of an element excludes padding and borders. This means an element with block-progression-dimension="3cm" and border=".25cm" will have a height including borders and padding of 3.5cm.

Can be set as a single value such as:

block-progression-dimension="20cm"
		

Figure 24-20:

or you can specify minimum and maximum values like this:

block-progression-dimension.minimum="5cm"
block-progression-dimension.maximum="25cm"
		

Figure 24-21:

Default value: "auto"

Value

Notes

auto

<length>

A length such as '10cm'. Valid units are pt (points) cm (centimetres) in (inches) mm (millimetres) em (current font size in points).

<percentage>

A percentage such as "10%". The value is calculated as a percentage of the parent elements height.

<length-range>

The value has three sub-components, namely minimim, optimum and maximum. Each of these can be set to a <length> value.

inherit

border

Sets the border for all four sides of an element to the same value.

Any of the values listed can be combined, for example you can have:

border="12pt solid red"
		

Figure 24-22:

Default value: Shorthand properties do not have default values. See individual properties for their default values.

Value

Notes

<color>

A color such as 'red', 'blue' etc. or an RGB color such as '#445566' or a CMYK color defined using the rgb-icc color.

<border-width>

WidthNotes
thin A thin border. The actual default width is Settings.BorderWidthThin and so can be changed programatically.
medium A medium border. The actual default width is Settings.BorderWidthMedium and so can be changed programatically.
thick A thick border. The actual default width is Settings.BorderWidthThick and so can be changed programatically.
<length> A length such as '10cm'. Valid units are pt (points) cm (centimetres) in (inches) mm (millimetres) em (current font size in points)

<border-style>

StyleNotes
none No border
solid A single solid line
double Two lines separated by a gap. The gap is 1/3 of the width of the border.
dashed A single dashed line
dotted A single dotted line
inset The top and left borders are slightly darker then the required color and the bottom and right borders are slightly lighter.
outset The top and left borders are slightly lighter then the required color and the bottom and right borders are slightly darker.
ridge

inherit

border-after-color

Sets the "after" border color, which for a non-rotated object is the bottom one. For example:

border-after-color="red"
		

Figure 24-23:

Default value: "the value of the color property"

Value

Notes

<color>

A color such as 'red', 'blue' etc. or an RGB color such as '#445566' or a CMYK color defined using the rgb-icc color.

inherit

border-after-style

Sets the "after" border style, which for a non-rotated object is the bottom one. For example:

border-after-style="solid"
		

Figure 24-24:

Default value: "none"

Value

Notes

<border-style>

StyleNotes
none No border
solid A single solid line
double Two lines separated by a gap. The gap is 1/3 of the width of the border.
dashed A single dashed line
dotted A single dotted line
inset The top and left borders are slightly darker then the required color and the bottom and right borders are slightly lighter.
outset The top and left borders are slightly lighter then the required color and the bottom and right borders are slightly darker.
ridge

inherit

border-after-width

Sets the "after" border width, which for a non-rotated object is the bottom one. For example:

border-after-width="1pt"
		

Figure 24-25:

Default value: "medium"

Value

Notes

<border-width>

WidthNotes
thin A thin border. The actual default width is Settings.BorderWidthThin and so can be changed programatically.
medium A medium border. The actual default width is Settings.BorderWidthMedium and so can be changed programatically.
thick A thick border. The actual default width is Settings.BorderWidthThick and so can be changed programatically.
<length> A length such as '10cm'. Valid units are pt (points) cm (centimetres) in (inches) mm (millimetres) em (current font size in points)

inherit

border-before-color

Sets the "before" border color, which for a non-rotated object is the top one. For example:

border-before-color="red"
		

Figure 24-26:

Default value: "the value of the color property"

Value

Notes

<color>

A color such as 'red', 'blue' etc. or an RGB color such as '#445566' or a CMYK color defined using the rgb-icc color.

inherit

border-before-style

Sets the "before" border style, which for a non-rotated object is the top one. For example:

border-before-style="solid"
		

Figure 24-27:

Default value: "none"

Value

Notes

<border-style>

StyleNotes
none No border
solid A single solid line
double Two lines separated by a gap. The gap is 1/3 of the width of the border.
dashed A single dashed line
dotted A single dotted line
inset The top and left borders are slightly darker then the required color and the bottom and right borders are slightly lighter.
outset The top and left borders are slightly lighter then the required color and the bottom and right borders are slightly darker.
ridge

inherit

border-before-width

Sets the "before" border width, which for a non-rotated object is the top one. For example:

border-before-width="1pt"
		

Figure 24-28:

Default value: "medium"

Value

Notes

<border-width>

WidthNotes
thin A thin border. The actual default width is Settings.BorderWidthThin and so can be changed programatically.
medium A medium border. The actual default width is Settings.BorderWidthMedium and so can be changed programatically.
thick A thick border. The actual default width is Settings.BorderWidthThick and so can be changed programatically.
<length> A length such as '10cm'. Valid units are pt (points) cm (centimetres) in (inches) mm (millimetres) em (current font size in points)

inherit

border-bottom

Sets the color, width and style of the bottom border of an element.

A shorthand way of setting border-bottom-color, border-bottom-width and border-bottom-style.

Any of the values listed can be combined, for example you can have:

border-bottom="12pt solid red"
		

Figure 24-29:

Default value: Shorthand properties do not have default values. See individual properties for their default values.

Value

Notes

<color>

A color such as 'red', 'blue' etc. or an RGB color such as '#445566' or a CMYK color defined using the rgb-icc color.

<border-width>

WidthNotes
thin A thin border. The actual default width is Settings.BorderWidthThin and so can be changed programatically.
medium A medium border. The actual default width is Settings.BorderWidthMedium and so can be changed programatically.
thick A thick border. The actual default width is Settings.BorderWidthThick and so can be changed programatically.
<length> A length such as '10cm'. Valid units are pt (points) cm (centimetres) in (inches) mm (millimetres) em (current font size in points)

<border-style>

StyleNotes
none No border
solid A single solid line
double Two lines separated by a gap. The gap is 1/3 of the width of the border.
dashed A single dashed line
dotted A single dotted line
inset The top and left borders are slightly darker then the required color and the bottom and right borders are slightly lighter.
outset The top and left borders are slightly lighter then the required color and the bottom and right borders are slightly darker.
ridge

inherit

border-bottom-color

Sets the bottom border color. For example:

border-bottom-color="red"
		

Figure 24-30:

Default value: "the value of the color property"

Value

Notes

<color>

A color such as 'red', 'blue' etc. or an RGB color such as '#445566' or a CMYK color defined using the rgb-icc color.

inherit

border-bottom-style

Sets the bottom border style. For example:

border-bottom-style="solid"
		

Figure 24-31:

Default value: "none"

Value

Notes

<border-style>

StyleNotes
none No border
solid A single solid line
double Two lines separated by a gap. The gap is 1/3 of the width of the border.
dashed A single dashed line
dotted A single dotted line
inset The top and left borders are slightly darker then the required color and the bottom and right borders are slightly lighter.
outset The top and left borders are slightly lighter then the required color and the bottom and right borders are slightly darker.
ridge

inherit

border-bottom-width

Sets the bottom border width. For example:

border-bottom-width="1pt"
		

Figure 24-32:

Default value: "medium"

Value

Notes

<border-width>

WidthNotes
thin A thin border. The actual default width is Settings.BorderWidthThin and so can be changed programatically.
medium A medium border. The actual default width is Settings.BorderWidthMedium and so can be changed programatically.
thick A thick border. The actual default width is Settings.BorderWidthThick and so can be changed programatically.
<length> A length such as '10cm'. Valid units are pt (points) cm (centimetres) in (inches) mm (millimetres) em (current font size in points)

inherit

border-collapse

Controls whether borders on adjacent rows, cells and table elements are collapsed into a single border or remain separate.

Default value: "collapse"

Value

Notes

collapse

borders are collapsed. Precedence rules are evaluated to see which borders take precedence.

collapse-with-precedence

borders are collapsed. Precedence rules are evaluated to see which borders take precedence. In addition the border-precedence attribute can be used to change the precedence rules.

separate

borders are not collapsed. Only cell and table borders are considered, borders on all other elements are ignored.

inherit

border-color

Sets the border color for all four sides of an element to the same color or to a number of different colors.

To set all borders to the same color use a single value like this:

border-color="red"
		

Figure 24-33:

If there are two values the top and bottom borders are set to the first value and the side borders are set to the second, like this:

border-color="red blue"
		

Figure 24-34:

If there are three values the top border is set to the first value, the side borders are set to the second, and the bottom is set to the third like this:

border-color="red blue green"
		

Figure 24-35:

If there are four values the top border is set to the first value, the right border is set to the second, the bottom is set to the third and the left is set to the forth (so clockwise from the top) like this:

border-color="red blue green black"
		

Figure 24-36:

Default value: Shorthand properties do not have default values. See individual properties for their default values.

Value

Notes

<color>

A color such as 'red', 'blue' etc. or an RGB color such as '#445566' or a CMYK color defined using the rgb-icc color.

transparent

inherit

border-end-color

Sets the end border color (the right side of a non-rotated page). For example:

border-end-color="red"
		

Figure 24-37:

Default value: "the value of the color property"

Value

Notes

<color>

A color such as 'red', 'blue' etc. or an RGB color such as '#445566' or a CMYK color defined using the rgb-icc color.

inherit

border-end-style

Sets the end border style (the right side of a non-rotated page). For example:

border-end-style="solid"
		

Figure 24-38:

Default value: "none"

Value

Notes

<border-style>

StyleNotes
none No border
solid A single solid line
double Two lines separated by a gap. The gap is 1/3 of the width of the border.
dashed A single dashed line
dotted A single dotted line
inset The top and left borders are slightly darker then the required color and the bottom and right borders are slightly lighter.
outset The top and left borders are slightly lighter then the required color and the bottom and right borders are slightly darker.
ridge

inherit

border-end-width

Sets the end border width (the right side of a non-rotated page). For example:

border-end-width="1pt"
		

Figure 24-39:

Default value: "medium"

Value

Notes

<border-width>

WidthNotes
thin A thin border. The actual default width is Settings.BorderWidthThin and so can be changed programatically.
medium A medium border. The actual default width is Settings.BorderWidthMedium and so can be changed programatically.
thick A thick border. The actual default width is Settings.BorderWidthThick and so can be changed programatically.
<length> A length such as '10cm'. Valid units are pt (points) cm (centimetres) in (inches) mm (millimetres) em (current font size in points)

inherit

border-left

Sets the color, width and style of the left border of an element.

A shorthand way of setting border-left-color, border-left-width and border-left-style.

Any of the values listed can be combined, for example you can have:

border-left="12pt solid red"
		

Figure 24-40:

Default value: Shorthand properties do not have default values. See individual properties for their default values.

Value

Notes

<color>

A color such as 'red', 'blue' etc. or an RGB color such as '#445566' or a CMYK color defined using the rgb-icc color.

<border-width>

WidthNotes
thin A thin border. The actual default width is Settings.BorderWidthThin and so can be changed programatically.
medium A medium border. The actual default width is Settings.BorderWidthMedium and so can be changed programatically.
thick A thick border. The actual default width is Settings.BorderWidthThick and so can be changed programatically.
<length> A length such as '10cm'. Valid units are pt (points) cm (centimetres) in (inches) mm (millimetres) em (current font size in points)

<border-style>

StyleNotes
none No border
solid A single solid line
double Two lines separated by a gap. The gap is 1/3 of the width of the border.
dashed A single dashed line
dotted A single dotted line
inset The top and left borders are slightly darker then the required color and the bottom and right borders are slightly lighter.
outset The top and left borders are slightly lighter then the required color and the bottom and right borders are slightly darker.
ridge

inherit

border-left-color

Sets the left border color. For example:

border-left-color="red"
		

Figure 24-41:

Default value: "the value of the color property"

Value

Notes

<color>

A color such as 'red', 'blue' etc. or an RGB color such as '#445566' or a CMYK color defined using the rgb-icc color.

inherit

border-left-style

Sets the left border style. For example:

border-left-style="solid"
		

Figure 24-42:

Default value: "none"

Value

Notes

<border-style>

StyleNotes
none No border
solid A single solid line
double Two lines separated by a gap. The gap is 1/3 of the width of the border.
dashed A single dashed line
dotted A single dotted line
inset The top and left borders are slightly darker then the required color and the bottom and right borders are slightly lighter.
outset The top and left borders are slightly lighter then the required color and the bottom and right borders are slightly darker.
ridge

inherit

border-left-width

Sets the left border width. For example:

border-left-width="1pt"
		

Figure 24-43:

Default value: "medium"

Value

Notes

<border-width>

WidthNotes
thin A thin border. The actual default width is Settings.BorderWidthThin and so can be changed programatically.
medium A medium border. The actual default width is Settings.BorderWidthMedium and so can be changed programatically.
thick A thick border. The actual default width is Settings.BorderWidthThick and so can be changed programatically.
<length> A length such as '10cm'. Valid units are pt (points) cm (centimetres) in (inches) mm (millimetres) em (current font size in points)

inherit

border-right

Sets the color, width and style of the right border of an element.

A shorthand way of setting border-right-color, border-right-width and border-right-style.

Any of the values listed can be combined, for example you can have:

border-right="12pt solid red"
		

Figure 24-44:

Default value: Shorthand properties do not have default values. See individual properties for their default values.

Value

Notes

<color>

A color such as 'red', 'blue' etc. or an RGB color such as '#445566' or a CMYK color defined using the rgb-icc color.

<border-width>

WidthNotes
thin A thin border. The actual default width is Settings.BorderWidthThin and so can be changed programatically.
medium A medium border. The actual default width is Settings.BorderWidthMedium and so can be changed programatically.
thick A thick border. The actual default width is Settings.BorderWidthThick and so can be changed programatically.
<length> A length such as '10cm'. Valid units are pt (points) cm (centimetres) in (inches) mm (millimetres) em (current font size in points)

<border-style>

StyleNotes
none No border
solid A single solid line
double Two lines separated by a gap. The gap is 1/3 of the width of the border.
dashed A single dashed line
dotted A single dotted line
inset The top and left borders are slightly darker then the required color and the bottom and right borders are slightly lighter.
outset The top and left borders are slightly lighter then the required color and the bottom and right borders are slightly darker.
ridge

inherit

border-right-color

Sets the right border color. For example:

border-right-color="red"
		

Figure 24-45:

Default value: "the value of the color property"

Value

Notes

<color>

A color such as 'red', 'blue' etc. or an RGB color such as '#445566' or a CMYK color defined using the rgb-icc color.

inherit

border-right-style

Sets the right border style. For example:

border-right-style="solid"
		

Figure 24-46:

Default value: "none"

Value

Notes

<border-style>

StyleNotes
none No border
solid A single solid line
double Two lines separated by a gap. The gap is 1/3 of the width of the border.
dashed A single dashed line
dotted A single dotted line
inset The top and left borders are slightly darker then the required color and the bottom and right borders are slightly lighter.
outset The top and left borders are slightly lighter then the required color and the bottom and right borders are slightly darker.
ridge

inherit

border-right-width

Sets the right border width. For example:

border-right-width="1pt"
		

Figure 24-47:

Default value: "medium"

Value

Notes

<border-width>

WidthNotes
thin A thin border. The actual default width is Settings.BorderWidthThin and so can be changed programatically.
medium A medium border. The actual default width is Settings.BorderWidthMedium and so can be changed programatically.
thick A thick border. The actual default width is Settings.BorderWidthThick and so can be changed programatically.
<length> A length such as '10cm'. Valid units are pt (points) cm (centimetres) in (inches) mm (millimetres) em (current font size in points)

inherit

border-separation

Sets the separation between cell borders in a table with border-collapse="separate".

To set both horizontal and vertical separation the same use:

border-separation="3pt"
		

Figure 24-48:

To set horizontal and vertical separation to different values use the inline-progression-dimension and block-progression-dimension components like this:

border-separation.inline-progression-dimension="3pt"
border-separation.block-progression-dimension="10pt"
		

Figure 24-49:

For a non-rotated page block-progression-dimension is down the page and inline-progression-dimension is across.

Default value: "0pt"

Value

Notes

<length>

A length such as '10cm'. Valid units are pt (points) cm (centimetres) in (inches) mm (millimetres) em (current font size in points).

inherit

border-spacing

This is a shorthand method of setting the border-separation attribute.

To set both horizontal and vertical separation the same use:

border-spacing="3pt"
		

Figure 24-50:

To set horizontal and vertical separation to different values use two values separated by a space like this:

border-spacing="3mm 13mm"
		

Figure 24-51:

The first value sets the horizontal spacing, the second sets the vertical spacing.

Default value: "0pt"

Value

Notes

<length>

A length such as '10cm'. Valid units are pt (points) cm (centimetres) in (inches) mm (millimetres) em (current font size in points).

inherit

border-start-color

Sets the start border color (the left side of a non-rotated page). For example:

border-start-color="red"
		

Figure 24-52:

Default value: "the value of the color property"

Value

Notes

<color>

A color such as 'red', 'blue' etc. or an RGB color such as '#445566' or a CMYK color defined using the rgb-icc color.

inherit

border-start-style

Sets the start border style (the left side of a non-rotated page). For example:

border-start-style="solid"
		

Figure 24-53:

Default value: "none"

Value

Notes

<border-style>

StyleNotes
none No border
solid A single solid line
double Two lines separated by a gap. The gap is 1/3 of the width of the border.
dashed A single dashed line
dotted A single dotted line
inset The top and left borders are slightly darker then the required color and the bottom and right borders are slightly lighter.
outset The top and left borders are slightly lighter then the required color and the bottom and right borders are slightly darker.
ridge

inherit

border-start-width

Sets the start border width (the left side of a non-rotated page). For example:

border-start-width="1pt"
		

Figure 24-54:

Default value: "medium"

Value

Notes

<border-width>

WidthNotes
thin A thin border. The actual default width is Settings.BorderWidthThin and so can be changed programatically.
medium A medium border. The actual default width is Settings.BorderWidthMedium and so can be changed programatically.
thick A thick border. The actual default width is Settings.BorderWidthThick and so can be changed programatically.
<length> A length such as '10cm'. Valid units are pt (points) cm (centimetres) in (inches) mm (millimetres) em (current font size in points)

inherit

border-style

Sets the border style for all four sides of an element to the same style or to a number of different styles.

To set all borders to the same style use a single value like this:

border-style="solid"
		

Figure 24-55:

If there are two values the top and bottom borders are set to the first value and the side borders are set to the second, like this:

border-style="solid none"
		

Figure 24-56:

If there are three values the top border is set to the first value, the side borders are set to the second, and the bottom is set to the third like this:

border-style="solid none double"
		

Figure 24-57:

If there are four values the top border is set to the first value, the right border is set to the second, the bottom is set to the third and the left is set to the forth (so clockwise from the top) like this:

border-style="solid none double dotted"
		

Figure 24-58:

Default value: Shorthand properties do not have default values. See individual properties for their default values.

Value

Notes

<border-style>

StyleNotes
none No border
solid A single solid line
double Two lines separated by a gap. The gap is 1/3 of the width of the border.
dashed A single dashed line
dotted A single dotted line
inset The top and left borders are slightly darker then the required color and the bottom and right borders are slightly lighter.
outset The top and left borders are slightly lighter then the required color and the bottom and right borders are slightly darker.
ridge

transparent

inherit

border-top

Sets the color, width and style of the top border of an element.

A shorthand way of setting border-top-color, border-top-width and border-top-style.

Any of the values listed can be combined, for example you can have:

border-top="12pt solid red"
		

Figure 24-59:

Default value: Shorthand properties do not have default values. See individual properties for their default values.

Value

Notes

<color>

A color such as 'red', 'blue' etc. or an RGB color such as '#445566' or a CMYK color defined using the rgb-icc color.

<border-width>

WidthNotes
thin A thin border. The actual default width is Settings.BorderWidthThin and so can be changed programatically.
medium A medium border. The actual default width is Settings.BorderWidthMedium and so can be changed programatically.
thick A thick border. The actual default width is Settings.BorderWidthThick and so can be changed programatically.
<length> A length such as '10cm'. Valid units are pt (points) cm (centimetres) in (inches) mm (millimetres) em (current font size in points)

<border-style>

StyleNotes
none No border
solid A single solid line
double Two lines separated by a gap. The gap is 1/3 of the width of the border.
dashed A single dashed line
dotted A single dotted line
inset The top and left borders are slightly darker then the required color and the bottom and right borders are slightly lighter.
outset The top and left borders are slightly lighter then the required color and the bottom and right borders are slightly darker.
ridge

inherit

border-top-color

Sets the top border color. For example:

border-top-color="red"
		

Figure 24-60:

Default value: "the value of the color property"

Value

Notes

<color>

A color such as 'red', 'blue' etc. or an RGB color such as '#445566' or a CMYK color defined using the rgb-icc color.

inherit

border-top-style

Sets the top border style. For example:

border-top-style="solid"
		

Figure 24-61:

Default value: "none"

Value

Notes

<border-style>

StyleNotes
none No border
solid A single solid line
double Two lines separated by a gap. The gap is 1/3 of the width of the border.
dashed A single dashed line
dotted A single dotted line
inset The top and left borders are slightly darker then the required color and the bottom and right borders are slightly lighter.
outset The top and left borders are slightly lighter then the required color and the bottom and right borders are slightly darker.
ridge

inherit

border-top-width

Sets the top border width. For example:

border-top-width="1pt"
		

Figure 24-62:

Default value: "medium"

Value

Notes

<border-width>

WidthNotes
thin A thin border. The actual default width is Settings.BorderWidthThin and so can be changed programatically.
medium A medium border. The actual default width is Settings.BorderWidthMedium and so can be changed programatically.
thick A thick border. The actual default width is Settings.BorderWidthThick and so can be changed programatically.
<length> A length such as '10cm'. Valid units are pt (points) cm (centimetres) in (inches) mm (millimetres) em (current font size in points)

inherit

border-width

Sets the border width for all four sides of an element to the same width or to a number of different widths.

To set all borders to the same width use a single value like this:

border-width="1pt"
		

Figure 24-63:

If there are two values the top and bottom borders are set to the first value and the side borders are set to the second, like this:

border-width="1pt 3pt"
		

Figure 24-64:

If there are three values the top border is set to the first value, the side borders are set to the second, and the bottom is set to the third like this:

border-width="1pt 2pt 3pt"
		

Figure 24-65:

If there are four values the top border is set to the first value, the right border is set to the second, the bottom is set to the third and the left is set to the forth (so clockwise from the top) like this:

border-width="1pt 2pt 3pt 4pt"
		

Figure 24-66:

Default value: Shorthand properties do not have default values. See individual properties for their default values.

Value

Notes

<border-width>

WidthNotes
thin A thin border. The actual default width is Settings.BorderWidthThin and so can be changed programatically.
medium A medium border. The actual default width is Settings.BorderWidthMedium and so can be changed programatically.
thick A thick border. The actual default width is Settings.BorderWidthThick and so can be changed programatically.
<length> A length such as '10cm'. Valid units are pt (points) cm (centimetres) in (inches) mm (millimetres) em (current font size in points)

transparent

inherit

bottom

This is used for absolutely and relatively positioned elements only. It sets the distance from the bottom edge of the containing element to the bottom edge of this element.

Default value: "auto"

break-after

Use this element to insert a page break after this element.

Default value: "auto"

Value

Notes

auto

column

page

A page break will occur after this element.

inherit

break-before

Use this element to insert a page break before this element.

Default value: "auto"

Value

Notes

auto

column

page

A page break will occur before this element.

inherit

caption-side

This is used on a table-and-caption to specify on which side of the table the caption appears.

Default value: "before"

Value

Notes

before

after

start

end

top

bottom

left

right

inherit

character

This attribute sets the character to be inserted by a fo:character element. For instance to insert the character "A" into the content you would use an fo:character element like this:

<fo:character character="A"/>
        

Figure 24-67:

Default value: This attribute has no default value, you must provide a value.

clear

This is used on an element to specify that it may not be placed next to a float element on one or both sides.

Default value: "none"

Value

Notes

left

right

both

none

inherit

clip

Not used in PDF creation.

Default value: "auto"

color

This sets the foreground color of text.

Default value: "inherited from parent"

Value

Notes

<color>

A color such as 'red', 'blue' etc. or an RGB color such as '#445566' or a CMYK color defined using the rgb-icc color.

color-profile-name

This is used in specifying color profiles for PDF/X documents. The value must be set to "cmyk". See page pdf-x for more information.

Default value: "auto"

column-count

Sets the number of columns in a body region. Only the body region can have more than one column.

For example to create a body region with three columns set column-count to 3 like this:

<fo:?xml version="1.0" encoding="UTF-8"?>
<fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format">
   <fo:layout-master-set>
      <fo:simple-page-master master-name="simple">
         <fo:region-body margin="2.5cm" region-name="body"
            background-color="#eeeeee" column-count="3"/>
      <fo:/simple-page-master>
   <fo:/layout-master-set>

   <fo:page-sequence master-reference="simple">
      <fo:flow flow-name="body">
         <fo:block>Hello World<fo:/block>
      <fo:/flow>
   <fo:/page-sequence>
<fo:/root>

Figure 24-68:

Default value: "1"

Value

Notes

<fo:integer>

A non-negative integer. Sets the number of columns to this value.

column-gap

Sets the gap between columns in a body region with column-count > 1. Only the body region can have more than one column.

For example to create a body region with two columns separated by a 4cm gap set column-count to 2 and column-gap to "4cm" like this:

<fo:?xml version="1.0" encoding="UTF-8"?>
<fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format">
   <fo:layout-master-set>
      <fo:simple-page-master master-name="simple">
         <fo:region-body margin="2.5cm" region-name="body"
            column-count="2" column-gap="4cm"/>
      <fo:/simple-page-master>
   <fo:/layout-master-set>

   <fo:page-sequence master-reference="simple">
      <fo:flow flow-name="body">
         <fo:block>Hello World<fo:/block>
      <fo:/flow>
   <fo:/page-sequence>
<fo:/root>

Figure 24-69:

Default value: "12.0pt"

Value

Notes

<length>

A length such as '10cm'. Valid units are pt (points) cm (centimetres) in (inches) mm (millimetres) em (current font size in points).

column-number

This is used on a fo:table-column element to specify which column the fo:table-column element refers to.

This attribute is optional as the column number can be determined from the position of the fo:table-column element in the list of such elements.

<fo:table>
    <fo:table-column column-number="1" 
      column-width="20%"/>	
    <fo:table-column column-number="2" 
      column-width="30%"/>	
    <fo:table-column column-number="3" 
      column-width="50%"/>	
    <fo:table-body>
         <fo:table-row> 
              <fo:table-cell>col 1<fo:/table-cell>
              <fo:table-cell>col 2<fo:/table-cell>
              <fo:table-cell>col 3<fo:/table-cell>
         <fo:/table-row>
    <fo:/table-body>
<fo:/table>
		

Figure 24-70:

Default value: "current column number"

column-width

This is used on a fo:table-column element to specify the width of the column the fo:table-column element refers to.

For example to set the widths of three columns to 20%, 30% and 50% you would do this:

		
<fo:table>
    <fo:table-column column-number="1" 
      column-width="20%"/>	
    <fo:table-column column-number="2" 
      column-width="30%"/>	
    <fo:table-column column-number="3" 
       column-width="50%"/>	
    <fo:table-body>
         <fo:table-row> 
              <fo:table-cell>col 1<fo:/table-cell>
              <fo:table-cell>col 2<fo:/table-cell>
              <fo:table-cell>col 3<fo:/table-cell>
         <fo:/table-row>
    <fo:/table-body>
<fo:/table>
		

Figure 24-71:

Default value: This attribute has no default value, you must provide a value.

Value

Notes

<length>

A length such as '10cm'. Valid units are pt (points) cm (centimetres) in (inches) mm (millimetres) em (current font size in points).

content-height

This is used on a graphic element such as a fo:external-graphic to set the height of the image.

The size of an image and the size of the area containing it are two seperate things. The height and width attributes set the size of the area containing the image, the content-height and content-width attributes set the size of the image itself.

Percentage values refer to percentages of the actual size of the image as determined from the image file.

Default value: "auto"

Value

Notes

<length>

A length such as '10cm'. Valid units are pt (points) cm (centimetres) in (inches) mm (millimetres) em (current font size in points).

inherit

scale-to-fit

content-width

This is used on a graphic element such as a fo:external-graphic to set the width of the image.

The size of an image and the size of the area containing it are two seperate things. The height and width attributes set the size of the area containing the image, the content-height and content-width attributes set the size of the image itself.

Percentage values refer to percentages of the actual size of the image as determined from the image file.

Default value: "auto"

Value

Notes

<length>

A length such as '10cm'. Valid units are pt (points) cm (centimetres) in (inches) mm (millimetres) em (current font size in points).

inherit

scale-to-fit

display-align

This attribute sets the vertical alignment of content contained within the element with this attribute.

Default value: "inherited from parent"

Value

Notes

auto

before

Align to before edge which for non-rotated content is the top.

center

Align to center

after

Align to after edge which for non-rotated content is the bottom.

end-indent

This attribute sets indentation of content from the end edge of the containing area. For non-rotated content the end edge is the right edge.

This attribute sets the indentation of the content contained in the element. The content will be positioned the required distance from the right edge of the containing area, and any padding and border will then be placed outside the content.

For CSS style alignment of nested elements use the margin-left and margin-right attributes instead of start-indent and end-indent.

Default value: "0pt"

Value

Notes

auto

<length>

A length such as '10cm'. Valid units are pt (points) cm (centimetres) in (inches) mm (millimetres) em (current font size in points).

inherit

ends-row

Within a fo:table-body (or fo:table-header and fo:table-footer) element a table has fo:table-cell elements. Normally cells are placed inside a fo:table-row element, but it is possible to place the cells directly below the fo:table-body element and not have any fo:table-row elements. In this case the formatter determines formation of rows by looking for ends-row and starts-row attributes on each fo:table-cell. If a fo:table-cell ends the row then the ends-row attribute should be set to "true", otherwise it should be set to "false" or not used at all.

A table which has two rows of three cells each and is created without row elements looks like this:

<fo:table>
    <fo:table-body>
         <fo:table-cell starts-row="true">col 1<fo:/table-cell>
         <fo:table-cell>col 2<fo:/table-cell>
         <fo:table-cell ends-row="true">col 3<fo:/table-cell>
         <fo:table-cell starts-row="true">col 1<fo:/table-cell>
         <fo:table-cell>col 2<fo:/table-cell>
         <fo:table-cell ends-row="true">col 3<fo:/table-cell>
    <fo:/table-body>
<fo:/table>
		

Figure 24-72:

Default value: "false"

Value

Notes

false

This cell does not end the row

true

This cell ends the row

extent

The extent attribute determines how large a region is. It is used on region elements other then the fo:region-body element.

The extent is the size of the region. The outer edge of the region is calculated from the edge of the page plus any margin on the fo:simple-page-master element. The inner edge of the region is the outer edge plus the value of the extent attribute.

Percentage values refer to the size of the page.

Default value: "0pt"

Value

Notes

<length>

A length such as '10cm'. Valid units are pt (points) cm (centimetres) in (inches) mm (millimetres) em (current font size in points).

external-destination

This attribute destination of a fo:basic-link element used to create a hyperlink in the document.

The format of the external-destination attribute must be a URI specification (RFC2396) as described below.

To link local file the format should be:

external-destination="url(external.pdf)"
        

Figure 24-73:

or to link to a website use a format like this:

external-destination
    ="url(http://www.xmlpdf.com/builds/ibex.pdf)"
        

Figure 24-74:

Default value: ""

Value

Notes

<uri-specification>

A sequence of characters that is "url(", followed by optional white space, followed by an optional single quote (') or double quote (") character, followed by a URI reference as defined in [RFC2396], followed by an optional single quote (') or double quote (") character, followed by optional white space, followed by ")". The two quote characters must be the same and must both be present or absent. If the URI reference contains a single quote, the two quote characters must be present and be double quotes.

float

Specifies how the block which is floated should be positioned. Specify float="start" or float="before" to move the block to the start of the page. Specify float="left" to position content to the left side of the page and have other content flow around the right side of the positioned content.

Default value: "none"

Value

Notes

inherit

before

start

end

left

right

flow-map-name

Specifies a unique name for a flow-map. page-sequence elements which will be laid out with that flow-map will have the same value for their flow-map-reference attribute.

Default value: "none, a value is required"

flow-map-reference

This is used on a page-sequence to specify the name of a flow-map which will control the layout of content (in flows) to regions.

It is also used on a flow-name-specifier to specify the name of a flow which will be mapped using the containing flow-map.

Default value: "none, a value is required"

flow-name

This attribute is used on fo:flow and fo:static-content elements to define which region the content from the fo:flow and fo:static-content is placed.

For content to be placed on the page the flow-name attribute must correspond to the region-name attribute of a region of the current page layout. If the flow-name is not the same as one of the region names the content contained in the fo:flow and fo:static-content is discarded.

Default value: This attribute has no default value, you must provide a value.

Value

Notes

<fo:name>

use a value which matches a region-name used on one of the regions on the current simple-page-master.

font

This attribute is shorthand for the font-style, font-variant, font-weight, font-size, font-family, line-height attributes.

Typically the font attribute will be set to a value which defines the font name and size plus possibly bold or italic. Some example of this are:

font="12pt arial"
        

Figure 24-75:

font="bold 12pt arial"
        

Figure 24-76:

font="bold 12pt "minion regular""
        

Figure 24-77:

The elements of the font attribute must be specified in this order:

style (normal, italic)

variant (normal, smallcaps)

weight (bold, bolder, lighter etc.)

size (1em, 12pt)

line height (12pt/14pt)

font-family (helvetica)

If the font name contains spaces it should be placed in quotes. If the attribute value is in single quotes, place the font name in double quotes like this:

font="12pt "minion regular" "
        

Figure 24-78:

If the attribute value is in double quotes, place the font name in single quotes like this:

font="12pt "minion regular" "
        

Figure 24-79:

Default value: Shorthand properties do not have default values. See individual properties for their default values.

font-family

This sets the font family for the element.

This attribute can be set to a single font name like this:

font-family="arial"
        

Figure 24-80:

or a list of fonts separated by commas, like this:

font-family="arial, "minion regular""
        

Figure 24-81:

If the font name contains spaces it should be placed in quotes. If the attribute value is in single quotes, place the font name in double quotes like this:

font="12pt "minion regular" "
        

Figure 24-82:

If the attribute value is in double quotes, place the font name in single quotes like this:

font="12pt "minion regular" "
        

Figure 24-83:

In addition to actual font names the following values can be used:

"serif", "sans-serif", "cursive", "fantasy", "monospace"

These names are mapped to actual font names by the Settings.

Default value: "The value of Settings.DefaultFontFamily or inherited from parent"

font-size

This sets the font size of this element and the elements it contains.

Typical values are show here:

font-size="12pt"
        

Figure 24-84:

font-size="1.2em"
        

Figure 24-85:

Values which set the font size relative to the font size of the containing element can also be used like this:

font-size="smaller"
        

Figure 24-86:

Percentage sizes refer to the font size of the containing element.

Default value: "medium"

Value

Notes

xx-small

Set the font size to the value of Settings.XX_Small which defaults to "7pt"

x-small

Set the font size to the value of Settings.X_Small which defaults to "8.3pt"

small

Set the font size to the value of Settings.X_Small which defaults to "10pt"

medium

Set the font size to the value of Settings.X_Small which defaults to "12pt"

large

Set the font size to the value of Settings.X_Small which defaults to "14.4pt"

x-large

Set the font size to the value of Settings.X_Small which defaults to "17.4pt"

xx-large

Set the font size to the value of Settings.X_Small which defaults to "20.7pt"

smaller

Set the font size to the parent font size multipled by the value of Settings.Smaller which defaults to "0.8em"

larger

Set the font size to the parent font size multipled by the value of Settings.Larger which defaults to "1.2em"

<length>

A length such as '10cm'. Valid units are pt (points) cm (centimetres) in (inches) mm (millimetres) em (current font size in points).

font-style

This sets the font style of this element and elements it contains.

Typical values are show here:

font-style="italic"
        

Figure 24-87:

Default value: "normal"

Value

Notes

normal

The style is the same as the style of the parent element.

italic

The style is italic.

oblique

The style is italic.

inherit

font-weight

This sets the font weight of this element and elements it contains.

The specification supports numeric values. These are mapped as follows:

900bold800bold700bold600normal500normal400normal300normal200normal100normal Default value: "normal"

Value

Notes

100-900

See the table above

normal

The weight is inherited from the parent element.

bold

The text will be bold.

inherit

format

In conjuction with grouping-separator and grouping-size this attribute sets the format to be used when formatting page numbers contained within this fo:page-sequence.

Default value: "1"

Value

Notes

1

Use numeric formatting so page numbers will be 1,2,3 ..

i

Use roman formatting so page numbers will be i, ii, iii, iv, v ..

height

Sets the height of the content of an element excluding padding and borders. This means an element with height="3cm" and border=".25cm" will have a height including borders and padding of 3.5cm.

This example shows the effect of the height attribute on the content of the block-container:

<fo:block-container space-before="1cm" height="3cm" 
         border=".5cm solid red">
         <fo:block>3+.5<fo:/block>
 <fo:/block-container>
        

Figure 24-88:

This produces this output:

3+.5

By pressing Control-U in Acrobat Reader you can measure the content and see that the area within the borders is 3cm high.

Note that the width and height attributes do not apply to the fo:block element.

To set minumum and maximum height values use the block-progression-dimension attribute.

Default value: "auto"

id

This attribute is set on elements which need to be referenced from somewhere else in the document.

An example of this is the fo:page-number-citation element which inserts into the document the page number some other content appears on. The content whose page number we want to retrieve is given an id attribute, and the fo:page-number-citation sets its ref-id attribute to the same value.

An example of this is:

<fo:?xml version="1.0" encoding="UTF-8"?>
<fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format">
   <fo:layout-master-set>
      <fo:simple-page-master master-name="simple">
         <fo:region-body margin="2.5cm" region-name="body"/>
      <fo:/simple-page-master>
   <fo:/layout-master-set>

  <fo:page-sequence master-reference="simple">
      <fo:flow flow-name="body">
         <fo:block id="22">
         Hello 
         <fo:/block>
      <fo:/flow>
  <fo:/page-sequence>
  
  <fo:page-sequence master-reference="simple">
      <fo:flow flow-name="body">
         <fo:block>
         		The block with id="22" is on page 
         		<fo:page-number-citation ref-id="22"/>
         <fo:/block>
      <fo:/flow>
  <fo:/page-sequence>
  
<fo:/root>

Figure 24-89:

Default value: "a unique value generated by Ibex"

Value

Notes

<fo:id>

a unique string

initial-page-number

This attribute sets the page number of the first page create by a fo:page-sequence element.

Default value: "auto"

inline-progression-dimension

Sets the dimension of content in the inline progression direction which for a non-rotated page is across the page.

The content of an element excludes padding and borders. This means an element with inline-progression-dimension="3cm" and border=".25cm" will have a width including borders and padding of 3.5cm.

Can be set as a single value such as:

inline-progression-dimension="20cm"
		

Figure 24-90:

or you can specify minimum and maximum values like this:

inline-progression-dimension.minimum="5cm"
inline-progression-dimension.maximum="25cm"
		

Figure 24-91:

Default value: "auto"

Value

Notes

auto

<length>

A length such as '10cm'. Valid units are pt (points) cm (centimetres) in (inches) mm (millimetres) em (current font size in points).

<length-range>

The value has three sub-components, namely minimim, optimum and maximum. Each of these can be set to a <length> value.

inherit

internal-destination

This sets the destination of a fo:basic-link element.

This should be set a value used as the id attribute of the element to be linked to.

Default value: "''"

keep-together

Set this attribute to "always" to keep content together on one page. If content with keep-together="always" will not fit on what remains of a page it will be moved to the next page. If it is larger than the region in which it is being placed it will be split.

Default value: "auto"

keep-with-next

Set this attribute to "always" to keep the content with the next element in the FO. If both elements do not fit on a page they will both be moved to the next page.

This is typically used to keep a heading together with the content which follows.

Any number of elements can be kept together by having keep-with-next="always" set on each one. If the list to be kept together exceeds the size of the region in which they are being placed they will not be kept together.

Default value: "auto"

keep-with-previous

Set this attribute to "always" to keep the content with the previous element in the FO. If both elements do not fit on a page they will both be moved to the next page.

This is typically used to keep a the last two rows of a table together so that a single row is never displayed by itself.

Any number of elements can be kept together by having keep-with-previous="always" set on each one. If the list to be kept together exceeds the size of the region in which they are being placed they will not be kept together.

Default value: "auto"

leader-length

This sets the length of a fo:leader element.

This can be set as three components for the minimum, optimum and maximum values like this:

leader-length.mimimum="10pt"
leader-length.optimum="50%"
leader-length.maximum="100%"
        

Figure 24-92:

Or alternatively all three components can be set to the same value like this:

leader-length="100%"
        

Figure 24-93:

The default values for each component are:

leader-length.mimimum="0pt"

leader-length.optimum="12pt"

leader-length.maximum="100%"

Default value: "see description"

leader-pattern

This sets the appearance of a leader element.

Default value: "space"

Value

Notes

space

The leader will be blank. This is useful for justification of text.

dots

The leader will be a dotted line.

rule

The leader will be a solid line.

left

When used on an absolutely or relatively positioned element this sets the offset from the left edge of the container to the left edge of this element.

Default value: "auto"

Value

Notes

<length>

A length such as '10cm'. Valid units are pt (points) cm (centimetres) in (inches) mm (millimetres) em (current font size in points).

line-height

Sets the height of a line.

Percentage values refer to the current font size.

Default value: "normal"

Value

Notes

<length>

A length such as '10cm'. Valid units are pt (points) cm (centimetres) in (inches) mm (millimetres) em (current font size in points).

normal

Line height is 1.2 times the font size.

linefeed-treatment

This sets the way in which linefeeds in the FO appear in the output. By default linefeeds are treated as spaces only. See page for a detailed example of the effects of this attribute.

Default value: "treat-as-space"

Value

Notes

treat-as-space

Linefeeds in the FO become spaces in the output.

preserve

Linefeeds in the FO become linefeeds in the output.

margin

This is a shorthand way of setting margin-top, margin-bottom, margin-right and margin-left.

To set all margins to the same size use a single value like this:

margin="1pt"
		

Figure 24-94:

If there are two values the top and bottom margins are set to the first value and the side margins are set to the second, like this:

margin="1pt 3pt"
		

Figure 24-95:

If there are three values the top margin is set to the first value, the side margins are set to the second, and the bottom is set to the third like this:

margin="1pt 2pt 3pt"
		

Figure 24-96:

If there are four values the top margin is set to the first value, the right margin is set to the second, the bottom is set to the third and the left is set to the forth (so clockwise from the top) like this:

margin="1pt 2pt 3pt 4pt"
		

Figure 24-97:

Default value: Shorthand properties do not have default values. See individual properties for their default values.

Value

Notes

inherit

<length>

A length such as '10cm'. Valid units are pt (points) cm (centimetres) in (inches) mm (millimetres) em (current font size in points).

margin-bottom

Sets the bottom margin on an element. For example:

margin-bottom="1pt"
		

Figure 24-98:

Default value: "0pt"

Value

Notes

<length>

A length such as '10cm'. Valid units are pt (points) cm (centimetres) in (inches) mm (millimetres) em (current font size in points).

inherit

margin-left

Sets the left margin on an element. For example:

margin-left="1pt"
		

Figure 24-99:

Default value: "0pt"

Value

Notes

<length>

A length such as '10cm'. Valid units are pt (points) cm (centimetres) in (inches) mm (millimetres) em (current font size in points).

inherit

margin-right

Sets the right margin on an element. For example:

margin-right="1pt"
		

Figure 24-100:

Default value: "0pt"

Value

Notes

<length>

A length such as '10cm'. Valid units are pt (points) cm (centimetres) in (inches) mm (millimetres) em (current font size in points).

inherit

margin-top

Sets the top margin on an element. For example:

margin-top="1pt"
		

Figure 24-101:

Default value: "0pt"

Value

Notes

<length>

A length such as '10cm'. Valid units are pt (points) cm (centimetres) in (inches) mm (millimetres) em (current font size in points).

inherit

marker-class-name

Sets the name for a fo:marker which is then used on a fo:retrieve-marker element to retrieve the content contained in that marker.

See fo:marker for an example.

Default value: This attribute has no default value, you must provide a value.

master-name

This is a unique name given to a fo:simple-page-master or fo:page-sequence-master and then used as the master-reference attribute of a fo:page-sequence to specify which page master will be used to lay out the content of the fo:page-sequence.

Default value: This attribute has no default value, you must provide a value.

master-reference

Both fo:simple-page-master and fo:page-sequence-master have a unique master-name attribute which is used as the master-reference attribute of a fo:page-sequence to specify which page master will be used to lay out the content of the fo:page-sequence.

Default value: This attribute has no default value, you must provide a value.

number-columns-repeated

This is used on a fo:table-column element to indicate how many columns the fo:table-column element applies to.

Default value: "1"

number-columns-spanned

This is used on a fo:table-cell element to specify how many columns the cell spans. This is functionally similar to the HTML colspan attribute.

Default value: "1"

number-rows-spanned

This is used on a fo:table-cell element to specify how many rows the cell spans. This is functionally similar to the HTML rowspan attribute.

Default value: "1"

orphans

This specifies the number of lines of text which must appear in a paragraph before a page break. At the default setting of "2" a single line will never appear by itself at the bottom of a page. If there is room for only a single line on a page (and the paragraph has more than one line) the whole paragraph will be shifted to the next page.

Increasing the value increases the number of lines which must appear on a page before a page break.

See also widows.

Default value: "2"

overflow

This attribute determines whether content which exceeds the size of an element should be displayed or not.

An example of this is the fixed size region elements such as fo:region-before which have their size set by the extent attribute. If content is placed in the region using a fo:static-content element the content may be too large for the region. If this happens and the overflow attribute is set to "hidden" the content will not appear.

Default value: "auto"

Value

Notes

hidden

Content which exceeds the elements boundaries will be discarded.

auto

Content which exceeds the elements boundaries will be displayed.

visible

Content which exceeds the elements boundaries will be displayed.

padding

Padding is space which appears between the border of an element and the content (such as text) of that element.

This is a shorthand way of setting padding-top, padding-bottom, padding-right and padding-left.

To set all paddings to the same size use a single value like this:

padding="1pt"
		

Figure 24-102:

Default value: Shorthand properties do not have default values. See individual properties for their default values.

Value

Notes

inherit

<length>

A length such as '10cm'. Valid units are pt (points) cm (centimetres) in (inches) mm (millimetres) em (current font size in points).

padding-after

Padding is space which appears between the border of an element and the content (such as text) of that element.

This sets the padding on the after edge of an element which for an non-rotated area is the bottom edge.

padding-after="1pt"
		

Figure 24-103:

Default value: "0pt"

Value

Notes

inherit

<length>

A length such as '10cm'. Valid units are pt (points) cm (centimetres) in (inches) mm (millimetres) em (current font size in points).

padding-before

Padding is space which appears between the border of an element and the content (such as text) of that element.

This sets the padding on the before edge of an element which for an non-rotated area is the top edge.

padding-before="1pt"
		

Figure 24-104:

Default value: "0pt"

Value

Notes

inherit

<length>

A length such as '10cm'. Valid units are pt (points) cm (centimetres) in (inches) mm (millimetres) em (current font size in points).

padding-bottom

Padding is space which appears between the border of an element and the content (such as text) of that element.

This sets the padding on the bottom edge of an element.

padding-bottom="1pt"
		

Figure 24-105:

Default value: "0pt"

Value

Notes

inherit

<length>

A length such as '10cm'. Valid units are pt (points) cm (centimetres) in (inches) mm (millimetres) em (current font size in points).

padding-end

Padding is space which appears between the border of an element and the content (such as text) of that element.

This sets the padding on the end edge of an element which for an non-rotated area is the right edge.

padding-end="1pt"
		

Figure 24-106:

Default value: "0pt"

Value

Notes

inherit

<length>

A length such as '10cm'. Valid units are pt (points) cm (centimetres) in (inches) mm (millimetres) em (current font size in points).

padding-left

Padding is space which appears between the border of an element and the content (such as text) of that element.

This sets the padding on the left edge of an element.

padding-left="1pt"
		

Figure 24-107:

Default value: "0pt"

Value

Notes

inherit

<length>

A length such as '10cm'. Valid units are pt (points) cm (centimetres) in (inches) mm (millimetres) em (current font size in points).

padding-right

Padding is space which appears between the border of an element and the content (such as text) of that element.

This sets the padding on the right edge of an element.

padding-right="1pt"
		

Figure 24-108:

Default value: "0pt"

Value

Notes

inherit

<length>

A length such as '10cm'. Valid units are pt (points) cm (centimetres) in (inches) mm (millimetres) em (current font size in points).

padding-start

Padding is space which appears between the border of an element and the content (such as text) of that element.

This sets the padding on the start edge of an element which for an non-rotated area is the left edge.

padding-start="1pt"
		

Figure 24-109:

Default value: "0pt"

Value

Notes

inherit

<length>

A length such as '10cm'. Valid units are pt (points) cm (centimetres) in (inches) mm (millimetres) em (current font size in points).

padding-top

Padding is space which appears between the border of an element and the content (such as text) of that element.

This sets the padding on the top edge of an element.

padding-top="1pt"
		

Figure 24-110:

Default value: "0pt"

Value

Notes

inherit

<length>

A length such as '10cm'. Valid units are pt (points) cm (centimetres) in (inches) mm (millimetres) em (current font size in points).

page-height

This is used on a fo:simple-page-master element to set the height of a page.

If not set or if set to "auto" the page height is determined from the Settings.PageHeight property.

Default value: "auto"

Value

Notes

auto

<length>

A length such as '10cm'. Valid units are pt (points) cm (centimetres) in (inches) mm (millimetres) em (current font size in points).

page-width

This is used on a fo:simple-page-master element to set the width of a page.

If not set or if set to "auto" the page width is determined from the Settings.PageWidth property.

Default value: "auto"

Value

Notes

auto

<length>

A length such as '10cm'. Valid units are pt (points) cm (centimetres) in (inches) mm (millimetres) em (current font size in points).

precedence

This is used on fo:region-before and fo:region-after elements to control whether the top and bottom regions take precedence over (i.e. extend into the corners over) the side regions.

Default value: "false"

Value

Notes

false

true

provisional-distance-between-starts

This applies to the fo:list-block element and sets the distance (in each fo:list-item) between the start of the label element and the start of the body element.

This is not the same as the width of the label element because the width of the label element is reduced by the provisional-label-separation value.

See fo:list-block for an example.

Default value: "24pt"

provisional-label-separation

This applies to the fo:list-block element and sets the distance between the end of the label element and the start of the body element.

See fo:list-block for an example and also provisional-distance-between-starts.

Default value: "6pt"

ref-id

This attribute is used on the fo:page-number-citation to identify which the element for which we want to retrieve the page number. This should match the value of the id attribute on the other element.

See fo:page-number-citation for an example.

Default value: This attribute has no default value, you must provide a value.

reference-orientation

This attribute is used to set the rotation of whole pages (when used on fo:simple-page-master), regions (when used on region element), blocks (when used on fo:block-container) and fo:table elements.

Rotation is counter-clockwise.

See fo:block-container for an example.

Default value: "0"

Value

Notes

0

90

180

270

-90

-180

-270

inherit

region-name-reference

This is used on a region-name-specifier to specify the name of a region which will have flows mapped onto it by the containing flow-map.

Default value: "none, a value is required"

retrieve-boundary

This attribute is used on a fo:retrieve-marker to specify limits on which markers should be retrieved.

See fo:marker for a complete example.

Default value: "page-sequence"

Value

Notes

page

page-sequence

document

retrieve-class-name

This attribute is used on a fo:retrieve-marker to specify which marker is to be retrieved. This attribute specifies which class of marker is retrieved and the retrieve-boundary and retrieve-position attributes are used to choose one of the markers in that class.

See fo:marker for a complete example.

Default value: This attribute has no default value, you must provide a value.

retrieve-position

This attribute is used on a fo:retrieve-marker to specify which marker is to be retrieved. The retrieve-class-name attribute specifies which class of marker is retrieved and the retrieve-boundary and retrieve-position attributes are used to choose one of the markers in that class.

See fo:marker for a complete example.

Default value: "first-starting-within-page"

Value

Notes

first-starting-within-page

Use the first marker which appears starts on this page

first-including-carryover

Use the first marker which has any content on this page

last-starting-within-page

last-ending-within-page

right

For an absolutely positioned element this specifies the distance between the right edge of the containing element and the right edge of this element.

Default value: "auto"

rule-thickness

This is used on the fo:leader element to specify the thickness (i.e. height) of the line the leader creates.

Default value: "1pt"

Value

Notes

<length>

A length such as '10cm'. Valid units are pt (points) cm (centimetres) in (inches) mm (millimetres) em (current font size in points).

scaling

This is used on graphic elements fo:external-graphic and fo:instream-foreign-object to specify how the image should be scaled.

If the scaling is uniform a change to the image size using content-height or content-width will result in a corresponding change in the other dimension to preserve the aspect ratio. If scaling is non-uniform a change to height or width will not change the other dimension and the aspect ratio will be changed.

Default value: "uniform"

Value

Notes

uniform

See above.

non-uniform

See above.

space-after

This attribute is used to define the amount of space which appears between this element and the next.

This attribute can be set as a single value like this:

space-after="3mm"
        

Figure 24-111:

or individual components can be set like this:

space-after.minimum="3pt"
space-after.optimum="4pt"
space-after.maximum="5pt"
        

Figure 24-112:

Space resolution in XSL-FO is complicated. If two elements have space after the first one and before the second one, usually the space is combined using a formula so that generally speaking the largest space will be used.

For example if there are two blocks A and B, and A has space-after="3cm" and B has space-before="2cm" the space between the blocks will not be the sum of the two spaces (ie. 5cm) it will be the largest of the two, ie. 3cm.

To prevent the two spaces from being merged, and get the sum of the two spaces you can use the precedence component like this:

space-after="3cm" space-after.precedence="force"
        

Figure 24-113:

Precedence can also be assigned a number. If there are two spaces to be merged and they have different precedence values the one with the highest value will be used. For example:

<fo:block space-after="3cm" space-after.precedence="5">
A
<fo:/block>
<fo:block space-before="1cm" space-after.precedence="6">
B
<fo:/block>
        

Figure 24-114:

In this case the space between the two blocks will be 1cm because the second block has the higher precedence value so its space value is the one which is used.

Space which appears before a block at the top of a region is usually discarded. To avoid this and make the space appear use the conditionality component like this:

space-before="3cm" space-before.conditionality="retain" 
        

Figure 24-115:

To make matters even more complex, the space after an element refers to the space between the last mark made by this element and the first mark made by the next element. This means we need to consider child elements of the two elements whose space is being merged.

For example the block A below has a child block A2 which has a space-after attribute. This means when Ibex merges the space between A and B, it also considers the space between A2 and B.

<fo:block space-after="3cm" >
   A
<fo:block space-after="4cm" >
  A2
<fo:/block>
<fo:/block>
<fo:block space-before="1cm" >
  B
<fo:/block>
        

Figure 24-116:

so the space between A and B will be 4cm because this is the largest value. If B had a child block this would also be considered.

And it gets worse. In the example shown above A2 makes the last mark on the page made by the A block and its children. If A had a bottom border, this border would then be the last mark made by the A block and its children (because the border of A is after A2) and the merging formula would not consider A2 (as it does not now make the last mark) and so the gap between A and B would now be 3cm.

Default value: "0pt"

Value

Notes

<length>

A length such as '10cm'. Valid units are pt (points) cm (centimetres) in (inches) mm (millimetres) em (current font size in points).

space-before

This attribute is used to define the amount of space which appears between this element and the previous one.

This attribute can be set as a single value like this:

space-before="3mm"
        

Figure 24-117:

or individual components can be set like this:

space-before.minimum="3pt"
space-before.optimum="4pt"
space-before.maximum="5pt"
        

Figure 24-118:

Space resolution in XSL-FO is complicated. See space-after for a detailed description of space resolution.

Default value: "0pt"

Value

Notes

<length>

A length such as '10cm'. Valid units are pt (points) cm (centimetres) in (inches) mm (millimetres) em (current font size in points).

span

This attribute is used on block-level (fo:block,fo:table,fo:list-block) elements whose immediate parent element is a fo:flow. The span indicates if the block element should span all the columns of a multi-column fo:region-body. The only options are "none" and "all". It is not possible to span some but not all columns.

Default value: "none"

Value

Notes

none

Span one column

all

Span all columns

inherit

src

This specifies the source for a fo:external-graphic element.

The src attribute is called a uri-specification and must follow the following rules:

A sequence of characters that is "url(", followed by optional white space, followed by an optional single quote (") or double quote (") character, followed by a URI reference as defined in [RFC2396], followed by an optional single quote (") or double quote (") character, followed by optional white space, followed by ")". The two quote characters must be the same and must both be present or both be absent. If the URI reference contains a single quote, the two quote characters must be present and be double quotes.

This means the following are all valid values for the src attribute:

uri(ibex.jpg)

uri("ibex.jpg")

uri("ibex.jpg")

url(http://www.xmlpdf.com/images/download2.gif)

Default value: This attribute has no default value, you must provide a value.

start-indent

This attribute sets indentation of content from the start edge of the containing area. For non-rotated content the start edge is the left edge.

This attribute sets the indentation of the content contained in the element. The content will be positioned the required distance from the right edge of the containing area, and any padding and border will then be placed outside the content.

For CSS style alignment of nested elements use the margin-left and margin-right attributes instead of start-indent and end-indent.

Default value: "0pt"

Value

Notes

auto

<length>

A length such as '10cm'. Valid units are pt (points) cm (centimetres) in (inches) mm (millimetres) em (current font size in points).

inherit

starting-state

Specifies if a bookmark entry should be open (with its child bookmarks visible) when the PDF file is opened.

Default value: "show"

Value

Notes

inherit

show

hide

starts-row

Within a fo:table-body (or fo:table-header and fo:table-footer) element a table has fo:table-cell elements. Normally cells are placed inside a fo:table-row element, but it is possible to place the cells directly below the fo:table-body element and not have any fo:table-row elements. In this case the formatter determines formation of rows by looking for ends-row and starts-row attributes on each fo:table-cell. If a fo:table-cell ends the row then the ends-row attribute should be set to "true", otherwise it should be set to "false" or not used at all.

A table which has two rows of three cells each and is created without row elements looks like this:

<fo:table>
 <fo:table-body>
  <fo:table-cell starts-row="true">col 1<fo:/table-cell>
   <fo:table-cell>col 2<fo:/table-cell>
    <fo:table-cell ends-row="true">col 3<fo:/table-cell>
    <fo:table-cell starts-row="true">col 1<fo:/table-cell>
    <fo:table-cell>col 2<fo:/table-cell>
    <fo:table-cell ends-row="true">col 3<fo:/table-cell>
  <fo:/table-body>
<fo:/table>
		

Figure 24-119:

Default value: "false"

Value

Notes

false

This cell does not start a new row.

true

This cell starts a new the row.

table-layout

This attribute controls whether the layout of a fo:table (which means the column widths) is calculated from the content of the cells or from fo:table-column elements.

Use "fixed" to calculate column widths from fo:table-column elements. This is the recommended approach. It is faster and makes the output file look consistent when using different data.

Default value: "auto"

Value

Notes

auto

fixed

see above

table-omit-footer-at-break

By default a fo:table-footer element is repeated before every table break. If you set this attribute to "true" the table footer will appear only once, at the end of the table.

Default value: "false"

Value

Notes

true

Footer appears once at end of table

false

Footer appears at every page break

table-omit-header-at-break

By default a fo:table-header element is repeated after every table break. If you set this attribute to "true" the table header will appear only once, at the beginning of the table.

Default value: "false"

Value

Notes

true

header appears once at start of table

false

header appears after every page break

text-align

This sets the text alignment of text contained within the element. This does not align the last (or only) line of a paragraph - see the text-align-last attribute for aligning the last line.

Default value: "start"

Value

Notes

start

same as left for non-rotated content

left

center

end

same as right for non-rotated content

right

justify

text-align-last

This sets the text alignment of text last line of a paragraph - see the text-align attribute for aligning lines other than the last one.

Default value: "start"

Value

Notes

start

same as left for non-rotated content

left

center

end

same as right for non-rotated content

right

justify

white-space-collapse

This controls how multiple contiguous whitespace in the FO is treated by Ibex. By default after processing of linefeeds all remaining runs of two or more consecutive spaces are replaced by a single space, then any remaining space immediately adjacent to a remaining linefeed is also discarded.

See page for a detailed example of the effects of this attribute.

Default value: "true"

white-space-treatment

This controls how whitespace characters in the FO are treated by Ibex.

See page for a detailed example of the effects of this attribute.

Default value: "ignore-if-surrounding-linefeed"

widows

This specifies the number of lines of text which must appear in a paragraph at the top of a page. At the default setting of "2" a single line will never appear by itself at the top of a page. If possible a line from the previous page will be moved to the the current page so that 2 lines of text appear at the top of the page. If this is not possible (perhaps because of the orphans setting) the whole paragraph will be moved to the current page.

Increasing the value increases the number of lines which must appear on a page.

See also orphans.

Default value: "2"

width

This sets the desired width for an element. This is shorthand way of setting all three components of the inline-progression-dimension attribute.

Default value: "auto"

Value

Notes

<length>

A length such as '10cm'. Valid units are pt (points) cm (centimetres) in (inches) mm (millimetres) em (current font size in points).

wrap-option

This option controls word wrapping within an element.

Default behavior for text within a fo:block is for words which do not fit on one line to wrap to the next line and the height of the block to increase. If wrap-option="no-wrap" then words which do not fit on the first line are discarded if overflow="hidden".

See also overflow

Default value: "wrap"

Value

Notes

inherit

wrap

words wrap to the next line

no-wrap

words do not wrap to the next line

z-index

This attribute controls the positioning of one element over another. By default a more deeply nested element will appear over its container element but by changing the z-order you can change which elemnets appear over which other elements.

Default value: "auto"

Compliance with the XSL-FO standard

This chapter describes which extent to which Ibex supports the XSL W3C Recommendation 1.1 dated 5 December 2006.

Objects are listed grouped together in the same way in which they appear in the specification.

Declarations and pagination and layout formatting objects

ElementStatus
fo:rootimplemented
fo:declarationsimplemented
fo:color-profileimplemented
fo:page-sequenceimplemented
fo:page-sequence-wrapperimplemented
fo:layout-master-setimplemented
fo:page-sequence-masterimplemented
fo:single-page-master-referenceimplemented
fo:repeatable-page-master-referenceimplemented
fo:repeatable-page-master-alternativesimplemented
fo:conditional-page-master-referenceimplemented
fo:layout-master-setimplemented
fo:simple-page-masterimplemented
fo:region-bodyimplemented
fo:region-beforeimplemented
fo:region-afterimplemented
fo:region-startimplemented
fo:region-endimplemented
fo:flowimplemented
fo:static-contentimplemented
fo:titleimplemented
fo:flow-mapimplemented
fo:flow-assignmentimplemented
fo:flow-source-listimplemented
fo:flow-name-specifierimplemented
fo:flow-target-listimplemented
fo:region-name-specifierimplemented

Block-level formatting objects

ElementStatus
fo:blockimplemented
fo:block-containerimplemented

Inline-level formatting objects

ElementStatus
fo:bidi-overrideimplemented
fo:characterimplemented
fo:initial-property-setnot implemented
fo:external-graphicimplemented
fo:instream-foreign-objectimplemented
fo:inlineimplemented
fo:inline-containerimplemented
fo:leaderimplemented
fo:page-numberimplemented
fo:page-number-citationimplemented
fo:page-number-citation-lastimplemented
fo:folio-prefiximplemented
fo:folio-suffiximplemented
fo:scaling-value-citationimplemented

Formatting objects for tables

ElementStatus
fo:table-and-captionimplemented
fo:tableimplemented
fo:table-columnimplemented
fo:table-captionimplemented
fo:table-headerimplemented
fo:table-footerimplemented
fo:table-bodyimplemented
fo:table-rowimplemented
fo:table-cellimplemented

Formatting objects for lists

ElementStatus
fo:list-blockimplemented
fo:list-itemimplemented
fo:list-item-table-bodyimplemented
fo:list-item-labelimplemented

Dynamic effects: link and multi formatting objects

ElementStatus
fo:basic-linkimplemented
fo:multi-switchnot implemented, not relevant to PDF
fo:multi-casenot implemented, not relevant to PDF
fo:multi-togglenot implemented, not relevant to PDF
fo:multi-propertiesnot implemented, not relevant to PDF
fo:multi-property-setnot implemented, not relevant to PDF

Formatting objects for indexing

ElementStatus
fo:index-page-number-prefiximplemented
fo:index-page-number-suffiximplemented
fo:index-range-beginimplemented
fo:index-range-endimplemented
fo:index-key-referenceimplemented
fo:index-page-citation-listimplemented
fo:index-page-citation-list-separatorimplemented
fo:index-page-citation-range-separatorimplemented

Formatting objects for bookmarks

ElementStatus
fo:bookmark-treeimplemented
fo:bookmarkimplemented
fo:bookmark-titleimplemented

Out-of-line formatting objects

ElementStatus
fo:floatimplemented
fo:footnoteimplemented
fo:footnote-bodyimplemented

Other formatting objects

ElementStatus
fo:change-bar-beginimplemented
fo:change-bar-endimplemented
fo:wrapperimplemented
fo:markerimplemented
fo:retrieve-markerimplemented
fo:retrieve-table-markerimplemented

Copyright (c) 2002-2023 Visual Programming Limited