Chapter 2. A First Look at XSL-FO

CONTENTS

•  2.1 An XSL-FO Overview
•  2.2 Related Stylesheet Specifications
•  2.3 Using XSL-FO as Part of XSL
•  2.4 Shorthand, Short Form, and Inheritance

This chapter introduces the details of XSL-FO, including a look at XSL-FO markup and an explanation of how to produce print documents with XSLT and XSL-FO. You should have a basic understanding of XSL-FO processing by the end of the chapter, which will provide a foundation for learning the rest of XSL-FO.

2.1 An XSL-FO Overview

This section provides a high level view of XSL-FO and its major parts, describes the process of getting from source to finished output, and describes some of the available tools. It introduces some of the necessary concepts (which will be expanded on later) and some of the jargon.

The production process starts with an XML document that you have been given or that you have created: the source XML. You take that document and apply an XSLT transformation (using an XSLT stylesheet) to select parts or all of the document content, and it produces an output XML document that uses the XSL-FO vocabulary. Let's call this output document the XSL-FO stylesheet. The XSL-FO stylesheet formatting instructions describe how the content of the document should be laid out for presentation to the end user. The formatting engine interprets the XSL-FO stylesheet to produce formatted output, often PDF, T_EX, or some other print-ready form. This formatted document is then ready for use. This end-to-end process is shown in Figure 2-1.

Figure 2-1. The end-to-end process

Making this work requires some means of creating XML documents, an XSLT processor, and an XSL-FO formatter to produce the printer ready output. This may be a command-line tool, part of an editing suite, or a graphical user interface-based tool. This formatter needs the XSL-FO document as its input and produces some form of printable output. The only other tool you will need is a printer (or similar output device) if you want paper-based output.

You should use XSLT to generate your XSL-FO from source documents (described later in this chapter). To do that, however, you need to have some idea of what XSL-FO documents look like, so we'll start by looking at the result XSL-FO documents.

The XSL-FO document specifies page layout, page size, any headers and footers, margins and page numbers, etc. For example, the page specifications may be for A4 pages (or U.S. letter pages) of a certain height and width. The title page may be specified separately from the main content. Other pages may need separate specification. The bulk of the content of the document is likely to have a common layout. Any appendixes may need page numbers with letter prefixes, for instance, page A1 for the first page of Appendix A. You can do all this using the page specifications.

The XSL-FO document also specifies in detail how each piece of content should be formatted, for example, titles should be big, bold, and centered. This second aspect is the bulk of the work of the XSL-FO document author.

There are also some key supplementary tasks, including generating tables of contents, lists of figures, and perhaps an index. Building these features will require a combination of XSLT processing to extract the information and XSL-FO to format it.

Page specification is a two-part task. First, pages are defined in terms of size, margins, etc. These are called simple-page-master s. Then they are called up in a sequence, referred to as a page-sequence. The sequence might tell the formatter in which order to use the title page specification, the main page specification, and the rear matter page specification. Standard XML techniques relate one to another. Example 2-1 shows a very simple page specification, first defining a simple-page-master and then applying it to a small flow of text.

Example 2-1. A basic page specification

<?xml version="1.0" encoding="utf-8"?> [1]<fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format"> [2]<fo:layout-master-set>       <fo:simple-page-master       page-height="11in"       page-width="8.5in" [3]   master-name="only">          <fo:region-body [4]   region-name="xsl-region-body"             margin="0.7in" /> [5]   <fo:region-before             region-name="xsl-region-before"             extent="0.7in" />          <fo:region-after [6]   region-name="xsl-region-after"            extent="0.7in" />       </fo:simple-page-master>    </fo:layout-master-set> [7]<fo:page-sequence master-reference="only" format="A">       <fo:flow flow-name="xsl-region-body"> [8]      <fo:block >Some base content, containing an inline warning,            <fo:inline >Warning: </fo:inline>Do not touch blue paper,            a fairly straightforward piece requiring emphasis           <fo:inline font-weight="bold">TEXT</fo:inline>, and            some instructions which  require presenting in a different            way, such as <fo:inline font-style="italic">Now light            the blue paper</fo:inline>.          </fo:block>       </fo:flow>    </fo:page-sequence> </fo:root>

1. The document element in the fo namespace

2. The layout master, which wraps the page specification

3. The page specification with name only

4. The main body area of the page

5. The header area

6. The footer area

7. The page-sequence, which refers to the page specification

8. Some content, wrapped in blocks and inlines, which will appear in the output

As you can see, this isn't quite straightforward, but once mastered, any page specification can be reused. Twenty lines of XML can specify a page that is good enough to provide quality print output. The formatted output is shown in Figure 2-2.

Figure 2-2. Resulting output

