XML Document Design

Now that we’ve covered how our tutorials appear in all their various forms, we’ll 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 panel’s contents.

This foundation creates an XML structure identical to the layout of our tutorials, so it was an obvious place to start.

Individual Panels

An individual panel has the following structure:

<panel>
  <title>Title of the panel</title>
  <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; it’s 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.

Get XSLT now with the O’Reilly learning platform.

O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.

Start your free trial