9.4. Document Structure
Prev | Chapter 9. DocBook Markup | Next

## 9.4. Document Structure

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 `chapter`s. This is a mandatory requirement. There may be `part`s 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 FreeBSD FAQ, and the FreeBSD 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 `bookinfo`.

Example 9.1. Boilerplate `book` with `bookinfo`
`<book>` `<bookinfo>` `<title>``Your Title Here``</title>` `<author>` `<firstname>``Your first name``</firstname>` `<surname>``Your surname``</surname>` `<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>` `</bookinfo>` … `</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 `articleinfo`.

Example 9.2. Boilerplate `article` with `articleinfo`
`<article>` `<articleinfo>` `<title>``Your title here``</title>` `<author>` `<firstname>``Your first name``</firstname>` `<surname>``Your surname``</surname>` `<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 article's contents here.``</para>` `</abstract>` `</articleinfo>` … `</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 `sect`n`` element. The `n` indicates the section number, which identifies the section level.

The first `sect`n`` 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

`part`s introduce another level of organization between `book` and `chapter` with one or more `part`s. 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

All FreeBSD documents are available for download at http://ftp.FreeBSD.org/pub/FreeBSD/doc/

Questions that are not answered by the documentation may be sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.