XML Reference Guide

One of the advantages of XML is its flexibility, but in the wrong hands, that can also be a disadvantage. For example, if you were going to represent a graphic image using XML, you could create your own format, but why should you? Why not use Scalable Vector Graphics (SVG) instead, so your users can simply use the existing SVG viewer? Simiarly, writing a web page in HTML means that there are existing cleints (browsers) that can read it. But what about producing longer works? DocBook is designed for just such a situation.

Like XML, DocBook is based on Standard Generalized Markup Language (SGML). It's actually been around since before XML, but has subsequently been adapted to XML's peculiarities. Originally designed for book-length works, DocBook documents are easily converted to HTML, PDF, or other environments using transformative or stylistic technhologes such as Extensible Stylesheet Language Transformations (XSLT) or Cascading Style Sheets (CSS), and standard solutions for these processses exist from the army of developers dedicated to the standard.

Let's take a look at a sample DocBook document. We'll start by looking at the informational elements. For example, a DocBook document containing the content of XML Primer Plus might start with:

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<book>
<bookinfo>
   <title>XML Primer Plus</title>
   <author>
      <firstname>Nicholas</firstname>
      <surname>Chase</surname>
   </author>
   <copyright>
      <year>2002</year>
      <holder>Sams Publishing</holder>
   </copyright>
</bookinfo>
...
</book>

From there, we can add parts and chapters:

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<book>
<bookinfo>
  <title>XML Primer Plus</title>
  <author>
    <firstname>Nicholas</firstname>
    <surname>Chase</surname>
  </author>
  <copyright>
    <year>2002</year><holder>Sams Publishing</holder>
  </copyright>
</bookinfo>
<preface>
    <title>Introduction</title>
...
</preface>
<part>>
    <title>XML Fundamentals</title>
    <chapter>
        <title>Basic XML Document Structure</title>
        ...
    </chapter>
    <chapter>
        <title>Designing XML Documents and Applications</title>
        ...
    </chapter>
    <chapter>
        <title>Manipulating Documents: The Document Object Model (DOM)</title>
        ...
    </chapter>
...
</part>
<part>
    <title>Using XML</title>
    <chapter>
        <title>Browser-Based XML: Cascading Style Sheets (CSS)</title>
        ...
    </chapter>
    <chapter>
        <title>Browser-Based XML:  XHTML</title>
        ...
    </chapter>
    <chapter>
        <title>XML Linking Language (XLink)</title>
        ...
    </chapter>
...
</part>
<part>
    <title>Appendixes</title>
    <appendix>
        <title>Resources</title>
        ...
    </appendix>
    <appendix>
        <title>XML Information Set</title>
        ...
    </appendix>
    <appendix>
        <title>Questions and Answers</title>
        ...
    </appendix>
</part>
</book>

Now, within each of these chapters (or for that matter, within any sections that can contain content, such as the preface or an appendix) there are a myriad of useful elements that define the structure of the content. Perhaps the most commonly used would be the paragraph and section elements. For example:

...
    <chapter>
        <title>Designing XML Documents and Applications</title>
        <para>Before we actually build anything, let's look at 
planning the structure of the data. Yes, yes, I know, you're anxious to get 
your hands dirty, and so am I, but planning is an essential part of any 
applicaton and XML-related applications are no exception.  The structure 
of your documents is the underpinning for your entire system.  If you don't 
take the time to understand exactly what you're building, and more 
importantly, why you're building it, you're setting yourself up for failure.</para>
        <para>In this chapter, we're going to discuss the various 
aspects of planning for the data and structure ...</para>
        ...
        <sect1>
              <title>The Planning Process</title>
              <para>Because XML is inherenetly simple, the 
temptation is to simply create the structure as you go along, a process 
known as "designing at the keyboard."  As tempting as this may be, a 
multitute of reasons exists for avoiding it.</para>
              ...
        <sect1>
...
    </chapter>
...

In actuality, there are serveral types of sections. Here I've used sect1, which can contain one or more sect2s, which can contain one or more sect3s, and so on, up to sect5 (but no further). You can also use sections, which can be infinitely recursed, or simplesects, which can't contain any other sections.

There are also numerous elements for dealing with items such as lists, code sections, references, tables, and so on. In fact, there are so many elements that a leaner version of DocBook, Simplified DocBook, has been created to make things a bit simpler.

Simplified DocBook is meant for smaller peices, such as articles, but you can also create these smaller pieces in DocBook proper. For example, an article from InformIT might look like this:

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<article>
<articleinfo>
    <title>Using XML and XSLT to Personalize a Web Site Part 1</title>
    <subtitle>Using XSLT to Transform XML to HTML</subtitle>
    <author>
        <firstname>Norman</firstname>
        <surname>Walsh</surname>
    </author>
  <copyright>
    <year>2001</year><holder>Nicholas Chase</holder>
  </copyright>
</articleinfo>
<para>You might assume that adding the word "personalization" to 
your Web site means adding a digit or two to your budget, but it doesn't 
have to be that way. Personalization means creating a Web site that adjusts
to your visitors' preferences and interests, and to some extent, you can 
accomplish this with XML and XSL Transformations.</para>
...
<section>
    <title>The Basic Idea</title>
    <para>You may already be familiar with the way that Cascading 
Style Sheets (CSS) can be used to change the look and feel of your Web 
site. With CSS, you specify the way that you want certain items to look 
by creating styles for classes of items, or even for specific HTML tags. 
Changing the site's look and feel means simply changing the style sheet. 
The browser then carries the changes through to each affected page. In 
this way, the same HTML page can look profoundly different, depending 
on the style sheet chosen.</para>
    ...
</section>
...
</article>

Overall, you can see that DocBook provides a ready-made structure for information content. Check out the resoruces for more information on using DocBook in your own projects, particularly when it comes to transforming it into other formats.