W3C Candidate Recommendation 21 November 2000

Author Dave Pawson, http://www.dpawson.co.uk

December 2000

This document is still being developed. Please be patient!

What I'm trying to do is develop some fairly easy to understand pages which demonstrate how to achieve certain layout styles, using XSL-FO. These files, XML, XSL (main and pages) use fairly simple template matches on various paragraphs and sections of the source document to show how to achieve a range of visual effects. You will need to read both the stylesheets, and look at the XML source to see how it all fits together. These files are linked from near the end of this page.

The messy bit at the moment, December 2000, is the pages.xsl stylesheet, which is included from the main stylesheet. I show how sections of the source document, can be laid out landscape (please excuse the Western orientation) in two columns, section 4 is laid out portrait in two columns, and the remainder of the document is normal portait layout. The file has quite a large amount of comment which should help with usage.

The file pages.xsl contains two main elements within the main fo:root element. Remember that this file is included with the remainder, so you can ignore the stylesheet element. The primary ones of interest are:

fo:root fo:layout-master-set fo:page-sequence /fo:root

The layout-master-set is the bit where you say how big your paper is, and how big the margins are. This is the page-master element. You will need one of these for each different page class you want to be created. I've created one for the front page, one each for portrait and landscape two column, and one for the rest of the document. It also contains any sequencing of pages, using the page-sequence-master element(s). I haven't seriously used that yet (December 2000). The fo:page-sequence element(s) - I have used this extensively - tell the processor what you want to put on the pages. I've used a named template since this is very repetative. Basically thats it for this document. The details are messy, but thats it in outline.

The rest of this document is a series of elements which demonstrate various things you can do with XSL-FO. In order to use it, there could even be some system of approach.

First para which is without any embellishments. No attributes set, simply an fo:block encapsulating the content.

This paragraph is indented as a whole, using the text-indent attribute. This pushes the whole paragraph over by the amount specified.

This paragraph is isolated from its preceeding ones using the space-before attribute. There are three values specified, space-before.minimum, space-before.optimum and space-before.maximum. There use is as their name. The distance should preferably be the optimum, and in any case no less than the minimum nor more than the maximum. Minimally use the space-before.optimum. Additional related aspects are space-before.precedence and space-before.conditionality. The default initial values are space.minimum=0pt, .optimum=0pt, .maximum=0pt, .conditionality=discard, .precedence=0. The precedence tells the processor how important it is to you, the author and the conditionality, which can take values of retain or discard.

This is commonly known as a hanging paragraph. It is obtained by specifying two attributes, the start indent and a negative text-indent. The result is that the first line hangs out over the remaining lines, which have the similar characteristic to the previous paragraph. Just for the sake of clarity, I also use a previous attribute with this paragraph, as I shall with all following ones. Done via the use of xsl:use-attribute-sets="para", which I hope you will come to enjoy using, since it encapsulates the depravity of XSL and its wealth of attributes. In setting up basic parameters for the fo:block element in an attribute set I can then re-use it, and modify it, with one single change.

Just to show that it can be done, this one has an end-indent set, one inch from the right side of the body region. Thats one imperial inch. Just to show that it can be done. Just to show that it can be done, this one has an end-indent set, one inch from the right side of the body region. Thats one imperial inch. Just to show that it can be done.

This set of paragraphs shows the alignment capability of XSL. This one has no specification for alignment, hence it aligns towards the start side, which for lrtb, left to right, top to bottom, is the left side of the page.

This paragraph has the text-align attribute set to end. Hence its attributes read text-align="end" xsl:use-attribute-sets="para". This should show the capabilities with respect to the right margin. I had to add some padding to the end direction simply to make it stand off from the right border. This attribute is specified with padding-end="6pt"

This paragraph is centred. To show it up, its not very long.

When I fill out the paragraph with more text, the effect is less noticable, other than at the margins of the text. Sufficient text with an appropriate length could produce an effect which is little different from a left justified paragraph. A litte more does show it up.

Justified text shows up even better when it is squeezed up with an indentation at the start and end. Thats what is added to this paragraph to enable justification to be exemplified. I added start-indent="0.5in" end-indent="0.5in" to this one to show it up.

In order to show up padding, I'm using a border around the block. This is set with the attributes border-color="blue" border-style="solid" border-width="0.5pt". Again I use an attribute set for this.

This paragraph has the general attribute padding set to 12pt. This paragraph has the general attribute padding set to 12pt. This paragraph has the general attribute padding set to 12pt. This paragraph has the general attribute padding set to 12pt. This paragraph has the general attribute padding set to 12pt.