In this example, note the use of regions. Three are used: xsl-region-before, xsl-region-after, and xsl-region-body. You can read these as header, footer, and page content. These regions separate these areas of a page. Once you have specified what you want in the header and footer, the focus will normally be on the body area.

Areas, blocks, and inlines are the basic building blocks of a page layout. As you look at a page, you could probably draw rectangles around the page boundary, each paragraph's boundary, a figure's boundary, and so on. Each provides what is termed an area (of the page), with lesser areas nesting inside greater ones. This nesting of areas is how the formatter lays out each page in turn, following your instructions in the XSL-FO document. The contents of each area are either blocks or inlines. Blocks are formed from paragraphs, lists, titles, images, examples, tables, etc. Within a block, inlines lay out the lines of text, with attributes specifying how the inline should be formatted, for example in bold or italics. In this way, the inlines build into blocks, which are built into areas, which form the pages you produce.

If you have ever used a desktop publishing tool, you may be familiar with the term text flowing . Conceptually, text is poured into areas, which form the pages. The text originates from your XML source document and the formatter does the pouring for you. When an inline area is filled, the formatter seeks the next piece of content (the next paragraph perhaps). A new area is created for the next piece of content. Similar transitions occur at the block level and page level. Any block can have margins, padding around it, and color and backgrounds applied to it, but all within the framework of these areas of the page through which text and images pour, flow, and fill.

The XSL-FO element set provides the stylesheet author with the tools of her trade. From the small example given earlier, you can see a few of these tools. Each is identified by the fo prefix, which is the namespace used for XSL-FO. This tells the formatter that they are instructions to be followed. Content within such an element is used by the formatter according to those instructions.

The fo:root element wraps the entire XSL-FO document. The fo:layout-master-set element specifies the page layout the formatter will use for your document. Each is identified by fo:simple-page-master and its attribute, master-name. The element fo:page-sequence tells the formatter when to start using a particular page master, when to stop using it, and when to change to another. The element fo:flow contains your content, primarily in the body region mentioned earlier. This relates back to the ideas of text flowing into areas. It is within this element that most of your time will be spent if you are writing XSL-FO or generating it with XSLT.

You'll need to be aware of the writing mode and what is termed progression direction (block-progression-direction and inline-progression-direction ). Had the specification been designed for Western use only, these would probably not be necessary. However, it is an international specification, thus, these terms are relative rather than absolute. The writing mode uses acronyms to specify the sequence of inline-progression-direction then block-progression-direction. It might be left to right, then top to bottom. I personally write lines of text across the page (inline progession), then lines continue down the page, top to bottom. This is abbreviated lr-tb (left-to-right, top-to-bottom). In this way, all combinations of directions can be specified for all languages.

The fo:block element performs a multitude of roles, from providing 36pt titles that are centered and bold, right down to holding the single bullet character used to visually identify a list item. Blocks build up into areas, adding to one another in the block-progression-direction. Other block-like elements include tables, lists, and images, which all act similarly.

Within a block, the fo:inline element specifies the formatting requirements when a line break is not needed, such as for a section of bold or italic text, or when a font change is needed.

Finally, at the atomic level, the fo:character element is available. Each character in this book takes up its own tiny area on the page; hence, chapters, paragraphs, and lines can all be broken down to this element when laying out a book.

When talking about blocks having a multitude of uses, it is appropriate to know just how each of these is provided by the single element. Attributes are used heavily to specify the formatting needed. In some cases, the number of attributes can make the element hard to find. How and when to use these attributes is the subject of much of the rest of this book.

2.2 Related Stylesheet Specifications

While XSL is a powerful set of formatting tools, it is far from the only option. XSL comes from a rich heritage of stylesheet development, and can be used with or in place of these technologies.

2.2.1 XSL and DSSSL

One of the originators of the W3C submission was James Clark, the initial editor of the W3C document. He worked on the Document Style Semantics and Specification Language (DSSSL) standard. The ISO/IEC 10179 document states that DSSSL provides the specification of document processing for two purposes:

1. The transformation language for transforming SGML documents marked up in accordance with one or more DTDs into other SGML documents marked up in accordance with other DTDs . . . .

2. The style language, where the result is achieved by applying a set of formatting characteristics to portions of the data, and the specification is, therefore, as precise as the application requires, leaving some formatting decisions, such as line-end and column-end decisions, to the composition and layout process.

From this, it's quite clear that XSL-FO falls into the second group, that of specifying the formatting of documents. DSSSL was designed with SGML in mind, whereas XSL-FO had XML in mind. The experience of DSSSL was a key input to XSL-FO.

