Pro PHP- Patterns, Frameworks, Testing and More

CHAPTER 6 ■ DOCUMENTATION AND CODING CONVENTIONS^63

The file layout is pretty simple. First, you need to create an XML file that will contain the

DocBook information. Like an HTML document, this file will contain elements and attributes.

The basic structure of a DocBook XML file is shown in Listing 6-3.

Listing 6-3. A Basic DocBook File

<?xml version="1.0" encoding="UTF-8" ?>

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"

"/usr/share/xml/docbook/schema/dtd/4.4/docbookx.dtd">

<book>

<bookinfo>

<title>Documentation</title>

<subtitle>Cool Application</subtitle>

</bookinfo>

<chapter>

<title>Chapter Title</title>

<sect1>

<title>Section Title</title>

<para>Introduction to this section</para>

<sect2>

<para>Sections may have subsections</para>

</sect2>

</sect1>

</chapter>

</book>

Listing 6-3 demonstrates some of the more basic DocBook tags. As you’ll notice, all DocBook

files must contain a DOCTYPE declaration, which is the version of DocBook your documentation

targets and the rules the file will follow. Next, you must define a root XML node, in this case,

book. Next, all books contain information, so the bookinfo node describes these attributes.

All books contain chapters, and those chapters are logically enclosed in chapter tags. You

may specify an unlimited number of chapters. Next, you can provide the chapter with a title.

Sections may be carved out of chapters, and even out of sections themselves. The sect1

element declares a first-level section. You can add subsections by nesting the sect1 through

sect5 tags. Inside sections or chapters, you can declare paragraphs with the para tag.

The example in Listing 6-3 is straightforward and intentionally basic. You can do a lot

more with DocBook, and we’ll get to that, but first let’s parse this file.

Parsing a DocBook File

To parse a DocBook file, you first need to install DocBook. You can do this in various ways

depending on your operating system. I suggest that you use a package manager to install

DocBook. For instance, on Debian, use the apt command:

McArthur_819-9C06.fm Page 63 Friday, February 22, 2008 8:59 AM