A Gentle Introduction to XSL-FO

This para will contain background reading. Src

XSL (Extensible Stylesheet Language) is presently a W3C candidate recommendation that will augment the flexibility of the XML (Extensible Markup Language) standard. XSL is a far more sophisticated style language than is CSS. XSL draws on earlier specifications including CSS and DSSSL. According to the W3C's XSL page,

In other words, a stylesheet tells a processor how to convert logical structures (the source XML document represented as a tree) into a presentational structure (the result tree). Note that an XSL stylesheet is actually an XML document!

In terms of XML Namespaces, an XSL document uses <xsl:> and <fo:>, for transformations and formatting objects, respectively.

It is important to understand that the transformation part can be used independently of the formatting semantics. Common transformations include converting XML to HTML, changing the order of elements, and selectively processing elements. In fact, as of late 2000, most XSL implementations support only the transformation part of the Working Draft; they do not address the formatting objects at all! This may be confusing if you view XSL as mainly for rendering style. There are a number of implementations, which are listed elsewhere in this FAQ.

Having created a source document in XML with the intent of providing output in print, a two stage process is necessary to create that print. The first step is to transform the source document into XSL. The W3C recs which do this are XSLT and XPATH. These are used in combination to produce a document which conforms to the XSL working draft, and use a processor such as XT or Saxon, which implement these recs. The final stage is to use a processor which implements XSL, such as Renderxor Antenna Hosue or fop, to produce output ready for printing.

Transformation is the process of getting from a source xml document into another XML document which conforms to the appropriate vocabulary known as XSL. This process often re-arranges original sequences, introduces other material or ignores certain source content. For example, to automatically generate a table of contents or an index. It can be used to obtain various vocabularies, most typically HTML or XSL.

Rather than try to do it myself, might I refer you to an excellent series of slides by Norman Walsh. These may be found at Norms home page and provide a good introduction to transformation.

WARNING Most of this content is from the current Working Draft. Where I understand it sufficiently to translate into plain English, I have done. Where I haven't, you are seeing snippets from the Working Draft. Within that document there is a caveat which reads

Minimally (and not very usefully) this is the top few levels of the input xml to a fo processor which will deliver rendered output to either paper or screen. I'll explain each area further.

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


 <fo:layout-master-set>
			<-- defines the geometry and sequencing of the pages -->
                        <-- the pagination and layout specifications -->
   <fo:simple-page-master master-name="master-pages-for-all">
       <fo:region-body/>
   </fo:simple-page-master>

   <fo:page-sequence-master master-name="sequence-of-pages">
	    <fo:repeatable-page-master-reference master-name="master-pages-for-all" />
   </fo:page-sequence-master>
 </fo:layout-master-set>

 <fo:page-sequence master-name="sequence-of-pages">
   <fo:static-content flow-name="xsl-region-before">
	           <--provide the content that is static -->
                   <--within a page [e.g. Headers ] -->
   </fo:static-content>

  <fo:static-content flow-name="xsl-region-after">
	           <--provide the content that is static -->
                   <--within a page [e.g. footers] -->
   </fo:static-content>




   <fo:flow flow-name="xsl-region-body">
                   <--provides most of the content -->
                   <--of the document -->
	    <xsl:apply-templates/>
   </fo:flow>
 </fo:page-sequence>

</fo:root>

The major sections within such a document instance are described below

fo:root. The root element for XSL-FO.

fo:layout-master-set. Defines the geometry and sequencing of the pages which are contained in the document. Acts as a wrapper for these two.

fo:simple-page-master. Defines the size and shape of a page, the major regions into which the page is divided (main body, footer areas etc). There will be one of these (named) for each differing page layout. The master-name attribute or trait is used to identify it. It will be referenced indirectly from either a page-sequence-master element, or directly from a page-sequence.

fo:page-sequence-master. Specifies which simple-page-master is used at which time as the document is laid out by the renderer. This selection is based on the availability of content from the XML source, and the conditions specified in the attributes of the element.

