5. Overall section structure

Here is the model file discussed in Section 3, “Setting up your directory for DocBook”:

model.xml

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
 "http://www.oasis-open.org/docbook/xml/4.3/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>
        <!--Place revision information here: RCS tags, etc.-->
        <revnumber>###</revnumber>
        <date>###</date>
      </revision>
    </revhistory>
    <abstract>
      <para>
        <!--All TCC documents must have an abstract.-->
        ###
      </para>
      <para>
        This publication is available in <ulink url="###"
        >Web form</ulink > and also as a <ulink
        url="###.pdf"
        >PDF document</ulink >.  Please
        forward any comments to <userinput
        >tcc-doc@nmt.edu</userinput >.
      </para>
    </abstract>
  </articleinfo >
  <section id='intro'  >
    <!-- On the next line, place the title of your first section.-->
    <title >###
</title >
    <!-- Add the body of your first section here.-->
  </section >
  <!--Place additional sections here.-->
</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 it.

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

For example:

  <section id='intro'>
    <title>Main section title</title>
    <para>Main section content...</para>
    <section id='sir-gawain'>
      <title>First subsection title</title>
      <para>First subsection content...</para>
    </section>
    <section id='sir-robin'>
      <title>Second subsection title</title>
      <para>Second subsection content...</para>
    </section>
  </section>

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

Important

You must invent a unique identifier for each section, and attach an id='I' attribute to the section element. You will use these identifiers to generate automatic internal cross-references in your document; see Section 8.1, “The link and xref tags: Linking within your document”. Identifiers may contain any combination of letters, hyphens (-), underbars (_), or digits.

To help you manage larger documents, there is a utility that displays all the section identifiers for one DocBook document in an outline format. See docbookindex: ID indexer for DocBook. As an example, here is the toc.pdf file showing all the section identifiers for this document.

You can include more section elements for sub-sub-sections, and so on.

5.1. The `titleabbrev` element: Short title

The title element inside your articleinfo group will appear in the running footer on every page in the PDF version of the document. If your title is too long, it will be folded into two or more lines inside the footer.

To cure this problem, place a titleabbrev element just after the main title element, containing a shorter version of the title that will fit inside the running footer. For example:

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
 "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
<article >
  <articleinfo >
    <title >
      Exegesis of archetypal content and pataphysical normatives in
      <citetitle >Monty Python and the Holy Grail</citetitle >
    </title >
    <titleabbrev >
      <citetitle >Monty Python</citetitle > and
      pataphysics
    </titleabbrev>
      ...
</article>

Writing documentation with DocBook-XML 4.3