4. Overall section structure

Here is the model file discussed in setting up your directory for DocBook:

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<article>
  <!-- Replace all fields ### below. Then delete this comment -->
  <articleinfo>
    <title>###
</title>
    <authorgroup>
      <author>
        <firstname>###
</firstname>
        <surname>###
</surname>
      </author>
    </authorgroup>
    <address><email>###
</email>
    </address>
    <revhistory>
      <revision>
        <revnumber>$Revision: 1.6 $</revnumber>
        <date>$Date: 2006/01/14 22:10:57 $</date>
      </revision>
    </revhistory>
  </articleinfo>
  <sect1>
    <!-- On the next line, place the title of your first section. -->
    <title>
    </title>
    <!-- Add the body of your first section here. -->
  </sect1>
  <!-- Place additional sections here with <sect1>...</sect1> tags. -->
</article>

Note the last few lines above. This is the skeleton of the first section of your document. Place the section's title inside the <title> element, and add the section's content after the closing </title> tag.

Each sect1 element is a top-level section. They will be numbered as sections 1, 2, 3, and so on. To add subsections, use a sect2 element inside the sect1 element. For example:

  <sect1>
    <title>Main section title</title>
    <para>Main section content...</para>
    <sect2>
      <title>First subsection title</title>
      <para>First subsection content...</para>
    </sect2>
    <sect2>
      <title>Second subsection title</title>
      <para>Second subsection content...</para>
    </sect2>
  </sect1>

If the main section were section 3, then the two subsections inside it would be numbered 3.1 and 3.2.

You can use sect3 elements for sub-sub-sections, and so on.

Instead of using sect1 for top-level sections, sect2 for subsections, and so on, you can instead use nested section elements. The above example could be structured like this:

  <section>
    <title>Main section title</title>
    <para>Main section content...</para>
    <section>
      <title>First subsection title</title>
      <para>First subsection content...</para>
    </section>
    <section>
      <title>Second subsection title</title>
      <para>Second subsection content...</para>
    </section>
  </section>

Writing documentation with DocBook-XML 4.2

4. Overall section structure