You may be asking the obvious by now. Why not DSSSL? Why XSL-FO? Two very clear reasons are implementation and support. DSSSL has a small following for its single open source implementation, OpenJade, produced by a group of faithfuls who took up the development of Jade when James Clark ceased its development. The one commercial implementation is from Nextsolution (http://www.nextsolution.co.jp/English/index.html). They recently announced the release of Version 2.0. Their initial release followed Jade in 1998.

The one key advantage DSSSL has over the XSLT/XSL-FO combination is its full programming language support, often a complaint about XSLT. The Jade implementation is based on Scheme, one of the Lisp family of languages. (While it provides all the functionality of a full programming language, Scheme is not an especially popular language with the users of XML.) Another plus on the DSSSL side is that can produce Rich Text Format (RTF) as an output, as used in Microsoft Word. The downside to DSSSL is its limited implementation. OpenJade has not added sufficiently to the original product to make it comprehensive in its capabilities. A series of limitations, combined with a steep learning curve, have deterred many people. DSSSL has very few tutorials and a specification written for implementors rather than users.

With these issues holding it back, the future for DSSSL may be viewed as restricted. I may be wrong; I like Jade, and it has an active support list of perhaps 30 to 50 regular users who are always very helpful. I just can't see its adoption by a wider audience. One quote that amused me was, "If you put the world's DSSSL experts into one room, it would still leave room for the toilet."

The lessons of DSSSL have been learned. XSL-FO uses an XML vocabulary. It has taken three years to get where it is at the time of this writing (currently, Recommendation status). It fits beautifully with XSLT and XPath. Together, these three will be complete, will have multiple implementations, will initially satisfy early adoptors, and will have the potential to meet the needs of business-to-business transactions involving human access to XML-based information, as well as to meet the needs of the publishing industry.

2.2.2 XSL and CSS

High-quality print output may be just one modality that integrates with others to provide the write once, deliver anywhere promise of XML. The print document may have several siblings: some are delivered over the Web, some are summarized in a WAP message, and others are converted to synthetic speech. This maze of information is possible to navigate using the tools that adapt XML.

Remember that XSL-FO is compatible with W3C technologies for other media. There are many similarities to the properties that form a part of Cascading Style Sheets (CSS) and XSL-FO. This is deliberatly done by the W3C. The rationale for this, when looking from the stylesheet writer's perspective, is clear. Although the syntax is different, the terms and terminology are similar. When you read the recommendation, you will see many cross-references to CSS Version 2, along with direct quotes and nominal variations from it. The advances in CSS from basic web page styling through to the complexities of Versions 2 and 3 use many of the formatting statements of DSSSL adapted for CSS. This alignment of semantics helps the stylesheet author, reduces confusion, and reduces the effort in the transition. Those used to the strengths of CSS will only have to respond to the shift in syntax when moving to XSL-FO. XSL-FO has borrowed much of the semantics of CSS Level 2, adding to it and modifying it a little, as necessary.

The variation in syntax is significant. XSL-FO uses a regular XML vocabulary, whereas CSS has its own syntax. Consider the following bit of CSS in XML:

<element style="font-size:12pt;font-weight:bold">content</element>

XSL-FO would have this as:

<fo:element font-size="12pt"             font-weight="bold">content</element>

The similarities are clear. The shift to the syntax of XSL-FO will depend on the writer's familiarity with XML syntax. XSL-FO goes beyond CSS in many areas, adding features that are page based as opposed to screen based. One often-raised question is whether the major browser providers will ever have the capability of XSL-FO styling. This remains to be seen, although, there are some indications that client side XSL-FO styling may become a feature in browsers at some stage in the future. The specification does address screen output, so there is potential. Considering that the W3C recommendation is now published, XSL-FO has three open developments on-going, and two commercial developments that are nearly feature complete provide some indication of its potential, even before it's widely known.

I see XSL-FO as an exciting technology, providing much-needed functionality that can connect the staid office users with the newer uses of XML. If Tim Berners-Lee is right, and the Semantic Web becomes a reality, slowly intruding more into daily life, the need for automated print production from web-based information will increase exponentially.

2.3 Using XSL-FO as Part of XSL

This section looks at the integration of XSLT and XSL-FO. The two recommendations started out as one and, rightly, have a close relationship. I make the assumption that the reader has some background in XSLT.

An XSLT transformation defines a mapping from the source document structures to XSL-FO formatting. When run, the XSLT transformation produces an XSL-FO document that is then run through a formatter. Tools can combine these two steps either overtly or behind the scenes, but it's worth understanding what happens under the hood. The advantage of this two-stage approach is that content selection can take place in the first stage. Certain parts of the source XML document may not be wanted in the final printed form. These can be ignored by this first stage. In the same way, literal content can be added by the stylesheet (to save the XML source document author having to retype a long company name, for instance), that is then output into the XSL-FO document, along with content from the source document, and that becomes a part of the final presentation.

2.3.1 History

XSL and XSL-FO have suffered from some naming confusion, largely because of history in the W3C. Initially, what we are calling XSL-FO was simply XSL, the Extensible Stylesheet Language. It became apparent that two-stage processing of SGML or XML into a print format was necessary. The prevailing view was that these two stages should be combined into a single W3C recommendation. This was proposed to the W3C, and XSL was born. When James Clark first released a product based on the working draft of this recommendation, its immediate use was for a slightly different purpose.

Remember I said that the transformation from XML into XSL-FO was done by XSLT? Initially, it was done by what was then called XSL. It soon became obvious that XSL had a very clear and quite large market using the transformation aspect to take one XML document through to another XML (or XHTML) format. This usage was well received, as people began using XSLT to transform XML into web-viewable HTML, XHTML, or WML (for mobile phones). Indeed, having realized that this general transformation capability was extremely useful, many people simply started to ignore the original purpose of XSL and demanded more features in this transformation area. User demand to speed up the delivery of the transformation side, at the expense of the formatting side, increased to the point where the Working Group accepted the inevitable and split out what are now XSLT and XPath from what remained XSL. (Some people still refer to XSLT as XSL.)

This is the reason we refer to what is XSL as XSL-FO; the FO appendage refers to the formatting objects, which are central to the life of XSL-FO and also are the only part of the original XSL that discriminates it from XSLT, the transformation language. fo also happens to be the most common namespace prefix used for XSL-FO. This intimate bond between the two still remains. XSLT provides the necessary tools in the first stage of transforming XML into a paper-based deliverable of selection, combination, reorganization, and so on. XSLT can generate the table of contents and all the cross links, while XSL-FO generates the page and paper-based outputs.

Before we move on, I would like to clarify, from the stylesheet author's perspective, how XSLT and XPath relate to XSL-FO.

First, let's make it clear that the stylesheet author and the source XML document author may not be the same people. As tools are produced to introduce XML into the office, generating valid XML will become easier. Styling that source document is not a task for the office administrator coming directly from Microsoft Word. I have in mind a job description that might equate to that of the analyst: taking the styling requirements of the originator and turning them into a formatting specification that results in an XSL-FO stylesheet.

In an XML document, there are many ways different users may want information content presented. Take a company report, for example. The company CEO may only want the executive summary. Others may want all the financial information stripped out. This selection and reordering is the job of the combination of XSLT and XPath. XPath provides the means to select content, XSLT, the means to transform it into the vocabulary of XSL-FO. XPath specifies the parts of the source document on which to operate; XSLT specifies how the output vocabulary will be used. It's this powerful combination that makes it easy to select all chapter titles (XPath) and specify that they be indented, with dot-leaders prepending the page-number-citation (XSLT). The formatter (a part of an XSL-FO implementation) then takes the markers placed there by the transformation and works out the actual page numbers to replace the page-number-citation object.

The stylesheet author, therefore, needs a number of skills:

• An understanding of the source XML document

• An appreciation of page layout, which used to be the domain of the print industry

• An understanding of the ways in which XPath and XSLT can be used to select and reorganize source content

• A good understanding of how to turn a layout idea into XSL-FO (which this book will provide)

• An understanding of the capabilities of the formatter that will be used

• On the less technical side, the ability to translate the needs of the person who wants the high-quality output into the desired formatting specification

Only when the final document is completed will the average recipient understand the difference between what he requested verbally and what it actually looks like. That's the diplomatic aspect of the stylesheet author's job.

2.3.2 Page Layout, Blocks, and Inline Content

One stylesheet design aspect I found strange at first is worth explaining before we create our first stylesheet. The three fundamental aspects of styling are understanding the functions of page layout, blocks, and inline content.

Page layout is fairly straightforward. Any page has a physical size, margins on all four sides, perhaps some header content, maybe marginalia, page numbers, etc.

Blocks are a little less obvious. A single word could be a block, as could the title of a chapter. Any area of a page (regardless of its content) that is set apart from other content may be laid out as a block. This applies to paragraphs, titles, figures, tables, captions, and many other items. XSL-FO generalizes blocks to a high degree, providing flexibility to specify how they are formatted to meet user requirements.

Within blocks we often see lines of content, usually source document content. Some items within blocks are styled using inline formatting objects. A typical example might be the page number citation that we often see at the end of a line in the table of contents. Here, a number of items are wrapped in a block, each as an inline object. The chapter title, for instance, followed by a line connecting the content to the actual page number. The page number citation itself should not be split out onto a separate line, so it is marked as an inline object and, thus, is displayed in the same line as the title. This may sound odd to the HTML author accustomed to using the br element to break lines.

The lesson here is to get used to identifying and realizing the difference between true inlines and blocks. Figure 2-3 shows an interaction between a long inline in a set of blocks. Whether to use a block formatting object or an inline formatting object is a decision made early on.

Figure 2-3. A table of contents example

In stylesheet design, the appearance of a formatting object is specified by setting the properties of that object. These are specified as attributes of the XML formatting object element. There are a large number of properties from which to choose, which, can be used to determine such things as the level of indentation, the spacing around an object, the color to apply to an object's content, or whether to break a flow before or after an object. By using different properties, one block produces titles, and another produces the fine print we all love to hate!

2.3.3 Considering Compliance Levels

The principles of compliance discuss three levels: basic, extended, and complete. These are listed fully in Appendix D and relate to each property. No formatting engine has a complete implementation. Many implement the basic level and some, the extended level. It's easier for an implementor to implement the basics, but quite hard to implement even some of the complete! Basic elements include fo:region-body, whereas extended requires fo:region-before in addition. The former is required for any output, the latter, typically for headers, is considered an extended feature. A rule of thumb is that the shorthands are often not basic level properties, but other than that, it's necessary to look up the property.

If you are using a basic property, you will be far more likely to produce a stylesheet that is portable across implementations. If you need an extended property, fine; but if you can use basic properties, it will maximize interoperability. If non-portable stylesheets become the norm, we will be doing a great disservice to the acceptance of XSL in general. Be aware of which class of properties you are using, and the implications for portability.

The terminology of XSL-FO may seem strange at first. I will describe some of the stranger terms in plain English upon first use. Many of the terms are defined in the Glossary.

Although the XSL-FO recommendation fully specifies all the elements in the fo namespace, it doesn't show their relationship to XSLT. There are two main areas in which such an understanding is necessary: first, selecting content to format in a selected page, and second, matching XML source content markup with an appropriate element and its properties in the fo namespace. I will discuss each of these in turn.

2.3.4 Selecting Content for Formatting

The simplest file, perhaps of use for test purposes, is shown in Example 2-2.

Example 2-2. Minimal test file

[1]<fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format"> [2]  <fo:layout-master-set>       <fo:simple-page-master master-name="only">          <fo:region-body [3]                      region-name="xsl-region-body"                          margin="0.7in"  padding="6pt" />          <fo:region-before                            region-name="xsl-region-before"                            extent="0.7in"  />          <fo:region-after                           region-name="xsl-region-after"                           extent="0.7in" />       </fo:simple-page-master>     </fo:layout-master-set>     <fo:page-sequence [4]                  master-reference="only">       <fo:flow flow-name="xsl-region-body"> [5]           <fo:block>Hello World</fo:block>       </fo:flow>     </fo:page-sequence>    </fo:root>

1. fo:root, the main wrapper, stating the fo namespace required on all XSL-FO stylesheets

2. Page definition

3. The main content area of the page

4. The page specification to use for the body

5. The actual content to be laid out

Please don't be put off by the page specification part of this example. It's not straightforward, but it's common to simply reuse these parts of a stylesheet, because (for me at least) my paper size seldom varies, and margins, headers, etc. only rarely need modification. These parts soon become reusable boilerplates with occasional minor changes.

These elements are explained more in Chapter 3, so for now it is sufficient to say that the content should be matched at the:

<fo:flow flow-name="xsl-region-body">

element within the file.

How is this achieved using XSLT (and XPath, of course)? I'm presuming that the XSLT stylesheet is using a push model rather than the simpler pull model, so templates will be used to match content rather than simply selecting required content from a root template. The push model is rule based, where the output structure depends on the input structure and is typically used for transforming documents. The pull model, has an output structure independent of the input structure that uses the same approach as server pages. For this example, I'll take a very simple source document as shown in Example 2-3. This is no more than an outer wrapper of doc with section wrappers and simple para content.

Example 2-3. Source XML for the examples

<doc> <section><head> Simple sectioned title </head> <para>Some base content, containing an inline warning,   <emphasis role="warning">Do not touch blue paper</emphasis>,   a fairly straightforward piece requiring emphasis   <emphasis>TEXT</emphasis>, and some instructions which   require presenting in a different way, such as   <instruction>Now light the blue paper</instruction>. </para> </section> .... </doc>

The stylesheet to produce the basic outline of Example 2-3 is shown in Example 2-4.

Example 2-4. Basic stylesheet

<?xml version="1.0"?> <xsl:stylesheet version="1.0" [1]     xmlns:xsl="http://www.w3.org/1999/XSL/Transform"   xmlns:fo="http://www.w3.org/1999/XSL/Format">    <xsl:output method="xml"/> [2]<xsl:template match="/">     <fo:root>       <fo:layout-master-set>       <fo:simple-page-master         master-name="only">         <fo:region-body            region-name="xsl-region-body"            margin="0.7in"             />         <fo:region-before            region-name="xsl-region-before"            extent="0.7in"             display-align="before" />           <fo:region-after            region-name="xsl-region-after"            display-align="after"            extent="0.7in"            />       </fo:simple-page-master>       </fo:layout-master-set>       <fo:page-sequence master-reference="only">         <fo:flow            flow-name="xsl-region-body"> [3]         <xsl:apply-templates />         </fo:flow>       </fo:page-sequence>     </fo:root> [4]</xsl:template> </xsl:stylesheet>

1. Note the namespace usage, for both xslt and xsl-fo

2. The root template

3. Apply templates to the children of the document root

4. End of the root template

This is similar to an XSLT stylesheet targeted at (X)HTML output. The root template produces the basic outline, then makes use of apply-templates to process the children of the root of the source document. This is no different than processing XML through to (X)HTML, where within the root template, the elements html, head, and body are output. So this is a simple use of XSLT to start processing a source document.

Further processing takes place within other templates, processing more source content to produce output in the fo namespace. Example 2-5 shows two of these templates.

Example 2-5. Other templates

[1]<xsl:template match="section"> [2] <fo:block  id="{generate-id}">           <xsl:apply-templates/>     </fo:block>    </xsl:template> [3]<xsl:template match="head">     <fo:block       font-family="Times"       font-size="18pt"       font-weight="bold"       space-before="18pt"       space-after="12pt"       text-align="center">           <xsl:apply-templates/>     </fo:block>    </xsl:template> [4]<xsl:template match="para">     <fo:block       font-family="Times"       font-size="12pt"       space-before="12pt"       space-after="12pt"       text-align="justify">           <xsl:apply-templates/>     </fo:block>    </xsl:template> [5]<xsl:template match="emphasis[@role='warning']">       <fo:inline            color="red">Warning: </fo:inline>           <xsl:apply-templates/>    </xsl:template>

1. Template for the section element

2. An id that may be required for cross-referencing

3. Template for a heading

4. Template for a basic paragraph

5. Template for a warning notice

These templates (for a section that simply outputs a wrapper with an id value, a basic block for a paragraph, and a simple inline that outputs red text) are all simple examples showing how each template must produce well-formed XML. In the fo namespace, it might mean wrapping content or further processing content using XSLT's apply-templates, in the xsl namespace. These principles provide the basis of processing XML through to print.

2.3.5 Matching Source to Content

Now to look at matching content with elements in the fo namespace. For any element in the source document, it's necessary to decide what processing is needed to format it to the appearance needed in the print version.

Example 2-4 shows the processing for the root template, which contains mostly literals in the fo namespace, with a single application of further processing. Other candidates for this class of processing might include boilerplate warnings and cautions where the output is content not available in the source document.

Another class of processing is the feedthrough type of element. In Example 2-5, the processing of a section could simply amount to an apply-templates instruction, to process the children of the element. The section tag might require this. Typical applications for this class of processing are wrappers for content that provide structural integrity.

Finally, there are those elements that are wrappers for actual content, such as the para and emphasis elements in the example. Here, the decision is to select an appropriate element from a limited range of either block or inline containers. This is basically restricted to one from the following list:

• Block

• Inline

• List

• Table

• Graphic

So, for example, you would use a block for paragraphs, titles, and any other elements from the source document that require the construction of separated content in the block progression direction (down the page for Western output). These will be discussed in Chapter 3. Inlines are selected for emphasis, a font change, a change of color where the content is laid out in the inline-progression-direction at right angles to the block-progression-direction (along the line for Western output). Lists are a subclass of the block, as are tables. Graphics can be either inlines or blocks.

With these selections made, the remaining task is to specify the appropriate property set for that element, which is what the bulk of this book discusses.

Another class of processing is put to use by the index, table of contents, or cross-document links. Here, the problem domain is cross-referencing one piece of source document with another, repetitively selecting content to format with respect to its formatted position within the printed document. This is a repeat of its counterpart in the production of (X)HTML.

For the table of contents, the basic processing model is to select the point in the output at which the table of contents is required and call an appropriate template. The basis of the processing is shown next. I'll assume this processing is done early in the document. Having output any frontmatter, and before processing further children, a call is made to a named template that produces the table of contents as shown in Example 2-6.

Example 2-6. Out-of-line processing for a table of contents

<xsl:template match="/">  <fo:root>    <fo:page-sequence master-reference="only">        <fo:flow flow-name="xsl-region-body">        <!-- Produce the frontmatter here -->          <xsl:call-template name="toc"/> [1]     <xsl:apply-templates />        </fo:flow>      </fo:page-sequence>  </fo:root> </xsl:template> [2]<xsl:template name="toc"> [3] <xsl:for-each select="section">      <fo:block text-align-last="justify"><xsl:value-of       select="head"/> <fo:leader          leader-pattern="dots"/> <fo:page-number/> [4]   <xsl:for-each select="section">       <fo:block text-align-last="justify"> <xsl:value-of        select="head"/> <fo:leader            leader-pattern="dots"/> <fo:page-number />       </fo:block>      </xsl:for-each>     </fo:block>   </xsl:for-each> </xsl:template>

1. Produce the table of contents prior to processing the majority of the document

2. The out-of-line processing template

3. Process each section by formatting the head contents

4. Recursively process each section child to an appropriate depth

A more complete example of this is shown in Chapter 9. The principle is to select content from the source document and wrap it in elements in the fo namespace. This aspect demonstrates the real strength of mixing XSLT and XSL-FO. XPath selects the appropriate content from the source document, and XSL-FO provides the cross-references within the formatted document, in this case, page references.

I hope this has given you an idea of the strengths of this combination. Remember that together, these three recommendations provide a toolset that has the strength to re-order, select, and present source content in the way that the stylesheet designer wants.

2.4 Shorthand, Short Form, and Inheritance

The word shorthand in XSL is reserved for the CSS-compatibility shorthands in the complete conformance level (it's described in section 7.29 of the specification, Shorthand Properties). Setting all components of a compound property by omitting the component specification is termed a short form; it is not a shorthand and is part of the basic conformance level. More on compound properties is discussed in Chapter 4. As an example, the background property (except for a specification of border width, color, and style for all four borders) is derived from and aligned with a similar CSS property.

By whatever name we choose to call it, a shorthand is a time-saving device for specifying more than one property with a single statement. For example, section 7.29.3 in the specification defines the single property, border. The border property is a shorthand property for setting the same width, color, and style for all four borders top, bottom, left, and right of a box. Section 7.29 of the specification lists them all. The visual ones are shown here:

background	border-bottom
background-position	border-color
border	border-left
border-bottom	border-right
border-color	border-style
background	border-spacing
background-position	border-top
border	border-width

Note that each shorthand expands to specify other related properties. Also note that it will save you typing at a potential cost of not being implemented in your customer's formatter. Shorthand properties do not inherit from the shorthand on the parent. Instead, the individual properties that the shorthand expands into may inherit. For example, border is not inherited, but border-before and border-start are.

In XSL-FO, most properties are inherited from an area to the areas that it contains. For example, if the color property says that a block's text should be red, all the text in that block and other contained blocks will be red, unless a child area overrides that color property.

XSL defines a precedence order when multiple interrelated shorthand properties, or a shorthand property and an interrelated individual property, are specified. They are processed in increasing precision (for example, border is less precise than border-top, which is less precise than border-top-color). The individual properties are always more precise than any shorthand.

In general, you should stay away from shorthands that are only in the complete conformance level, because these can always be replaced with corresponding basic properties, are mostly there just for CSS compatibility, and will not always be supported by all implementations. If portability is an issue for you, this is important.

2.4.1 Inheritance

Using inheritance, I place common properties as high up in the FO tree as possible. Specification of common properties can be made once, rather than repeated throughout the document. This promotes correctness, maintenance, and legibility of the stylesheet and of the FO. This is both good practice and a good way to avoid errors.

Some of the properties applicable to formatting objects are inheritable. Those properties are identified as such in the property description in the specification. The inheritable properties can be placed on any formatting object. They are propagated down the formatting object tree from parent to child. (These properties are given their initial values at the root of the result tree.) If a given inheritable property is present on a child, the value of the property is used for that child and its descendants until explicitly reset. Hence, there is always a specified value defined for every inheritable property for each formatting object.

If all properties were explicit on all elements, the description would become too verbose even by XML standards. To constrain the amount of markup, the following expedient is introduced: certain properties may take their default values from the closest ancestor in the tree where the property is specified. For example, to specify a font family for a whole document, you can put a respective attribute on the root element. Any element with no explicit font-family will pick their values from there. This is common in typography and styling, which have similar mechanisms.

To make inheritance work, you must break the coupling between properties and elements that consume them. In XSL-FO, inheritable properties can be specified almost anywhere on the tree, not necessarily on elements whose formatting is influenced by them. For instance, leader-pattern is inheritable: therefore, specifying it on a fo:table will influence any and all fo:leaders inside cells of that table (unless a lower element redefines it to some other value).

Inheritance breaks the standard scheme of getting default values for attributes from a DTD or schema, a property used by an element may appear on any of its ancestors. Common sense and programming style are needed to avoid confusion. A DTD for XSL-FO has been provided. Its authors admit it is not 100% accurate, but it is useful.

Later in the book, I will use inheritance occasionally to reduce the amount of typing. I will note examples when they occur.

In summary, be aware of inheritance. It can be very useful to achieve a common style; on the other hand, if you ignore inheritance, it can trip you up with unwanted effects.

2.4.2 Tips on Using Inheritance

It is common practice to specify inherited values on flows and block-level elements. There is also a special fo:wrapper element that serves as a host to inherited properties. It is neither block-level nor inline-level, we can define it as a transparent property carrier. Use it to specify properties on a group of consecutive elements without introducing a fake extra area.

Don't abuse inheritance. When your stylesheets become complex, it may become hard to debug. Don't neglect another mechanism to assign identical properties to many objects for example, xsl:use-attribute-sets may be more appropriate than relying on inheritance.

Inherited properties are propagated down the object tree regardless of the respective area placement. This may sometimes lead to difficulties in styling your documents properly.

Out-of-lines (e.g., fo:footnote-body and fo:float) inherit properties from the content in which they occur. So, if a footnote happens to be located in an indented paragraph, it takes inherited values of all indents; if the text was red, the default color will also be red; if the text was a formula, the footnote may appear in Symbol font. Take care to explicitly predefine as many inheritable properties as possible at the top of your fo:footnote or fo:float element. There is no way in XSL-FO to assign a common set of properties to all footnotes; xsl:use-attribute-sets remains the only plausible alternative.

Indents are inherited universally. For instance, indents from fo:flow will carry to all cells in all tables, to all block and inline containers (even absolutely-positioned ones), despite the fact that these elements define a reference-area of their own that is different from the page-reference-area. In practice, this often leads to unwanted effects. When you try to adjust the position of a table by increasing its start-indent, the contents of each cell are shifted by the same amount inside the cell. Don't forget to reset indents to zero somewhere in the middle between fo:table and fo:table-cell; it is a good idea to add zero indents to fo:table-body, fo:table-header, and fo:table-footer.

There are more delicate things about inheritance, e.g., peculiarities of line-height behavior or font shorthand that silently resets a whole bunch of properties to their default values, which will be discussed later in their particular contexts. As a further observation, I'd also like to point out that markers take their properties from where they end up, not from where they started. These are discussed further in Chapter 9.

Before moving on, we need to understand compound datatypes. Certain property values are described in terms of compound datatypes. Every property has a datatype, which is the kind of information that it can hold, such as a color or a number. Some properties have compound datatypes, such as length or keep. The compound datatypes are represented in the XSL-FO result tree as multiple attributes. The names of these attributes consist of the property name, followed by a period, followed by the component name.

For example, a space-before property may be specified as:

space-before.minimum="2.0pt" space-before.optimum="3.0pt" space-before.maximum="4.0pt" space-before.precedence="0" space-before.conditionality="discard"

This notation may be familiar to those who have experience with object-oriented systems. It simply means that the space-before property has separate components that specify the optimum, minimum, and maximum values, and so on.

A short form of a compound value specification may be used in cases where the datatype has some length components and for the keep datatype. In the first case, the specification consists of giving a length value to an attribute with a name matching a property name. Such a specification gives that value to each of the length components and the initial value to all the non-length components.

For example:

space-before="4.0pt"

is equivalent to a specification of:

space-before.minimum="4.0pt" space-before.optimum="4.0pt" space-before.maximum="4.0pt" space-before.precedence="0" space-before.conditionality="discard"

It's a way of reducing typing (unless you want to explicitly specify limits). Note that short forms may be used together with complete forms; the complete forms have precedence over the expansion of a short form.

Compound values of properties are inherited as a unit and not as individual components. After inheritance, any complete form specification for a component is used to set its value.

2.4.3 Layout-Driven and Content-Driven Layout Types

The XSL 1.0 specification has a number of limitations that we will encounter throughout this book (and I will diligently strive to point them out). One of these pertains to the classes of document that are best suited for this version of XSL. It is possible to draw a fairly clean line between two primary categories of document: those that are layout-driven and those that are content-driven.

In the layout-driven case, a container searches the content flow to find matching content to put inside itself. In other words, the layout comes first. (A container is, loosely speaking, a region on a page that can accept content. Refer to Chapter 4 for more detail.) Typical documents in this category include magazines, newspapers, web pages, brochures, newsletters, catalogs, and presentations (slides and overheads). Content is often adjusted to satisfy the constraints of the layout.

In the content-driven case, the content itself identifies a model (think template), which, in turn, specifies the creation of suitable containers. As many containers (layout areas on pages) are produced as required to consume all the content of the document. Page layouts are usually relatively uncomplicated, and their selection is based on simple rules. Examples of this category of documents include books, manuals, technical documentation, articles, and documents driven by data. Content flows are sequential and unbroken. I find that XSL 1.0 is best suited for content-driven documents (page layout, blocks, and inlines).

These concepts and terms the three main divisions of any abstract document, and the distinction between layout-driven and content-driven layout are useful to keep in mind as we begin to discuss the highest-level structures in FO documents.

CONTENTS