2.2 Examples
2.2.1 Hello world exampleConsider a simple, but complete, XSL-FO instance hellofo.fo for an A4 page report shown in Example 2-8. Example 2-8 A simple exampleLine 01 <?xml version="1.0" encoding="UTF-8"?> 02 <root xmlns="http://www.w3.org/1999/XSL/Format" 03 font-size="16pt"> 04 <layout-master-set> 05 <simple-page-master 06 margin-right="15mm" margin-left="15mm" 07 margin-bottom="15mm" margin-top="15mm" 08 page-width="210mm" page-height="297mm" 09 master-name="bookpage"> 10 <region-body region-name="bookpage-body" 11 margin-bottom="5mm" margin-top="5mm" /> 12 </simple-page-master> 13 </layout-master-set> 14 <page-sequence master-reference="bookpage"> 15 <title>Hello world example</title> 16 <flow flow-name="bookpage-body"> 17 <block>Hello XSL-FO!</block> 18 </flow> 19 </page-sequence> 20 </root> Note that all examples in this book illustrate instances of the XML-FO vocabulary. How an instance is created is not material to the semantics of the vocabulary. The instance could have been hand- authored in a simple text or XML editor, or created as the result of an XSLT transformation from another XML vocabulary, or generated from any other application. We can see the declaration on line 2 of the default namespace being the XSL-FO namespace, so all un-prefixed element names refer to element types in the XSL-FO vocabulary. There are no prefixed element-type names used by any of the elements, thus the entire content is written in XSL-FO. The document model for XSL-FO dictates that the page geometries must be summarized in layout-master-set on lines 4 through 13, followed by the content to be paginated in a sequence of pages in page-sequence on lines 14 through 19. This instance conforms to these requirements and conveys our formatting intent to the formatter. The formatter needs to know the geometry of the pages being created and the content belonging on those pages. Think of the parallel where we learned that the document model for HTML requires the metadata in the head element and the displayable content in the body element. Both elements are required in the document model, the first to contain the mandatory title of the page and the second to contain the rendered information. Once we learned the vocabulary for HTML, we can create a page knowing where the required components belong in the document. The same is true for XSL-FO, in that we learn what information is required where and we express what we need in the constructs the formatter expects. In this simple example the dimensions of A4 pages are given in the portrait orientation on line 8. Margins are specified on lines 6 and 7 to constrain the main body of the page within the page boundaries. That body region, described on lines 10 and 11, itself has margins to constrain its content, and is named so that it can be referenced from within a sequence of pages. The sequence of pages specified on line 14 in this example refers to the only geometry available and specifies on line 16 that the flow of paginated content is targeted to the body region on each page. The sequence is also titled on line 15, which is used by rendering agents choosing to expose the title in some application-dependent fashion (e.g. in a window's title bar). Consider two conforming XSL-FO processors that processed the simple hellofo.fo example as shown in Figure 2-7, one interactively through a GUI window interface, and the other producing a final-form representation of the page:
Figure 2-7. A simple XSL-FO instance example Note how the two renderings are not identical. If an XSL-FO instance is insufficient in describing the entire formatting intent, the rendering application may engage certain property values of its own choosing. Page fidelity is not guaranteed if the instance does not express the entire formatting intent. Even within the expressiveness of the XSL-FO semantics, there are some decisions still left up to the formatting tool. This is not different from two web browsers with different user settings for the display font. A simple web page that does not use CSS stylesheets for font settings relies on the browser's tool options for the displayed font choice. The intent of the web page may be to render "a paragraph," but if two users have different defaults for the font choice, there is no fidelity in the web page between the two renditions if the formatting intent is absent. 2.2.2 Training material exampleConsider a page of content from some instructor-led training material that contains a mixture of a table, a list, a proportionally- spaced paragraph, and monospaced paragraphs shown in Figure 2-8. Figure 2-8. A page of handouts rendered in XSL-FO Example 2-9 lists the first constructs in the flow that will produce the result shown in Figure 2-8. The information presented above the horizontal rule is rendered using a borderless table. Lines 1 through 15 describe the three columns of information: the page title and context, a placebo white box in place of the branding logo for the licensee of the training material, and the Crane registered trademark. The table cell with the page information contains text in different point sizes on lines 6 through 9. Example 2-9 Formatting objects (excerpt) for a page of handout materialLine 01 <flow flow-name="pages-body"><table> 02 <table-column column-width="( 210mm - 2 * 15mm ) - 2in"/> 03 <table-column column-width="1in"/> 04 <table-column column-width="1in"/> 05 <table-body><table-row><table-cell><block text-align="start"> 06 <block font-size="19pt">Training material example</block> 07 <block font-size="10pt" space-before.optimum="10pt">Module 08 1 - The context of XSL-FO</block> 09 <block font-size="10pt">Lesson 2 - Examples</block></block> 10 </table-cell> 11 <table-cell><block text-align="end"><external-graphic 12 src="url("..\whitesml.bmp")"/></block></table-cell> 13 <table-cell><block text-align="start"><external-graphic 14 src="url("..\cranesml.bmp")"/></block></table-cell> 15 </table-row></table-body></table> 16 <block line-height="3px"><leader leader-pattern="rule" 17 leader-length.optimum="100%" rule-thickness="1px"/></block> 18 <block space-before.optimum="6pt" font-size="14pt"> 19 This page's material as an instructor-led handout:</block> 20 <list-block provisional-distance-between-starts=".43in" 21 provisional-label-separation=".1in" space-before.optimum="6pt"> 22 <list-item relative-align="baseline"> 23 <list-item-label text-align="end" end-indent="label-end()"> 24 <block>-</block></list-item-label> 25 <list-item-body start-indent="body-start()"> 26 <block font-size="14pt">excerpts of formatting objects 27 created through the use of an XSLT stylesheet</block> 28 </list-item-body></list-item></list-block> 29 <block space-before.optimum="12pt div 2" font-family="Courier" 30 linefeed-treatment="preserve" white-space-collapse="false" 31 white-space-treatment="preserve" font-size="12pt"><inline 32 font-size="inherited-property-value(font-size) div 2">01 </inline 33 ><flow flow-name="pages-body"><table> 34 <inline font-size="inherited-property-value(font-size) div 2" 35 >02 </inline> <table-column column-width... Note how the attribute value specified on line 2 is an expression, not a hard value. There is an expression language in XSL-FO that is a superset of the expression language of XSLT. This can make an XSLT stylesheet easier to write by having it convey property values in a piecemeal fashion in an expression to be evaluated, rather than trying to calculate the resulting value in XSLT. The example shows a calculation involving the page width and twice the margins, less the width of the other two columns. A simpler alternative would be "100% - 2in" since the percentages at this point are calculated relative to the width of the region and not the width of the page. The horizontal rule below the title information needs to be block-oriented in that it needs to break the flow of information and be separate from the surrounding information. To achieve this effect with the inline-oriented leader construct, note how, on lines 16 and 17, the leader is placed inside of a block. Note also how the line height of the block is adjusted in order to get the desired spacing around the leader. The block on lines 18 and 19 lays out a simple paragraph. Lines 20 through 28 lay out a list construct, where the labels and bodies of list items are synchronized and laid out adjacent to each other in the flow of information. This side-by-side effect cannot be achieved with simple paragraphs; it could be achieved to some extent with borderless tables, but the use of list objects gives fine control over the layout nuances of a list construct. The list block itself has properties on lines 20 and 21 governing all members of the list, including the provisional distance between the start edges of the list item label and the list item body, and the provisional label separation. These provisional values are useful constructs in XSL-FO in that they allow us to specify contingent behavior for the XSL-FO processor to accommodate the start indent of the list label while maintaining the distance between the end of the label and the start of the body. Note: Remember one of the design goals of XML declared that "terseness is of minimal importance" (they probably could not have found a terser way of saying that)? Note that the attribute name specifying the first of these provisional property values is 35 characters long. It is not uncommon to need to use lengthy element and attribute names, and XSL-FO instances always seem to me to be so very verbose to read, though I admit they certainly are not ambiguous. Note how, on lines 23 and 25, functions can be used in attribute values. XSL-FO defines a library of functions that can be invoked in the expression language. The label-end() and body-start() functions engage the appropriate use of one of the two provisional list construct properties based on the start indent of the item's label. Line 29 begins the block containing the listing of markup. To ensure a verbatim rendering of edited text, line 30 specifies that all linefeeds in the block of content must be preserved, and white-space characters are not to be collapsed . This disengages the default behavior of treating linefeeds as white space and collapsing white space to a single space character, as would be typical for proportional-font paragraphs of prose . Lines 31 and 32 show an inline sequence of text being formatted differently than the remainder of the text of the block. The desired effect of the line number being half the current font size is achieved through the use of the function " inherited-property-value(font-size) ", though there are two alternate ways of specifying the same relative value: " 50% " and " .5em ". Using any of these expressions would produce the same result. The escaped markup on lines 33 and 35 may look incorrect, but this is an XML serialization of the XSL-FO instance, hence, sensitive markup characters must be escaped in order to be recognized as text and not as markup. Since this is a page describing markup, the markup being described needs to be distinguished from the markup of the document itself. The nesting of the hierarchy of the formatting objects is shown in Figure 2-9. Figure 2-9. The nesting of XSL-FO constructs in the example  |