fo:page-sequence. Wrapper for the actual content derived from the source XML document or entered by hand. For each variant (in terms of content) of a basic page layout, there will be one page-sequence.

fo:static-content. Static as in fixed location within a page, e.g. headers and footers, whether these are at the top and bottom or either side of a page.

fo:flow. Finally, the actual content to be laid out into the main page areas, the region named xsl-region-body.

To take each of these in turn. For those, like me, who hate learning a new set of jargon, I've done my best to clarify the terms used. Unfortunately it is hard to avoid it, and as the warning states, the working draft is not written for easy understanding.

The first specification then is for the size, orientation and shape of the page needed for a document type. Next is specified the sequence in which these masters are used, such as front-page, odd-page and even-page pairs, then back-page. This gives the physical paper size. Page decorations are specified in terms of header and footer content, including page numbers etc.

page-sequence elements have overall initial control of the formatter. As content is found from the XML document, a page layout is sought for that content. the master-name attribute is used to determine where to find that layout. This could refer directly to a simple-page-master, or indirectly via the page-sequence-master, which in turns works out which simple-page-master to use.

Page-sequence-masters have the role of describing the sequence of page-masters that will be used to generate pages during the formatting of an fo:page-sequence. They determine which page-masters are used and in which order.

For example, a sequence might begin with several explicit simple-page-masters and continue with a repetition of some other simple-page-master (or masters).

Which of the alternative page-masters is used at a given point in the sub-sequence is conditional and may depend on whether the page number is odd or even, is the first page, is the last page, or is blank.

<fo:layout-master-set>

<fo:layout-master-set> is the wrapper for both page masters and page sequences, Its children define the geometry and sequencing of the pages of a document.

<fo:simple-page-master>

<fo:simple-page-master> is the layout child of the layout-master-set. A simple-page-master is a master that is used to define the regions of a page into which content is flowed. If you want to rotate a page then this is where it is specified, using the reference-orientation attribute on one (surely all!) of the regions of the page. Rotation is specified in terms of a compass idea, with 0° being North, 90° is West, 180° being South, and 270° being East.

An fo:simple-page-master has, as children, specifications for one or more regions.

Page regions

The regions on the page are analogous to "frames" in an HTML document. Typically, at least one of these regions is of indefinite length in one of its dimensions. The viewport represents the visible part of the frame. The flow assigned to the region is viewed by scrolling the region reference-area through the viewport.

A page-master can consist of up to five regions: "region-body" and four other regions, one on each side of the body. These regions are named "region-before" "region-after" "region-start" and "region-end".

<fo:page-sequence-master>

<fo:page-sequence-master> is the sequencing child of the layout-master-set and has the role of describing the sequence of simple-page-masters that will be used to generate pages during the formatting of an fo:page-sequence. It determines which page-masters are used and in which order.

For example, a sequence might begin with several explicit page-masters and continue with a repetition of some other page-master (or masters).

Which of the alternative page-masters is used at a given point in the sub-sequence is conditional and may depend on whether the page number is odd or even, is the first page, is the last page, or is blank. The use of a repeatable-page-master-reference with an attribute of "maximum-repeats" property controls the number of repetitions. If this property is not specified, there is no limit on the number of repetitions.

Each fo:page-sequence references either an page-sequence-master or a simple-page-master, using the master-name attribute. If the reference is to a simple-page-master, this is interpreted as if it were a reference to an fo:page-sequence-master that repeats the referenced page-master an unbounded number of times. In plain English this means it keeps on using that layout until all the data it contains is laid out, i.e. exhausted. Use this option if there is no sequencing to be done with the content, for example in the case of a single page which is special, or any multiple sequences of pages which don't have any special requirements. Reference a page-sequence-master when you need to treat individual pages within a sequence specially, e.g. if you want the inner margins bigger than the outer margins, or other natural sequences which rely on conditions specified within the page-sequence-master.

fo:single-page-master-reference is used to specify a sub-sequence consisting of a single page-master.

