Next / Previous / Contents / Shipman's homepage

5. Overall section structure

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

model.xml
<?xml version='1.0' encoding='utf-8'?>
<!DOCTYPE book
[ <!--Place entity declarations below-->
]
>
<article xmlns='http://docbook.org/ns/docbook' version='5.0'
    xmlns:xl='http://www.w3.org/1999/xlink'
    xml:lang='en'>
  <!-- Replace all fields ### below. Then delete this comment-->
  <info >
    <title >###
</title >
    <authorgroup >
      <author >
        <personname >
          <firstname >###
</firstname >
          <surname >###
</surname >
        </personname >
      </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 <link xl:href="###"
        >Web form</link > and also as a <link
        xl:href="###.pdf"
        >PDF document</link >.  Please
        forward any comments to <userinput
        >tcc-doc@nmt.edu</userinput >.
      </para>
    </abstract>
  </info >
  <section xml:id='intro'  >
    <info>
      <!-- On the next line, place the first section title.-->
        <title >###
</title >
    </info>
    <!-- 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 xml:id='intro'>
    <info>
      <title>Main section title</title>
    </info>
    <para>Main section content...</para>
    <section xml:id='sir-gawain'>
      <title>First subsection title</title>
      <para>First subsection content...</para>
    </section>
    <section xml: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 xml: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 : 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 >
  <info >
    <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>
      ...
  </info>
    ...
</article>