Table of Contents
For an overview of the basic structure of a DocBook article, please see the [ http://help.unc.edu/?id=4765#basic ]
Basic Document Structure section of the [ http://help.unc.edu/?id=4765 ]
KMT Styleguide. This document will cover in detail how to create sections and sub-sections, or nested sections, in DocBook XML. Nesting is accomplished by placing section elements within section elements, to any desired depth.
The simplest use of multiple sections in a DocBook article is with no nesting. In this case, each section element appears directly within the article element as in the following example:
Example 1. Example of Multiple Non-Nested Sections
<article>
<title>document title</title>
<section>
<title>section title</title>
<para>section text</para>
</section>
<section>
<title>section title</title>
<para>section text</para>
</section>
</article>
Following this pattern, you may create as many sections as you like. Since each section title will be automatically compiled into a table of contents at the top of the page, it is a good idea to create short, descriptive titles that will help the reader navigate through longer documents.
section elements may also be nested within other section elements as in this example:
Example 2. Example of Proper Nesting
<article>
<title>document title</title>
<section>
<title>section title</title>
<para>section text</para>
<section>
<title>section title</title>
<para>section text</para>
<section>
<title>section title</title>
<para>section text</para>
</section>
<section>
<title>section title</title>
<para>section text</para>
</section>
</section>
</section>
</article>
Note
Though each section title will be displayed as a title in the article, only the title from the outermost section will be compiled into the table of contents.
The most common mistake when nesting sections is made by placing content in the wrong part of the section. Content for a section may only be placed directly after the title element. The following example would generate an error:
Example 3. Example of Incorrect Nesting
<article>
<title>document title</title>
<section>
<title>section title</title>
<para>section text</para>
<section>
<title>section title</title>
<para>section text</para>
<section>
<title>section title</title>
<para>section text</para>
</section>
<section>
<title>section title</title>
<para>section text</para>
</section>
<para>This content is in the wrong place and will make your XML invalid!</para>
</section>
</section>
</article>
For additional information on the section element, see the official element declaration at [ http://help.unc.edu/?id= ]
http://www.docbook.org/tdg/en/html/section.html.
Document Overview
Tags: DocBook, XMLSubjects: Knowledge Management Tool (KMT)
Genre: Tutorial
Audience: Everyone
This work is licensed under a Creative Commons Attribution 3.0 United States License.
Copyright 2002-2007 The University of North Carolina at Chapel Hill.
This
work is licensed under a
Creative Commons Attribution 3.0 United States License.
