Jabber.org's Quick Guide to DocBook XML

Before any DocBook XML can be started, the document type must be stated:

<?xml version='1.0' encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
  "http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd">

The first line is standard for all XML documents; it specifies what version of XML the document is and what type of encoding the text is written in. The second and third lines specify that the document type is going to be an article and that we're using DocBook version 4.1.2. At the time of this writing, this is the most current version available.

The entire document must be wrapped within one main element. DocBook has several different main elements, depending on the size of the document. The most commonly used document type for Jabber documents is article. After the xxxx is stated, the actual DocBook elements can be started.

First some metadata must be specified. This usually includes information about the document title, author(s), contributors, and publication date. All of this information is inclosed with the articleinfo element.

The metadata for this document:

<articleinfo>
	<title>Jabber.org's Quick Guide to DocBook XML</title>

	<author>
		<firstname>Eliot</firstname><surname>Landrum</surname>
		<affiliation>
			<orgname>Jabber.org</orgname>
			<address>
                            <email>eliot@landrum.cx</email>
                        </address>
                </affiliation>
	</author>

	<pubdate>2001/12/14</pubdate>
</articleinfo>

				

Now the good stuff can begin! All text must be inclosed within sections. Each section is marked with, originally enough, the section element. Every section must have a title, marked with the title element. Sections can also have subsections, simply by inclosing section's inside other sections. All text must be inclosed within the section by para elements. Here's a simple section with an inclosed section:

<section>
	<title>Section 1</title>

	<para>This is section 1 with a nice little paragraph.</para>

	<section>
		<title>Section 1.1</title>

		<para>Here we have a subsection and the text of it.</para>
	</section>
</section>
				

You can link to various parts of the document by using the link element. First, you must specify an ID for the element which you would like to link to. Nearly all the elements in DocBook may have the ID attribute. Each ID must be unique. The following is an example of using the ID attribute and the link element:

<section id="section1">
	<title>Section 1</title>

	<para>This is section 1 with a nice little paragraph.</para>
</section>

<section id="section2">
	<title>Section 2</title>

	<para>This is section 2. <link linkend="section1">Section 1</link>
              provides more in depth information.</para>
</section>
				

To link to a URL, use the ulink element. Simply provide the URL in the url attribute:

<ulink url="http://www.jabber.org">Jabber.org</ulink>

A bulleted list:

<itemizedlist>

     <listitem>
          <para>Item 1</para>
     </listitem>

     <listitem>
          <para>Item 2</para>
     </listitem>

</itemizedlist>
				

A variable list (useful for any definition lists):

	    
<variablelist>
    <title>List of Variables</title>

        <varlistentry>
            <term>Jabber</term>
            <term>ICQ</term>
            <term>AIM</term>
            <listitem>
                <para>Instant messaging systems.</para>
            </listitem>
	</varlistentry>

	<varlistentry>
	    <term>DocBook XML</term>
	    <listitem>
                <para>A markup language for creating structured documents.</para>
            </listitem>
	</varlistentry>
</variablelist>
				

In DocBook there is no "bold" or "italic" formatting, instead, words are marked specific to what they mean. For instance, a command would be wrapped with the command element. Commonly used formatting elements are: wordasword, emphasis, varname, literal, filename and replaceable.

The simplest way is to add this processing instruction at the top of the document, right after the DOCTYPE has been declared:

<?xml-stylesheet type="text/xsl" href="docbook/html/docbook.xsl"?>
				

In the example, docbook/html/docbook.xsl is local to where the document is located on your hard drive. (docbook/html/docbook.xsl is in the downloadable package from Norman's web site.) After adding this processing directive, load the XML in an XSL-capable browser and the browser will do the transformation process. Unfortunatly, few web browsers are capable of this task. Supposedly, versions of Microsoft Internet Explorer greater than 5 can do it, but I was unable to get it to render DocBook XML document.

Using a browser to view the XML is excellent for quick proof-reading, but to output the data to formats available to a wider audience (HTML, RTF, PDF, etc.), an XSLT processor must be used. Many exist for many different platforms and languages.

I saved the best for last! There are lots of great XSLT engines for GNU/Linux as a quick search on Freshmeat.net will testify. I installed xsltproc from Debian because it was the first match on my search for XSLT. It installed quickly and is quite fast. For xsltproc, the syntax is simple (and quite similar to any other XSLT processor): xsltproc docbook/html/docbook.xsl infile.xml > outfile.html