Appendix B. Finding Your Way Aroundthe Specification

CONTENTS

Appendix B. Finding Your Way Aroundthe Specification

•  B.1 Overview

This description applies to the W3C Recommendation of October 15, 2001, found at http://www.w3.org/TR/xsl/.

At this URL, you will find various formats of the document. Unless you are lucky enough to be permanently connected, it's probably wise to have a copy on your desktop. For that purpose, the specification is provided in alternate formats, specifically, a single large file, a zip file, which splits up the HTML into a number of smaller files, and a PDF version, should you be brave enough to print it out, kindly provided by RenderX.

Within the main specification, you will find frequent (annoyingly so, in my opinion) references to http://www.w3.org/TR/1998/REC-CSS2-19980512/, the CSS2 specification. You should download that too. Each time you come across such a reference, if you are using a local copy on your PC, the link in the HTML will be to a web document. I resolved this by using a command line editor to change all the strings http://www.w3.org/TR/REC-CSS2/ to read ../CSS2. In other words, I made them local references. Do this for all .html files in the directory in which you have stored the XSL specification. In a similar manner, I have stored the CSS specification in the same root directory, hence, the ../CSS2.

Personally, I found it worthwhile to have a paper copy. I also had access to a double sided printer and binding facilities, which helped. You decide. The PDF produced by the RenderX stylesheets is good. All cross-references are to page numbers and section numbers, so it really is a joy to use, and sometimes the screen is just not enough, until we all have Annotea in place! Otherwise, the notes on the paper copy provides as good a place as any to keep your jottings.

B.1 Overview

First, the downside! This document is not meant for end users of XSL-FO. Its target audience is an implementor. For that reason, it is written in a style that is meant to be accurate, precise, and clear (to an implementor), rather than explanatory. Keep that in mind when you read it and you'll appreciate why its phrasing is so concise. To quote the specification, "This document is intended for implementors of such XSL processors. Although it can be used as a reference manual for writers of XSL style sheets, it is not tutorial in nature."

B.1.1 index.html

The index.html file is most useful for its table of contents and is hyperlinked to each of even the most minor sections. It is wonderfully complete, a real gem. My thanks to the XSL Working Group for this. Use it to find almost any aspect of the specification.

B.1.2 Section 1

Section 1 of the specification outlines what happens with the conversion process, XML through to print (and screen-based media). If you want the whole thing in perspective, this is the only chapter that deals at that level. It dives straight into the jargon of formatting objects, so don't expect an easy ride.

B.1.3 Section 2

This section appears as a waste of space, referring out to XSLT and also formally defining the fo namespace.

B.1.4 Section 3

This section introduces the process of formatting. Some terminology is introduced, areas are discussed, and then it moves on to a conceptual model of what happens. The XSL Working Group says what might happen, but carefully avoids telling an implementor just what to do. This avoids implementation conflicts. The specification is supposed to say what happens, not how to do it.

The rider here is that there are implementor interpretation conflicts; that is, the recommendation has been interpreted differently by different implementations. It will take some time (and probably a revision of the recommendation) to resolve this.

The formatting process is explained, in very broad terms, which is more than likely of little interest to the end user! Look to Section 4 for a pictorial model of the area tree introduced here.

B.1.5 Section 4

Section 4 begins to put some meat on the bones. Further terminology is introduced, and there is more on areas, with the introduction of block and inline areas block-progression-dimension and inline-progression-dimension. The majority of this section relates to the management of areas, specifying how any adjacent areas should resolve traits to produce the final output. The concept of conditionality (include or forget) is introduced, spaces are defined and resolved, and the layout of blocks and inlines are expressed in terms of their relationships to one another. Keeps and breaks (when to keep two areas together and when to break them) are defined and the final stages, converting to the final presented output, are discussed. Borders and padding are brought into the layout equation, explaining how they are added to content to offset one piece of content from another. This section provides clear definitions of the terms that may be creating problems for you.

B.1.6 Section 5

This section is one I rarely visit. Come here when you need to care about inheritance! The shorthand of XSL-FO is introduced (though not explained fully), and the section explains how actual final values of, for instance, indents and widths are calculated.

This section, for some reason I can't figure, explains units you'll come across. If you want to know how to specify a length, this is the section to which you should refer. The few XSL-FO functions are covered here as well, including the color functions. Compound data types, specified with a minimum, maximum, and optimum set of values are explained, including resolution.

B.1.7 Section 6

Section 6 starts with interesting material for the end user. Here, you will find the basic formatting objects defined in reasonably plain English, both with the detailed content you will use most and with the page level objects. The diagram in this section explains how to specify your pages in document tree form. I guess it was from this section that RenderX derived their document type definition that I find so useful.

This section is worth browsing to absorb the details of page layout, which are diagrammed and explained. Also included are the first examples in the specification. The common uses entries for each of the formatting objects are particularly useful. It won't tell you of the devious ways you can use some of them, but states their most common application.

This should be your starting point when you are trying to determine whether or not you can use a particular property. Look up the particular formatting object of concern and you'll find a full list of applicable properties. This is of particular application in the usage of tables and lists, which are not the most intuitive of structures.

This section is possibly the second most used section for the stylesheet author.

B.1.8 Section 7

Compared to the others, this section is home. When you want to find out about a particular property, you can either look it up in the table of contents and go directly to it, or use the table of contents at the front of the document.

My personal usage of this section is actually centered on the table of contents. I have highlighted the ones I repeatedly go back to because, due to its density of information, it can take a while to trawl through the list to find the one I want.

B.1.9 Section 8

This section provides the source of the compliance tables available for most of the processors. This section defines the three levels of conformance by which most of the implementations define their compliance.

B.1.10 Appendix A

This appendix addresses internationalization. It's worth a quick skim to find out the pains to which the XSL Working Group went to address an international audience.

B.1.11 Appendix B

This appendix is the other half of Section 8. It assigns each of the formatting objects to one of the three levels of compliance.

B.1.12 Appendix C

This appendix lists all the properties and candidate values. It's useful as a summary, and is fully linked to the section in which properties and candidate values are fully specified.

B.1.13 Appendix D

This appendix lists references made from within the specification. They are mostly hyperlinked to the web address where they can be found.

B.1.14 Appendix E

This appendix has a list of hyperlinks or page references to each of the properties.

B.1.15 Appendix F

This appendix lists the most recent set of changes.

B.1.16 Appendix G

This appendix lists the acknowledgments from the XSL Working Group.

CONTENTS