webarch.pdf

Formatting the WebArch document The WebArch document is authored in a dialect of XHTML. I say dialect because although its original sources are valid XHTML, they aren't quite the same XHTML that gets presented in the final specification. A series of transformations are applied to the sources. In order to produce the PDF, I decided to start with the transformed XHTML version of the specification, the document you view, not the original sources. In principle, transforming to XSL Formatting Objects is as straight forward as any other transformation. Starting with XHTML, you can see that most of the block structures are going to get transformed to fo:blocks and most of the inline structures are going to get transformed to fo:inlines. The tricky part is that FOFormatting Objects documents have a fair bit of preamble at the front. The preamble is where you tell the formatter the size and shape of each page; you have to create a template, called a “master”, for each kind of page that will appear in your document. If you've never thought about composition in these terms, it may be a little hard to get your head around it.

Setting up the page masters If you have a book nearbyFor the pedantic, a book written in a language presented left-to-right and top-to-bottom. Books with other orientations or writing directions will likely show analogous variation, though that is by no means true for all languages in all writing directions., pick it up and flip through it. While every page is probably different, odds are good that you will be able to find four different page layouts in the body of the book. First, left-hand (even numbered or “verso”) pages probably differ from right-hand (odd numbered or “recto”) pages. Look at the headers and footers, they are often mirror images of each other with, for example, page numbers in the outer corners of each page. Close inspection will probably also reveal that the margin on the “binding edge” of the page is a little wider than the margin on the other side. In many books, the first page of each chapter or section is different from both the left- and right-hand pages, perhaps having different or absent running headers or footers. The fourth layout style is for blank pages, if there are any. It is common for all chapters to begin on an odd page so if a chapter ends on an odd page, then a blank “even” page is inserted to force the next chapter to also begin on an odd page. Like the first page of a chapter, the blank page is often distinguished from other even pages by different or absent headers and footers. This is also the page that is sometimes annotated “This page intentionally left blank”. Each of these page layouts is defined by a “master” with a specific name. After all the individual page masters have been created, you have to create a page sequence master. In XSL FO terms, a document consists of one or more page sequences. Each page sequence has a master that is a collection of individual page masters. For the WebArch document, there's only one page sequence, but in a book there might be different sequences for front matter, body, and back matter. For WebArch, the page sequence master defines a master for the first page, for odd pages, for even pages, and for blank pages No, there won't actually be any blank pages, but I defined the master anyway. It doesn't do any harm..

Setting up the headers and footers We're now almost ready to start generating FO markup for the document content, but there's one more little hurdle. Every FO page has five regions, the main body region in the center where the document goes, and four more regions around the edges for top, bottom, left, and right material. The top and bottom regions are used for headers and footers. If you look at the stylesheet, you'll see that each of these regions in each page master has a name. As soon as we've started a page sequence, we'll refer to these regions by name and fill in their content. The formatter will use this “static content” in the appropriate place on each page. The content is static in the sense that content from the document doesn't “flow” into it. It can change on a per-page basis, as we'll see. Without going into a lot of detail here, if you look in the stylesheet, you'll see that I use tables to format the running headers and footers, placing the page numbers, for example, on the left side of left pages and the right side of right pages. Some masters, like the first page, have empty headers and/or empty footers. At this point we can “apply templates” on the body and our FO document will come out.

Also of note Two other parts of the stylesheet are perhaps notable: PDF bookmarks and the use of markers. Bookmarks will be a standard feature of XSL 1.1, but for the moment, I'm relying on a xep extension. Markers are more interesting. Markers provide a mechanism for adjusting the running headers and footers as you progress through a document. Think of the way that headers and footers change as you flip through a dictionary: markers let you do that. For WebArch, I decided to put the current first- or second-level section in the footer of each page. That way you can tell just where you are. It may prove to be more distracting than useful, but I figured there'd be no way to tell without trying it. Markers are easy to use. Whenever you output content that should appear in a header or footer, you output an fo:marker. In the static content for the appropriate header or footer, you use fo:retreive-marker. The formatter will replace the fo:retreive-marker with the appropriate fo:marker. Careful inspection of the stylesheet will reveal several places where I've taken care to avoid an obvious compositional faux pas like leaving a single list item on the top or bottom of a page or allowing a page break to occur immediately after a section title. Readers with design skill could certainly improve the presentation.