Getting Fancy with FOP

ebster’s Dictionary defines a fop as being synonymous with a “dandy,” a person (usually male) who spends an inordinate amount of time and effort on dress and appearance, sometimes to ludicrous extremes. Think of the gold-chain-festooned white-polyester clad lounge lizard of the 1970s and you’ll get the basic idea. However, as with so many other terms, FOP has resurfaced with a different meaning?as an acronym for the Formatting-Object Processor, part of the Open Source Apache Project. The FOP processor performs an interesting stunt: it converts an XSL-FO file into an Adobe Postscript Description Format (PDF) file.

XSLT and XSL focus on data-centric and document-centric transformations, respectively, but they are related; You need both to create efficient document-to-print transformations. How do XSLT, XSL, and XSL-Formatting Objects (XSL-FO) fit together?

XSL-FO is a page description language. It’s a language specifically designed for working with fairly sophisticated page content; consequently, it can be surprisingly difficult to master well. Rather than coding XSL-FO documents manually it’s far better to create an XSLT document that will handle the transformation for you.

A Little XSL History
PDF files encode detailed information, font content and graphics within a single file, and have become a standard for document display, just as Postscript has become integral in the area of document printing.

The XSL-FO part, on the other hand, requires a little more explanation, as it is a format that many people think they know but really don’t. In the late 1990’s, as the XML standard was coming together, the W3C Stylesheet working group wanted to create a generalized page description language that would be able to convert an XML document into a presentation. Unfortunately HTML, even as XHTML, isn’t apt at detailed presentations, because the very features that make web browser displays convenient, such aslong scrolling panes of information, don’t fare especially well when split into individual pages.

For example, even simple elements such as headers and footers are problematic. Columns are difficult to format effectively. Specifying print dimensions can be frustrating, because the concept of “width” in a web page is very different from the same concept in most printed output. Finally, HTML is very imprecise, even using CSS positioning, therefore you must add proprietary extensions if you want the output to do more than vaguely resemble the quality of print-only media.

Therefore, the stylesheet group recommended an Extensible Stylesheet Language (or XSL) that would include two components – a descriptive language for formatting specific content, and a transformative language for converting XML into the descriptive language. As it turned out, the simpler of the two languages ended up being the transformation language, which, because it was originally deemed the less essential of the two tasks, was given the name Extensible Stylesheet Language for Transformations, or XSLT. However, as XML has become more data-centric, the role of XSLT as a mechanism for general transformations has become much, much more prominent, while the rest of the XSL specification was relegated to the background.

Eventually though, the XSL recommendation was released, in October, 2001?nearly two years after the XSLT recommendation. Because of the extreme prominence that XSLT has achieved, even though the recommendation is titled Extensible Stylesheet Language (XSL), the page-description portion of XSL is commonly called XSL-FO, where FO stands for Formatting Objects (hence FOP).

A Short XSL-FO Primer
XSL-FO is a page description language. It’s a language specifically designed for working with fairly sophisticated page content; consequently, it can be surprisingly difficult to master well. You won’t be throwing away your copy of Quark or Pagemaker any time soon?but don’t be surprised to see Pagemaker?also an Adobe product?generating XSL-FO eventually. Adobe is perhaps the prime mover behind XSL-FO, though IBM, Sun, Xerox, and other companies also helped author of the XSL Recommendation.

XSL-FO uses the fo: namespace, xmlns:fo = “http://www.w3.org/1999/XSL/Format”, to identify fo: elements contained within a element that acts something akin to HTML’s tag. The document then defines a set of “layout masters”, which can be thought of as templates for different page types, which set the dimensions and general characteristics of each specific type of page. For example, you could create two masters, one for the left page and one for the right, because such pages generally are mirror symmetric in terms of margins. A third master page might define a title page.

I created a very simplified (ad hoc) XML schema to describing the sample document included with this article (although you could easily use something like DocBook to do much the same thing). The schema isn’t the formatting code; it’s just a simple “logical” breakdown of the document (see Listing 1).

Author Note:: The sample document contains an early version of this article?there may be minor differences between the sample document and the final version.

The XSL-FO markup for this document can look a little intimidating, but it’s actually pretty straightforward. All XSL-FO documents begin with a that contains the markup and declares the fo: namespace

The next element should be a layout master set. This is a collection of masters that the document requires. For the current article, the name of this simple page master is (not surprisingly) “mainPage”, but it could be pretty much anything?the master-name attribute just provides a value to refer to the page master:

The page master defines the height and width of the page, as well as the dimensions of the margins. Note that the units involved can be any standard CSS units: inches (in), centimeters (cm), millimeters (mm), points (pt), etc. These dimensions are printer page dimensions?if you wanted to print to an 11×17 broadside, for example, you’d specify a page-height of “17in” and a page-width of “11in”. The margins define the actual “printable” area on that page, given as an offset from the page itself along the respective axis.

The page itself is then broken into three distinct areas?the region-before, used to set header information (such as the title of the article), the region-after, which holds footer information such as page numbers, and the region-body, which is the active area where the process inserts the body of the text. The margins here work relative to the margins defined by the page itself, with the extents giving the amount before or after the body that the headers or footers extend respectively.:

This defines one master, but it doesn’t tell the order that the master appears. You do that in the page sequence master, which can describe both single instances and repeating collections of pages. The “simpleDoc” sequence master in the following example consists of nothing but repeating page masters named “mainPage.”