There are two ways to specify a sub-sequence that is a repetition. The fo:repeatable-page-master-reference specifies a repetition of a single page-master. The fo:repeatable-page-master-alternatives specifies the repetition of a set of page-masters. Which of the alternative page-masters is used at a given point in the sub-sequence is conditional and may depend on whether the page number is odd or even, is the first page, is the last page, or is blank. The "maximum-repeats" property on the repetition specification controls the number of repetitions. If this property is not specified, there is no limit on the number of repetitions.

<fo:page-sequence>

This element is where the formatter goes to start the whole process.!

With yet more help from Nikolai, I think I now understand it a little better. I've used the example to describe how I went from an initial requirement to the contents of the file pages.xsl, which specifies the page layout.

Starting from the top. I want:

1st page special, a fancy front sheet.

Next few pages normal portrait, headers and footers - The Introduction and section 2

Next section, section 3, is landscape, two columns headers on the left, footers on the right.

Next section, section 4, portrait, two columns, headers back in their normal place.

Section 5 onwards, as per Introduction and section 2.

So, I need a page-master for each different layout. By layout I mean page dimensions (geometry), header and footer specifications in terms of borders and sizes (from simple-page-masters) and their content, from page-sequences. This means that since I don't want headers and footers on the first page, yet do on the second, I can't put them both in the same sequence, hence they have to use their own simple-page-master and page-sequence.

The logic behind my particular reasoning here is that I have a template match within an fo:page-sequence which selects a particular part of the XML source document. Thats the only reason I needed almost the same number of page-sequence elements as simple-page-masters.

Using the page-master master-name attributes I have:

first - fancy front page

rest - Introduction, section 3 and section 6.

twocolsP - Portrait two columns - section 4

twocolsL - Landscape two columns - section 5

To achieve this I need to use a mix of references to simple-page-master and page-sequence-master. I could have used direct references to simple-page-master only, but I wanted to include a page-sequence-master, so I have!

Why?

Listen carefully here, its a long story! This is the sequence the formatter goes through when you invoke it to lay out your pages.

In order to determine what content goes into which simple-page-master layout, The formatter follows the following logic, very much simplified, and thanks to Arved of fop fame (thanks Arved)

(1). Looks for the first page-sequence element in document order (This beast is not order independant!). Get the master-name from the page-sequence. If it refers to a simple-page-master, layout the content with page geometry from the simple-page-master. Keep on doing this until all data exhausted from the template-match in the page-sequence. When exhausted, try the next page-sequence in document order. Repeat from (1), using next page-sequence element

If it refers to a page-sequence-master (2) Take the first sub-sequence in the page-sequence master. (this could be any one of (single-page-master-reference| repeatable-page-master-reference| repeatable-page-master-alternatives)+

if the 'conditions' expressed in the sub-sequence are met * get the simple-page-master referenced from the sub-sequence and layout the content with page information from the simple-page-master. Keep on doing this until all data exhausted from the template-match in the page-sequence or the 'condition' * is no longer valid. if the 'conditions' are not met, move on to the next sub-sequence. and repeat from (2) using the 'next' sub-sequence.

WARNINGMoving on to the next sub-sequence (i.e. not using the same sub-sequence twice) only applies to this particular page-sequence. The 'counter' is reset to zero once a particular page-sequence is 'used up' and the formatter moves on to the next page-sequence.

* The conditions might be, for instance, odd, even, or first page; Number of pages specified in a repeatable-page-master-reference etc.

So having understood how it does it, here goes to determine the content of page-sequence-master(s)

For the fancy front page I refer directly to the page without headers and footers, named 'first'.

For sections 1 and 2 I need a - for remainder of section 1 and section 2. This is done using the simple-page-master named 'rest'.

This will be called up from the template match within the first page-sequence, using a match pattern of "/simpdoca/section[1]" The corresponding page-sequence-master will refer to the page-masters 'first'

For section 2 I need another page-sequence with match pattern "/simpdoca/section[2]" This will reference the second page-sequence-master, which will have content repeatable-page-master-reference, which will reference the 'rest' simple-page-master.

For section 3, just a single page, in the page-sequence I will refer directly to the simple-page-master twocolsL

For section 4, again a single page, in the page-sequence I will refer directly to the simple-page-master twocolsP.

For section 5, multiple pages, I will refer directly to the simple-page-master 'rest'

Phew. Did you follow the sequence there? You will need to when you need more than one different page layout! How about putting that table from chapter 5 on a landscape page :-)

