Introduction to DocBook, Part II

Introduction to DocBook, Part II

So far, I have the file:

<?xml version="1.0" standalone="no"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"      "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<article class="journalarticle">

</article>

Except that since we’re doing an article, I have to change !DOCTYPE book to !DOCTYPE article.

However, this isn’t actually going to output any documents if I
feed it into the DocBook parsers. Or, more accurately, it would
output a blank document with XML header information. The first
thing we need to do is understand what’s actually in a DocBook
article. This requires a little jump over to DocBook:
The Definitive Guide’s <article> page.

I bet you’re itching to actually get past this theory and actually
do something. Notice the example at the end. If you’ve installed
your DocBook tools already, then do the following:

1. Copy the example code into a blank text file.
2. Add the XML tag at the top:

   <?xml version="1.0" standalone="no"?>
   

3. Save and exit the file. For example purposes, I’ve named mine:
   myfirst.docbook.

4. Move the file into a directory where things won’t get
   confused. I just made a “docbook” directory.

5. Change to that directory.
6. Type (adjusting document name as necessary):

   docbook2html myfirst.docbook

I get a whole bunch of errors after doing this, but at the end is
the word I really wanted to see:

Done.

There in my docbook directory
now is t1.html, which contains the example article in HTML format.

But that doesn’t really teach you how to work with the tags, so
back to our example. Let’s start by setting up information about
the article with the <art
icleinfo> tag. I like to make sure and put the
opening and closing tag in place before I do anything else, so my
file now looks like:

<?xml version="1.0" standalone="no"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"       "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<article class="journalarticle">
<articleinfo>

</articleinfo>

</article>

First, let’s set the author with the (you guessed it) <author> tag. Since this is XML, it’s never just as simple
as typing out the whole name. Instead, <author> has its own sub-requirements. I’m
going to keep this really simple and stick with <firstname> and <surname>, which gives me (now, use your own
name here, not mine!):

<author>
<firstname>Dee-Ann</firstname>
<surname>LeBlanc</surname>
</author>

Now I plug this into the <articleinfo> section and voila:

<?xml version="1.0" standalone="no"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"      "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<article class="journalarticle">
<articleinfo>
<author>
<firstname>Dee-Ann</firstname>
<surname>LeBlanc</surname>
</author>
</articleinfo>

</article>

Still nothing that will actually print out! So, is there any other
article information to include? Let’s just get to the exciting
stuff: adding article content. This could be as simple as adding
the following under </articleinfo>:

<para>This is my very first
DocBook article.</para>

Go through the steps I detailed above and check it out for
yourself.

Next week: We work on some REAL content …