Introduction to DocBook, Part III

So far, I have the file:

<?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>
<para>This is my very first DocBook article.</para>
</article>

As usual, markup languages are really easier to follow if things
are indented within their container tags, so I’ll change this to:

  <articleinfo>
    <author>
      <firstname>Dee-Ann</firstname>
      <surname>LeBlanc</surname>
    </author>
  </articleinfo>
  <para>This is my very first DocBook article.</para>
</article>

Much better. Now I go back to the listing of how an article is
laid out at http://www.docbook.org/tdg/en/html/article.html … this lets me look at
the various elements I might want to use. Let me add just some
general text first:

  </articleinfo>
  <para>This is my very first DocBook article.</para>
  <para>Being a technical writer, I'm kind of anal about formatting. If I find myself listing steps, for example, then I'll often want to use a numbered list. For example, when writing a DocBook article, you have to: 1. Start with the XML version tag. 2. Add the DOCTYPE declaration. 3. Start the article container tag. 4. Fill in some article info. 5. Write the article. 6. Close the article.
</article>

This isn’t going to come out very pretty. How about I put the word
“anal” in Italics. To do this, I need the emphasis tag:

<para>Being a technical writer, I'm kind of <emphasis>anal</emphasis> about formatting.

Now, rather than having my numbered list embedded in the
paragraph, I want to break it up. For that, I need a procedure:

<?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>
  <para>This is my very first DocBook article.</para>
  <para>Being a technical writer, I'm kind of <emphasis>anal</emphasis> about formatting. If I find myself listing steps, for example, then I'll often want to use a numbered list. For example, when writing a DocBook article, you have to:</para>
  <procedure>
    <step><para>Start with the XML version tag.</para></step>
    <step><para>Add the DOCTYPE declaration.</para></step>
    <step><para>Start the article container tag. </para></step>
    <step><para>Fill in some article info. </para></step>
    <step><para>Write the article. </para></step>
    <step><para>Close the article.</para></step>
  </procedure>
</article>

Notice that I closed my paragraph before beginning the procedural
list. Also, I removed the manual numbering. Now let’s take a look
at what we have. Copy the text above into a document, say,
“mysecond.docbook.” Now:

$ docbook2html mysecond.docbook
Using catalogs: /etc/sgml/xml-docbook-4.2-1.0-17.cat
Using stylesheet: /usr/share/sgml/docbook/utils-0.6.12/docbook-utils.dsl#html
Working on: /home/dee/docbook/mysecond.docbook
Done.

View the HTML file and there it is, our nicely formatted article.

That wraps up your introduction to DocBook. Go forth and make
documentation!