[Prev] [Next]

Document Hierarchies

Contents:
Sets and Books
General-Purpose Sections
Reference Entries
Articles
Document Navigational Information

DocBook makes available several different document hierarchies and a large library of markup for the content of documents. In addition, it offers markup for various kinds of nonlinear information (such as hyperlinks). The following chapters explain how to choose and apply DocBook markup.

DocBook supports several choices of overall document hierarchy that give ``shape'' to a document:

• Books and Sets (collections of Books)

• Reference entries

• Articles

These structures can be used in combination. For example, a reference entry containing a command's ``man page'' information might exist in isolation and also appear in a higher-level structure.

Note that you are not constrained to using the top-level structures in DocBook; you can start an SGML document at any level of DocBook's structure, so long as your document element (top-level element) is reflected in the document type name in your DOCTYPE declaration. For example:

<!DOCTYPE Para PUBLIC "-//Davenport//DTD DocBook V3.0//EN">
<Para>
This is an extremely short document, consisting only of a 
single DocBook paragraph.
</Para>

1.1 Sets and Books

Sets and Books

The Set element is the highest possible document element in DocBook. It contains an optional Title and TitleAbbrev, an optional SetInfo (which can also contain Title), an optional ToC, two or more Books, and an optional SetIndex. Note that Set, Book, RefEntry, and Article each have their own containers for metainformation. In the case of Set, you should choose one place to store your Set title information: either directly in Set or inside SetInfo.

A typical Set might be structured as follows:

Set
Title
SetInfo
Book
Book
Book
SetIndex

The Book element is the level at which most DocBook documents start; even if your documents are delivered in a Set, you need not use Set unless you want to do processing on the Set markup.

The structure of Book is relatively complex, to allow for a variety of configurations of major Book components. The structure assumes that you will place elements such as ToC and Glossary where you want them to appear in the output flow of your document. Book's content model has three main segments, corresponding roughly to the traditional front matter, body, and back matter:

• At the beginning, Book can contain an optional Title and TitleAbbrev, an optional BookInfo (which can also indirectly contain Title and TitleAbbrev), an optional ToC, zero or more LoTs (lists of titles), and a mixture of zero or more Bibliography, Glossary, and Preface elements in any order. You should choose one place to store your Book title information: either directly in Book or inside BookInfo's BookBiblio element.

• The body of Book can contain Chapters followed by any number of References (collections of reference entries), References only, Parts only (which can contain lower-level components such as Chapters), or Articles only.

• At the end, Book can contain zero or more Appendices, a mixture of zero or more Bibliography and Glossary elements in any order, a mixture of zero or more Index and SetIndex elements in any order, zero or more LoTs, and an optional ToC.

Here is a diagram of a fairly typical Book:

Book
BookInfo
ToC
LoT for figures
LoT for tables
Preface
Chapter
Chapter
Chapter
Chapter
Reference
Appendix
Appendix
Glossary
Bibliography
Index

Books can have Chapters and Appendices grouped in Parts. Note that you can group Appendices into a Part simply by supplying a Part at the end of the other Book parts that contains only Appendices. You should not mix Chapters and Appendices in any one part, though the structure allows you to.

Book
BookInfo
Preface
Part
PartIntro
Chapter
Chapter
Part
PartIntro
Chapter
Chapter
Chapter
Part
PartIntro
Appendix
Appendix

A reference manual might be arranged like this:

Book
BookInfo
ToC
LoT
Preface
Reference
Reference
Reference
Reference
Appendix
Appendix
Appendix
Appendix
Index

Set and Book Metainformation

SetInfo and BookInfo allow you to supply document information (also known as metainformation) on Sets and Books, respectively. SetInfo allows you to choose whatever document information elements are appropriate and supply them in any order. BookInfo, by contrast, imposes an order on its subelements. It contains zero or more Graphics that illustrate or represent the topic of the Book, a required BookBiblio (which also imposes a strict internal order on its subelements), zero or more LegalNotices, and zero or more ModeSpecs for the storage of information associated with OLink linking elements.

While you can use LegalNotice as a generic container for many kinds of metainformation, it's better to try to store the information in one of the BookBiblio elements if an appropriate element, such as Copyright or ProductNumber, is available. BookInfo has an optional Contents attribute, which points to the list of IDs of the major components making up the Book.

BookBiblio is used in BookInfo and ArtHeader to supply information about a Book or article, and is also used in BiblioEntry to supply information about a cited work.

Set and Book Attributes

Set and Book have an optional FPI attribute, which can be used to supply a formal public identifier for the Set or Book. Book also has an optional Label attribute

Book Components

Appendix, Chapter, Index, Part, Preface, SetIndex, and Reference are components allowed inside Books. Bibliography and Glossary can appear as Book components and also as parts of Book components.

A Book's main body can be organized starting at one of two logical levels. It can contain Book components such as Chapters, Appendices, and References directly, or it can contain groups of those components organized in Parts.Part

The content model of Part is very broad: it contains an optional DocInfo, a Title, an optional TitleAbbrev, an optional PartIntro, and a mixture of one or more Appendices, Chapters, Bibliographies, Glossaries, Prefaces, RefEntries, and References, in any order. You should not, however, mix these components inappropriately when using Parts.Reference

Reference is a special-purpose component for grouping collections of RefEntries. References can be used, for example, to organize UNIX man pages into their traditional numbered sections. Reference contains an optional DocInfo, a Title, an optional TitleAbbrev, an optional PartIntro (which is also used in Parts), and one or more RefEntry elements. The Label attribute on Reference may have as its value a nonnumeric keyword (such as ``CMD''), rather than a number, for use in constructing formal object prefixes, page number prefixes, and so on.Preface

The content models of Preface, Chapter, and Appendix are similar. Preface contains an optional DocInfo, a Title, an optional TitleAbbrev, any number of object-level elements from the %divcomponent.mix; mixture, and optionally a group of Sect1s or SimpleSects or a group of RefEntries (so long as some content is present). A Book may have multiple Prefaces, for example, one containing an acknowledgments section and another containing a foreword; these may be distinguished by their titles. Even if you always have a single Preface and always want it to be titled ``Preface,'' you should supply Title text, as formatting applications are unlikely to generate it for you.Chapter

Chapter contains an optional DocInfo, a Title, an optional TitleAbbrev, an optional ToCchap for holding a Chapter-level table of contents, any number of object-level elements from the %divcomponent.mix; mixture, any number of Sect1, RefEntry, or SimpleSect elements (so long as at least some content is supplied), and zero or more Indices, Glossaries, and Bibliographies. Note that the choice of Sect1, RefEntry, or SimpleSect precludes using any of the others at the same level: directly inside any one chapter, you can organize your information only as formal sections, reference entries, or simple sections.Appendix

Appendix has the same content model as Chapter, except that it can't contain Index, Glossary, and Bibliography at the end.DocInfo

DocInfo contains metainformation for the Book component in which it appears. DocInfo is similar to BookInfo in that its contents have a fixed order: It contains zero or more Graphics that illustrate the component, a Title, an optional TitleAbbrev, an optional SubTitle, zero or more AuthorGroups, zero or more Abstracts, an optional RevHistory, and zero or more LegalNotices.

[Prev] Acknowledgments
[Next] General-Purpose Sections
[User's Guide Home] [Davenport Group Home]