page 175
are also converted to hyperlinks. If your machine is connected, and you have a recent version of the Adobe Acrobat Reader, you can click on the web site and go directly to it.
Figure 9-8. First page of the tutorial PDF file
Pages in the body of the tutorial feature the text and illustrations of each panel, with a horizontal line between panels. The first panel of each section starts on a new page.
Figure 9- 9
shows the layout of an individual panel in the PDF file.
Figure 9-9. PDF layout for an individual panel
To accommodate our worldwide audience, we create letter-sized and A4-sized versions of the PDF file. We use the same stylesheet for each PDF file; we simply change the page
dimensions and let the Formatting Objects to PDF FOP tool generate the line, column, and page breaks for us. We are responsible for creating the formatting objects the FOP tool needs
to do its work.
page 176
9.4 XML Document Design
Now that weve covered how our tutorials appear in all their various forms, well discuss the structure of the XML documents that become our tutorials. To start with, we used some
obvious structural principles:
•
A
tutorial
should contain a single
title
and one or more
section
s.
•
A
section
should contain a single
title
and one or more
panel
s.
•
A
panel
should contain a single
title
and a
body
, which in turn contains the markup for the panels contents.
This foundation creates an XML structure identical to the layout of our tutorials, so it was an obvious place to start.
9.4.1 Individual Panels
An individual panel has the following structure:
panel titleTitle of the paneltitle
body image-column
text-column Basic HTML markup p, ol, li, b, i, u, a, etc.
text-column body
panel
The
image-column
element is optional; its used to define the image that appears on the left side of the panel. We intentionally kept our markup design simple so that rendering the
tutorials would be relatively straightforward. Although this approach is heavy-handed, it does allow us to enforce a certain amount of consistency in the layout of our tutorials. Reusing
common HTML tags inside the
text-column
element allows authors to use the tags they already know and love, and it simplifies the XML-to-HTML transformation.
9.5 XSLT Source Code
Now that weve discussed the design issues we went through as we defined our XML document structure, well talk about how our XSLT stylesheets transform XML-tagged
tutorials into the files we want.
9.5.1 Stylesheets and Modes
To start with, we use the XSLT
mode
attribute to process the same set of nodes several times. Our template for the root element is similar to a Java or C++ program whose
main
method contains nothing but subroutine calls:
xsl:template match= xsl:apply-templates select=tutorial mode=build-main-index
xsl:apply-templates select=tutorial mode=build-section-indexes xsl:apply-templates select=tutorial mode=build-individual-panels
xsl:apply-templates select=tutorial mode=generate-graphics xsl:apply-templates select=tutorial mode=generate-pdf-file
xsl:with-param name=page-size select=letter xsl:apply-templates
xsl:apply-templates select=tutorial mode=generate-pdf-file xsl:with-param name=page-size select=a4
xsl:apply-templates xsl:apply-templates select=tutorial mode=generate-zip-file
xsl:template
page 177
If this were a Java program, we might create a
main
method that looks like this:
public static void mainString[] argv {
buildMainIndex; buildSectionIndexes;
buildIndividualPanels; generateGraphics;
generatePDFFileletter; generatePDFFilea4;
generateZipFile; }
This style of coding facilitates maintenance; if the PDF files arent generated correctly, the templates with
mode=generate-pdf-file
are the obvious place to start debugging. In addition, we structured the files so that all the templates for a given
mode
are in a single file that can be included into our main stylesheet:
xsl:include href=toot-o-matic-variables.xsl xsl:include href=xslt-utilities.xsl
xsl:include href=dw-style.xsl xsl:include href=build-main-index.xsl
xsl:include href=build-section-indexes.xsl xsl:include href=build-individual-panels.xsl
xsl:include href=build-graphics.xsl xsl:include href=build-pdf-file.xsl
xsl:include href=build-zip-file.xsl
In addition to the obviously named files, the file toot-o-matic-variables.xsl defines several global variables used throughout the stylesheets, xslt-utilities.xsl is a library of generic
routines substring replacement, for example we use, and dw-style.xsl defines the look and feel of our HTML pages.
9.5.2 Initializing Global Variables
Its worth discussing the global variables initialized in toot-o-matic-variables.xsl. All of these variables are used throughout our various stylesheets, and initializing them saves us a
significant amount of processing time. The most significant variable is
mouse-effects
. This variable is an automatically generated segment of JavaScript code used to process mouseover
effects on all the HTML pages we generate. Heres how the generated code looks:
-- var emailAbstract=developerWorks is proud to present the Toot-O-Matic,...; var justTitle=Building tutorials with the Toot-O-Matic;
var tutorialPrereqs=http:www-4.ibm.comeducationtootomatic; var menu1blurb=Installing and configuring Toot-O-Matic;
var menu2blurb=Creating your first tutorial; var menu3blurb=developerWorks editorial guidelines;
var menu4blurb=Toot-O-Matic tag guide; var menu5blurb=Toot-O-Matic tag reference;
var menu6blurb=Troubleshooting; var menu7blurb=Feedback;
var browser = x; if navigator.userAgent.indexOfMozilla4 = -1 browser = N3;
else if navigator.userAgent.indexOfMozilla3 = -1 browser = N3; else browser = x;
if browser==N3 {
var menu1over=new Image108,68; var menu1out=new Image108,68;
var menu2over=new Image108,68; var menu2out=new Image108,68;
var menu3over=new Image108,68; var menu3out=new Image108,68;
...