fo:root  (layout-master-set,declarations?,page-sequence+)

fo:layout-master-set   (simple-page-master|page-sequence-master)+

See para 6.4.12 for a fairly clear description. Note especially the terminology used!

A simple start might be

	 <fo:root>
	  <fo:layout-master-set> 
	    <fo:simple-page-master
	    master-name="rest"
	    page-height="29.7cm" 
	    page-width="21cm"
	    margin-top="1in"
	    margin-bottom="1in"
	    margin-left = "0.75in"
	    margin-right="0.75in">

          <fo:region-body 
	    padding="4mm"
	    margin-top="0.6in" 
	    margin-bottom="0.6in"/>

	  <fo:region-before 
	    extent="0.5in"/>
	  <fo:region-after 
	    extent="0.5in"/> 
	<fo:simple-page-master>
....

This little lot had me very confused. Being a simple person, and not from the print industry, I guessed or assumed, that the header and footer go into the top and bottom margins. Nope. The header and footer as I think of them, are areas within the region-body, set aside in this example, by the margin-top and margin-bottom attributes of the region-body, into which fits the region-before and region-after 'extents'. I've deliberately made one smaller than the other to make this obvious. There are a number of diagrams in section 6.4.12 which show this. It didn't do me any good, but it may help you!

fo:region-body 

(common border padding and background, see 7.6) Lots of decorations, but complexity can be avoided! the following can be specified

background ~ color, image, repeating, position

borders ~ color, style, width

padding

margins

space-before and after

start and end indents

the number of columns

the gap between the columns

alignment

reference-orientation (0 | 90 | 180 | 270 | inherit)

How would you like it sir/madam? Remember that 0 is normal, top to top etc. 90 degrees rotation means rotated counter-clockwise! and

writing mode (defaults to left to right, top to bottom)

Quite a lot for a main region of a simple page master! A basic set without frills might be:

   
	    <fo:region-body 
	    padding="4mm"
	    margin-top="0.6in" 
	    margin-bottom="0.6in"/>

Auto alignment and overflow are managed by the renderer OS combination.

This latter is difficult, since in some circumstances a page can have clipped content which is only realised when an end user complains because the author hasnt' noticed it.

<fo:region-body overflow="visible"> is nice to have, but dependant on the implementation.

Simple page masters. 6.4.12

For a simple-page-master, with header and footer, the following example seems fairly clear

   <fo:static-content 
	 flow-name="xsl-region-before">          
	 <fo:list-block  
	   font-size="10pt" 
	   provisional-distance-between-starts="5in" 
	   provisional-label-separation="0in">
	   <fo:list-item>
	     <fo:list-item-label>
              <fo:block 
		 text-align="start">Document Title</fo:block><!-- Header left -->
	     </fo:list-item-label>
	     <fo:list-item-body>
	       <fo:block
                 text-align="end">Page <fo:page-number/> <!-- Header Right -->
                  </fo:block><
	       </fo:list-item-body>
	     </fo:list-item>    
	   </fo:list-block>
	 </fo:static-content>

This is the header. I've used the list format to obtain the seperation between left and right headers. The footer is the same, but using flow-name xsl-region-after.

The body is even simpler.

 <fo:flow flow-name="xsl-region-body"> 
    <xsl:apply-templates select="/simpdoca/section[4]"/>
   </fo:flow>

All this does is name the region its going into, and say what content you want in it.