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.
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
.
book
with
bookinfo
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>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
.
article
with
articleinfo
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>Use chapter
to mark up your chapters.
Each chapter has a mandatory title
.
Articles do not contain chapters, they are reserved for
books.
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.
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
element.
The n
n
indicates the section number,
which identifies the section level.
The first
sect
is
n
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
.
This example includes section numbers in the section titles. You should not do this in your documents. Adding the section numbers is carried out by the stylesheets (of which more later), and you do not need to manage them yourself.
part
s introduce another level of
organization between book
and
chapter
with one or more
part
s. This cannot be done in an
article
.
This, and other documents, can be downloaded from http://ftp.FreeBSD.org/pub/FreeBSD/doc/
For questions about FreeBSD, read the
documentation before
contacting <questions@FreeBSD.org>.
For questions about this documentation, e-mail <doc@FreeBSD.org>.