Make It Easier to Create Tutorials

page 170 step was typically to create a PDF version of the tutorial. High-quality printable versions of our tutorials are popular, and its easy to create them from a single formatted document in Microsoft Word. Once that was done, we would convert the tutorial document into a single HTML file. We would then take the file, break it into small pieces, and add the standard IBM header and footer to each small piece. This step gave us a number of HTML files usually 50 to 100 that we needed to link together. In other words, if you look at the third panel in a section, clicking Next should take you to the fourth panel, and clicking Previous should take you to the second panel. We also needed to create a menu panel; from the menu panel, you can link directly to the first panel of any particular section. Finally, each panel had mouseover effects that had to be tested. While the writer and editor worked on the actual content, our graphic designers created artwork for the titles of the sections and for the tutorial itself. It was important that the heading text look a particular way, so our designers created graphics that contained that text, drawn on the appropriate background. For some titles, both plain and highlighted versions were created for the mouseover effects. Clearly, much of the tutorial-building process was hand-coded and error-prone particularly when we were feverishly finishing a tutorial at 5:30 in the morning so it would be on the site by sunrise. We wanted to automate as many of these steps as we could, to save us time and minimize the chance of errors.

9.2.2 Show Our Audience That We Use the Technologies We Advocate

Another goal was to actually use the technologies we espouse. We were certainly aware of the irony of a site that promotes open, standards-based computing creating content with a closed-source, proprietary tool, such as Microsoft Word. One attraction of building tools from XML documents and XSLT stylesheets was that it enabled us to show the world that XML and XSLT can do useful work today. Choosing these technologies to manipulate structured data was a no-brainer for us.

9.2.3 See Just How Much We Could Accomplish Through Stylesheets

Our final goal was to see how much we could do with XSLT. As youll see, we exercise all the advanced capabilities of XSLT in the Toot-O-Matic, including multiple input files, multiple output files, and extension functions. Through our stylesheets, we convert an XML document into: • A web of interlinked HTML documents • A menu for the entire tutorial • A table of contents for each section of the tutorial • JPEG graphics containing the title of the tutorial and each of the individual sections • A letter-sized PDF file • An A4-sized PDF file • A zip file containing everything users need to run the tutorial on their machine page 171 As well discuss, creating all of these things through stylesheets required us to push XSLT to its limits. The design of the XML document allows us to manipulate the information for a tutorial in a variety of sophisticated ways, and the structure of our stylesheets makes it easy for us to change the look and feel of our tutorials without having to modify the original XML content. In addition to these goals, we decided to make the XSLT stylesheets and the necessary extensions open source. We did this so our readers could see what we were doing to eat our own dog food, and to see if tight integration with a standards-compliant stylesheet processor would allow us to use existing tools to generate tutorials in a semi-WYSIWYG environment.

9.3 Tutorial Layout

Before we talk about the details of the XML document design and the XSLT source code, well review the actual HTML, zip, and PDF files we need to create. One advantage we had in this project is that we didnt have any existing XML documents to contend with; this advantage gave us complete freedom over the XML document design.

9.3.1 Menu Panel

The menu panel is the first HTML document a user sees. It looks like Figure 9-1 . Figure 9-1. Toot-O-Matic menu panel In this example, the string Building tutorials with the Toot-O-Matic and all section titles are JPEG graphics created with our stylesheets and extensions. If you mouseover a section title, its background color changes, as shown in Figure 9-2 . Figure 9-2. Mouseover effect for section titles In this sample, notice that the text of the menu item appears as a tooltip. This appearance is useful for sight-impaired users, and is consistent with the Web Accessibility Guidelines defined by the W3C.