9.4. Document Structure

9.4. Document Structure
Prev	Chapter 9. DocBook Markup	Next

DocBook allows structuring documentation in several ways. The FreeBSD Documentation Project uses two primary types of DocBook document: the book and the article.

Books are organized into chapters. This is a mandatory requirement. There may be parts between the book and the chapter to provide another layer of organization. For example, the Handbook is arranged in this way.

A chapter may (or may not) contain one or more sections. These are indicated with the sect1 element. If a section contains another section then use the sect2 element, and so on, up to sect5.

Chapters and sections contain the remainder of the content.

An article is simpler than a book, and does not use chapters. Instead, the content of an article is organized into one or more sections, using the same sect1 (and sect2 and so on) elements that are used in books.

The nature of the document being written should be used to determine whether it is best marked up as a book or an article. Articles are well suited to information that does not need to be broken down into several chapters, and that is, relatively speaking, quite short, at up to 20-25 pages of content. Books are best suited to information that can be broken up into several chapters, possibly with appendices and similar content as well.

The FreeBSD tutorials are all marked up as articles, while this document, the FAQ, and the Handbook are all marked up as books, for example.

9.4.1. Starting a Book

The content of a book is contained within the book element. As well as containing structural markup, this element can contain elements that include additional information about the book. This is either meta-information, used for reference purposes, or additional content used to produce a title page.

This additional information is contained within info.

Example 9.1. Boilerplate book with info

<book>
  <info>
    <title>Your Title Here</title>

    <author>
      <personname>
        <firstname>Your first name</firstname>
        <surname>Your surname</surname>
      </personname>

      <affiliation>
	<address>
          <email>Your email address</email>
	</address>
      </affiliation>
    </author>

    <copyright>
      <year>1998</year>
      <holder role="mailto:your email address">Your name</holder>
    </copyright>

    <releaseinfo>$FreeBSD$</releaseinfo>

    <abstract>
      <para>Include an abstract of the book's contents here.</para>
    </abstract>
  </info>

  …

</book>

9.4.2. Starting an Article

The content of the article is contained within the article element. As well as containing structural markup, this element can contain elements that include additional information about the article. This is either meta-information, used for reference purposes, or additional content used to produce a title page.

This additional information is contained within info.

Example 9.2. Boilerplate article with info

<article>
  <info>
    <title>Your title here</title>

    <author>
      <personname>
	<firstname>Your first name</firstname>
	<surname>Your surname</surname>
      </personname>

      <affiliation>
	<address>
	  <email>Your email address</email></address>
	</address>
      </affiliation>
    </author>

    <copyright>
      <year>1998</year>
      <holder role="mailto:your email address">Your name</holder>
    </copyright>

    <releaseinfo>$FreeBSD$</releaseinfo>

    <abstract>
      <para>Include an abstract of the article's contents here.</para>
    </abstract>
  </info>

  …

</article>

9.4.3. Indicating Chapters

Use chapter to mark up your chapters. Each chapter has a mandatory title. Articles do not contain chapters, they are reserved for books.

Example 9.3. A Simple Chapter

<chapter>
  <title>The Chapter's Title</title>

  ...
</chapter>

A chapter cannot be empty; it must contain elements in addition to title. If you need to include an empty chapter then just use an empty paragraph.

Example 9.4. Empty Chapters

<chapter>
  <title>This is An Empty Chapter</title>

  <para></para>
</chapter>

9.4.4. Sections Below Chapters

In books, chapters may (but do not need to) be broken up into sections, subsections, and so on. In articles, sections are the main structural element, and each article must contain at least one section. Use the sectn element. The n indicates the section number, which identifies the section level.

The first sectn is sect1. You can have one or more of these in a chapter. They can contain one or more sect2 elements, and so on, down to sect5.

Example 9.5. Sections in Chapters

<chapter>
  <title>A Sample Chapter</title>

  <para>Some text in the chapter.</para>

  <sect1>
    <title>First Section</title>

    …
  </sect1>

  <sect1>
    <title>Second Section</title>

    <sect2>
      <title>First Sub-Section</title>

      <sect3>
	<title>First Sub-Sub-Section</title>

	…
      </sect3>
    </sect2>

    <sect2>
      <title>Second Sub-Section (1.2.2)</title>

      …
    </sect2>
  </sect1>
</chapter>

Note:

Section numbers are automatically generated and prepended to titles when the document is rendered to an output format. The generated section numbers and titles from the example above will be:

1.1. First Section
1.2. Second Section
1.2.1. First Sub-Section
1.2.1.1. First Sub-Sub-Section
1.2.2. Second Sub-Section

9.4.5. Subdividing Using `part` Elements

parts introduce another level of organization between book and chapter with one or more parts. This cannot be done in an article.

<part>
  <title>Introduction</title>

  <chapter>
    <title>Overview</title>

    ...
  </chapter>

  <chapter>
    <title>What is FreeBSD?</title>

    ...
  </chapter>

  <chapter>
    <title>History</title>

    ...
  </chapter>
</part>

Prev	Up	Next
9.3. Formal Public Identifier (FPI)	Home	9.5. Block Elements