To block a paragraph out as being laid out as one might for a quote, a number of options are available. Its possible to modify the start-indent, end-indent. This paragraph is set off by modifying the border-start and border-end properties. Initially I simply did that, and noticed no effect. It works as shown when I created an invisible border, by specifying border-style and border color, which I set to white, hence it doesn't show. For appearance sake, I've added a text-align="justify".

A word of caution. Be aware of the spec at para 5.3.2

The formulae for calculating the computed value of the "start-indent", and "end-indent" properties are as follows (where "margin-corresponding" is a variable for the corresponding absolute "margin" property): end-indent = margin-corresponding + padding-end + border-end-width start-indent = margin-corresponding + padding-start + border-start-width If an absolute "margin" property is not explicitly specified, these equations determine a computed value for the corresponding "margin" property given values for the three traits corresponding-indent, padding-corresponding and border-corresponding width.

What this means is that although in normal word processing applications, the start-indent may simply add padding to the start of some content, its slightly different in XSL-FO. The total value of the indent from the margin to the start of actual content is called the start-indent, but is made up of space-start, border-start and padding-start. Therefore, (in "lr-tb" writing-mode) margin-left = start-indent - padding-start - border-start-width. Think about that one. The stylesheet for this para does not have start-indent set, it simply augments the padding start at the start and end points, leaving the start-indent to be calculated. Until I learn a better technique, I'll stick to this method of indentation.

Finally this is a simple paragraph with a start-indent and end-indent set to one inch, simply adding the para attribute set to show this form being done this way.

This para has the properties suitable for a pre-formatted output. The shorthand version is white-space="pre", the fuller version is wrap-option="no-wrap" white-space-collapse="false" linefeed-treatment="preserve"

This para uses a different combination. The white-space property is set to nowrap,

whereby whitespace is not respected, and new elements used to provide line breaks,

There are quite a few variants on the in-line element theme. I simply want to provide enough to interest you in what can be done, then to go and read the WD to find out what else can be done.

This block of text is decorated in various ways. The first one is , followed by , , (called overline) and - which happens to be called line-through for some strange reason. And it is a text-decoration attribute. I've changed the line-height property on the overline inline element, just to show it up more clearly. You may realise that no mention has been made of fonts. I guess that you can figure that out for yourself. Just to show that it can be done

his is simply to show that font size is easy to change. There are numerous way of arranging the manner in which the varieties of text can be arranged.

Fonts can be changed using the font-family attribute on either a block or an inline element, for example or , and . Then we can use monospace

Plain straightforward lists aren't too bad.

The Structure is unusual, to say the least, having a number of wrapper elements.

The outer wrapper is fo:list-block.

Next in is a fo:list-item, for every item.

Then each item has a two part wrapper, of fo:list-item-label and list-item-body. These are seperate children of fo:list-item. Note also that the actual list item contents needs a block wrapper.

Remember:

<fo:list-block>

<fo:list-item>

<fo:list-item-label>

<fo:block>&#x2022; (•)</fo:block>

</fo:list-item-label>

<fo:list-item-body>

<fo:block> Whatever is in the list</fo:block>

</fo:list-item-body>

</fo:list-item>

</fo:list-block>

Note that I've used the Unicode value for the bullet, which is code point 2022 hexadecimal.

So thats the simplest form of list. No seperation, nothing fancy, just a plain bullet marker. In the example given above, I've simply indented it, using the start-indent property on the fo:list-block.

Remember good old XSLT? Thats where your numbers come from.

Nested lists are just as simple. Nest them as lists within list items.

Numbering with nested lists is a little trickier. All that is needed is the depth, for single level numbering, is to use the form <xsl:number level="multiple" count="litem" from="list"/>. Alignment is done by the formatter. Simple.

We can get fancy with lists, using the various seperation attributes. See the XSL-FO specification, Extensible Stylesheet Language (XSL) Version 1.0 W3C Candidate Recommendation 21 November 2000 § 6.8.1., where you will find a diagram explaining all the various distances you can play with.

For Tables of contents and things, leader lines are rather nice to have, to aid the user in aligning content with page numbers.

This is achieved using an empty element, <fo:leader />

For tables of contents or indexes, where page references are used, try <fo:leader leader-pattern="dots"/> <fo:page-number-citation ref-id="intro"/>, or whatever the page-number is that you want to refer to. The example below shows this in use. Note that for the very first section, I've added an id value to the fo:block which is first generated. This now reads <fo:block id="intro". This is done in the stylesheet, not in the XML document. But you knew that, didn't you? In order to make this more source related, you could use the id value of the source document by doing the following:

<xsl:if test="@id='intro'"> <fo:block id="intro"/> </xsl:if>

I've used ordinary dot leaders, which may appear as a solid line until magnified by zooming in, if you are not printing this.

Markers sort of wrap content for later use in headers. As of today I can't get them to work. I'll try and find out more.