6. Element Reference

The following is a short and incomplete guide to the most commonly used DocBook elements. I'm adding to this list as I find I need the elements, so expect this section to grow and evolve over time. Keep in mind that I'm pretty new to this whole DocBook thing, too, and I cannot guarantee that I'm using all of the elements as intended. In other words: everything in this book may be wrong ;>

6.1. Article header elements

Any DocBook "article" should include an article header. The article header contains information such as the article title, author, revision history, abstract, and so forth.

6.1.1. Article header

artheader: the "artheader" element contains all of the other elements that make up the article header.

6.1.2. Article title

title: the "title" element contained in the article header defines the article title. So, if you're writing an article called 101 Stupid Ferret Tricks, your article header would look like this:

<article>
   <artheader>
      <title>101 Stupid Ferret Tricks</title>
   </artheader>

...

</article>

6.1.3. Author information

author is the element which contains all of your author-related information, including first name, surname, email address, organizational affiliation, etc. Each of these pieces of information is marked up separately within the "author" element, which might seem like a bit of a pain, but it's worth it. The more comprehensive the markup, the more we can do with the information when processing the document.

All that aside, here's an example of an article header that contains an author's first name, surname, organizational affiliation, and email address. Usually all you need is the name and email address, and there's other stuff you can add. For now, we'll keep it simple:

<article>
   <artheader>
      
      ...

      <author>
         <firstname>Deb</firstname>
         <surname>Richardson</surname>
         <affiliation>
            <orgname>Open Source Writers Group</orgname>
            <address>
               <email>deb@oswg.org</email>
            </address>
         </affiliation>
      </author>

      ...
   
   </artheader>

...

</article>

6.1.4. Revision information

Most technical documentation goes through a series of revisions as the writer improves and updates the document. In order that readers know which version of a document s/he is reading, technical documentation often includes a revision number and other information. In a DocBook article, the revision information is part of the article header, and is contained in the revhistory element. Here's an example:

<article>
   <artheader>

      ...

      <revhistory>

         <revision>
            <revnumber>0.1</revnumber>
            <date>19 June 1999</date>
            <authorinitials>dr - deb@oswg.org</authorinitials>
            <revremarks>
               First draft, incomplete
            </revremarks>
         </revision>

         <revision>
            <revnumber>0.2</revnumber>
            <date>20 Sept 1999</date>
            <authorinitials>dr</authorinitials>
            <revremarks>
               Updated section 14, added section 11.5
            </revremarks>
         </revision>
   
      </revhistory>

      ...

   </artheader>

...

</article>

6.1.5. Article abstract

Many people write abstracts for their articles, which are short summaries, usually no more than a paragraph long, that tell the reader just what the article is about. In a DocBook article, the abstract is part of the article header, contained in an abstract element.

<article>
   <artheader>

   ...

      <abstract>
         <para>
            This article describes the steps that are performed to boot
            the Linux kernel. While this kind of information is not
            relevant to the system's functionality, it's interesting to
            see how the different architectures bring the system up.
         </para>
      </abstract>

   ...

   </artheader>

...

</article>

6.2. Marking up code, filenames, commands, and the like

If you're doing computer-related documentation or writing, chances are that you're going to have to use code samples, filenames, commands, and other computer-centric things in your document. DocBook, being designed for doing technical documentation, provides tags for marking each of these up as a specific type of element.

6.2.1. Code samples

When you want to include a multiple-line code example in your document, you should use the programlisting tag. Here's an example that's part of a level 1 section:

<sect1>
<para>
Here's an example:
</para>

<programlisting>
if [ $# -eq 1 ]
then
  if [ ! -r $1 ]
  then
    echo Cannot read \"$1\".  Exiting. >&2
    exit 1
  fi
fi
</programlisting>

</sect1>

The programlisting tag is usually processed so the output will be rendered with all whitespace and formatting preserved, done in a fixed-width font, such as courier.

If you want to include an example of SGML, XML, or HTML in your document, you have to use a special bit of markup that tells the parser to ignore any tags it contains. This special bit of markup is a CDATA marker, the beginning of which appears directly after the programlisting start tag, and which ends just before the programlisting end tag:


<programlisting>
<![CDATA[

<html>
<head>
<title>Web Page Title</title>
</head>

<body bgcolor="#ffffff">
Web Page Content
</body>
</html>

]]>
</programlisting>

Note that the beginning of the CDATA marker is "<![CDATA[", and the end of the CDATA marker is "]]>". Any markup contained between the beginning and end bits of a CDATA marker will be ignored by the processing tools and treated as if it were just part of the regular text.

6.2.2. Filenames and directories

Appropriately enough, in DocBook you markup filenames with a filename tag. You mark up directories with the same tag, only by adding class="directory" as an attribute. For example:


<para>
When you install DocBook Tools a number of files are added to 
<filename class="directory">/usr/bin</filename>, including
<filename>db2html</filename>, and <filename>db2pdf</filename>.
</para>

6.2.3. Commands

When you want to mark up a command or command line, use the intuitively-named command tag. For example:


<para>
When you want to generate HTML output from your DocBook instance, use
the <command>db2html</command> command from the command line.
</para>

Often, commands include more than one part, some of which, in documentation, are actually "replaceable", meaning that they indicate something that can be replaced or modified by the user who is typing the command. For example:


<para>
When you want to generate HTML output from your DocBook instance, type
the following on the command line: <command>db2html
<replaceable>my-filename.sgml</replaceable></command>.
</para>

You can also mark up command options or flags separately as well.


<para>
If you want to generate HTML from your DocBook instance using a
different set of stylesheets, you can use the "-d" option on the command
line:
</para>

<programlisting>
<command>db2html <option>-d</option> </command>
</programlisting>

To Be Continued