After defining the page sequence master, you can begin adding content. For a given page sequence adding content involves both defining static content?content such as footers or headers that either do not change or change predictably (such as page numbers) across multiple pages?and flow content, which consists of the main body of the article. You should declare the static content for the header first:

         XML 10 Minute Solution: Getting Fancy With FOP

The master-name attribute in the element indicates that the page sequence should use the page master defined under page-sequence block just given. The element in turn sets the contents for the header (flow-name=”xsl-region-before”) or the footer (flow-name=”xsl-region-after”). Perhaps the most pervasive element in XSL-FO documents is the element. The element defines a block region, which is analogous to a block within CSS or a

element within HTML. A block defines a rectangular region of text, whether as a paragraph, a collection of paragraphs, a sidebar, a headline or any other layout element that has a bounding rectangle. The opposite of a element is an element, which places the contents of this block within the current flow structure. An element can be thought of as being analogous to an HTML element, or the CSS inline property.

A note about attributes. Many of the attributes you’ll see within both and elements may seem familiar if you’re used to CSS. A big reason for this is that these tags are CSS based, whenever possible. One useful way to envision XSL-FO is to see it a framework for applying CSS in a purely XML environment. The XSL-FO elements define specific entities?parts of pages, regions, or even sections within text?while the attributes basically provide the media description about how those parts look and act.

The footer demonstrates that static content isn’t really all that static:

      Copyright 2001 Cagle Communications --    Page

The footer content includes the element, which updates from one iteration to the next. The page-number is quite customizable, by the way, employing the same formatting convention that XSLT uses. For example, if you wanted to number elements by capital Roman numerals you’d add the format attribute to the element (note that you don’t add it to the element). Doing that would number the pages in the sequence I, II, III, IV, V, VI, etc., inserting the number at the position of the element.

The final (and arguably most important) part of the document is the region. This contains, for each page sequence, the region into which the template flows the body of text. Unlike static content, which you explicitly set to reside on a given page, the flow content flows from one page to the next, creating new pages when there’s insufficient space on the previous page. The vast majority of the contents within a element will consist of elements.

For example, Listing 2 contains a flow object that shows the title, subtitle, author, and the first paragraph of the article itself

   Getting Fancy With FOP         Creating Adobe Acrobat Files from XSLT and XSL-FO         by Kurt Cagle         Webster's Dictionary defines a fop as being synonymous    with a "dandy," a person (usually male) who spends an    inordinate amount of time and effort on dress and    appearance, sometimes to ludicrous extremes. Think of    the gold-chain-festooned white-polyester clad lounge    lizard of the 1970s and you'll get the basic idea.    However, as with so many other terms, FOP has    resurfaced with a different meaning—as an acronym for    the Formatting-Object Processor, part of the Open    Source Apache Project. The FOP processor performs an    interesting stunt: it converts an XSL-FO file into an    Adobe Postscript Description Format  (PDF) file.

Finally, the blocks may potentially contain in-line elements. An inline element, as mentioned earlier, is an element that is part of the flow of text. For example, in HTML the element is an inline element that sets the font-weight of the enclosed text to “bold”. In the article, rather than creating and elements, which give no real clue as to why they are bold or italic, I have instead three distinct inline elements: , for emphasis, and to easily create an angle bracketed element. For example, the document presents the element visually as:

<tag>

Note that the example given here is very simple?the full XSL-FO specification is more than 300 printed pages in length, and can be extraordinarily complicated. However, that size makes it robust enough to handle a wide variety of applications.

Creating XSL-FO Using XSLT
The full code to describe even a relatively simple XSL-FO document like this one can easily be overwhelming if you attempt to write the XSL-FO code by hand, especially because there’s a great deal of repetition. Ideally, rather than coding a FO document manually (which you should do once, but only once) it’s far better to create an XSLT document that will handle the transformation for you. Fortunately, such transformations are fairly easy to generate.

For example, the file createFOP.xsl contains the transformation for this document. The element declaring the stylesheet namespaces requires two namespaces?one for XML-FO and one for XSLT:

Additionally, set the method attribute of the so the stylesheet generates xml output (method=”xml”) and so the result has elements indented, and does not include the XML declaration.

The next step to create any kind of document navigator is to figure out how to handle unspecified children. For instance, while the stylesheet uses both the and elements, the XSLT handles them directly in the template that matches the element. To ensure that the content of these elements don’t just “spill out” to the output stream, the stylesheet supports a template matching otherwise untrapped elements or attributes and simply fails to pass them to the output stream. Text elements, on the other hand, usually do need to be passed to the output stream. The following set of match templates handles both of these problems:

The template match puts in most of the boilerplate code, including the page dimension definitions and the footer, header and body region. It attempts to match elements in the order that they are encountered (more or less) in the source document, though in general it’s a good idea to explicitly declare the ordering in the stylesheet itself.

: Copyright - Page

Much of the remainder of the stylesheet generates the appropriate

elements with the prerequisite attributes, and generally have the form:

The element instructs the XSLT processor to find all child elements, attributes and text blocks for the current node and apply the relevant transformation to them. Because the code for handling unknown XML elements already exists, if the stylesheet doesn’t explicitly handle a child element in the source, it simply passes the text of that unknown element into the output stream.

The one single contentious area in this stylesheet involved displaying XML code. XSL-FO does not have an element analogous to the HTML