5. Step by Step Example

Now we'll walk through the process of creating a simple DocBook article. This example includes some of the most commonly used DocBook elements, and is here mostly to show you what a document marked up with DocBook looks like.

If you're looking for a more complete list of DocBook elements and their uses, see the Element Reference, or Norman Walsh's DocBook: The Definitive Guide, available at http://www.docbook.org.

5.1. Step 1: Including the Document Type Declaration

Assuming that you're marking up an "article", the first thing you have to have in your document is the document type declaration:

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">

5.2. Step 2: Adding a "root" element

After that, you have to define the "root" element, which will contain all the other elements in your document. For an article, the root element is simply "article". So, add that, and its end tag after the document type declaration:

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
<article>

</article>

Everything else you add to your document will be contained within the "article" tags, so when you're done, the last tag in your document should be "</article>".

5.3. Step 3: Adding an article header

Next, you'll want to add some "header" information. Header information includes the article's title, the author's name and email address, the revision history of the document, and lots of other stuff. For now, we'll just add the article title and the author name.

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
<article>

<artheader>
   <title>How I Spent My Summer Vacation</title>
   <author>
      <firstname>Deb</firstname>
      <surname>Richardson</surname>
   </author>
</artheader>

</article>

5.4. Step 4: Adding a first level sectioin

So, now that we have some header information added, lets actually add some content in a level 1 section with a title:

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
<article>

<artheader>
   <title>How I Spent My Summer Vacation</title>
   <author>
      <firstname>Deb</firstname>
      <surname>Richardson</surname>
   </author>
</artheader>

<sect1>
<title>The Month of May</title>
<para>
My summer vacation started on May 14th, right after graduation.  Being a
new, unemployed, and highly-debt-ridden university graduate, I decided
that I should probably get a job.  I spent the vast majority of May
padding my resume with all sorts of impressive-sounding yet terribly
obscure skills and accomplishments, and sending those out to any company
whose name appeared in the phone book.
</para>
</sect1>

</article>

I think you're probably getting the hang of it at this point.

5.5. Step 5: Adding subsections and sub-subsections

Adding subsections and sub-subsections is also simple. A second level section starts and ends with "sect2" tags, third level with "sect3", and so on. The standard DocBook DTD only supports up to a level 5 section, so there are no "sect6", "sect7" or higher tags. Unless you're doing a massively long and professional book, however, you probably won't need more than 5 section levels.

Each section level should be contained within a higher level, so level 2 sections should be contained by level 1 sections, and so on. Here's an example:

<sect1>
<title>The Month of May</title>
<para>
My summer vacation started on May 14th, right after graduation.  Being a
new, unemployed, and highly-debt-ridden university graduate, I decided
that I should probably get a job.  I spent the vast majority of May
padding my resume with all sorts of impressive-sounding yet terribly
obscure skills and accomplishments, and sending those out to any company
whose name appeared in the phone book.
</para>

<sect2>
<title>My Resume</title>
<para>
My resume was 4 pages long, and mostly contained notes about my
education and employment history, which was sparse, at best.
</para>

<sect3>
<title>Employment History</title>
<para>
Most of the jobs I've ever had have been in the food service industry.
Like most aspiring writers, I spent most of my formative years wiping
tables and grumbling about lousy tips.
</para>
</sect3>

</sect2>

</sect1>

As you can see, this example ends with three end tags -- each section level is contained or "nested" within the higher level.